Water analysis

This function performs electroneutrality and property reconciliation calculations from incomplete and/or inaccurate water sample data based on ionic species input.

water analysis

POST https://api.olisystems.com/engine/flash/{dbs_file_id}/wateranalysis

run a water analysis calculation with anions, cations and nuetrals as input

Headers

Name	Type	Description
Authorization	string	Bearer {access_token}
Content-Type	string	application/json

200 Please look at "API call blueprint" page on how to obtain results

{
	"code": 200,
	"data": {
		"file_id": "dee854a6-59db-487d-ad08-a20dee691133",
		"jobId": "f6b3375e-cd0f-4ace-a5ee-71e047b76754",
		"resultsLink": "https://api.olisystems.com/result/flash/f6b3375e-cd0f-4ace-a5ee-71e047b76754?context=engine",
		"status": "IN PROGRESS"
	},
	"message": "Process execution started Successfully",
	"status": "SUCCESS"
}

Request payload

{
    "params": {
        "waterAnalysisInputs": [
            {
                "group": "Cations",
                "name": "NAION",
                "unit": "mg/L",
                "value": 100,
                "charge": 1
            },
            {
                "group": "Cations",
                "name": "KION",
                "unit": "mg/L",
                "value": 200,
                "charge": 1
            },
            {
                "group": "Cations",
                "name": "CAION",
                "unit": "mg/L",
                "value": 300,
                "charge": 2
            },
            {
                "group": "Anions",
                "name": "CLION",
                "unit": "mg/L",
                "value": 100,
                "charge": -1
            },
            {
                "group": "Anions",
                "name": "SO4ION",
                "unit": "mg/L",
                "value": 200,
                "charge": -2
            },
            {
                "group": "Anions",
                "name": "HCO3ION",
                "unit": "mg/L",
                "value": 300,
                "charge": -1
            },
            {
                "group": "Anions",
                "name": "ACETATEION",
                "unit": "mg/L",
                "value": 400,
                "charge": -1
            },
            {
                "group": "Neutrals",
                "name": "SIO2",
                "unit": "mg/L",
                "value": 100,
                "charge": 0
            },
            {
                "group": "Properties",
                "name": "Temperature",
                "unit": "°C",
                "value": 30
            },
            {
                "group": "Properties",
                "name": "Pressure",
                "unit": "atm",
                "value": 1.5
            },
            {
                "group": "Electroneutrality Options",
                "name": "ElectroNeutralityBalanceType",
                "value": "DominantIon"
            },
            {
                "group": "Calculation Options",
                "name": "CalcType",
                "value": "EquilCalcOnly"
            },
            {
                "group": "Calculation Options",
                "name": "CalcAlkalnity",
                "value": false
            },
            {
                "group": "Calculation Options",
                "name": "AllowSolidsToForm",
                "value": true
            }
        ]
    }
}

each entry in the params.waterAnalysisInputs follows a JSON format described below.

params.waterAnalysisInputs [ { } ]	type	description
group	string	Properties/Cations/Anions/Electroneutrality Options/Calculation Options
name	string	name of entity under the group
value	number/string	value of entity
unit	string	unit of entity
charge	number	charge of species if group is Cations/Anions

specifying temperature and pressure

{
    "group": "Properties",
    "name": "Temperature",
    "unit": "°C",
    "value": 30
},
{
    "group": "Properties",
    "name": "Pressure",
    "unit": "atm",
    "value": 1.5
}

units of temperature and pressure can be found here.

specifying volume

{
    "group": "Properties",
    "name": "Volume",
    "unit": "L",
    "value": 1.0
}

units of volume can be found here.

volume can only be specified when inflows are in concentration or molar concentration units. 1 L will be assumed when the volume is not specified.

specifying stream amount

{
    "group": "Properties",
    "name": "StreamAmount",
    "unit": "g",
    "value": 1000.0
}

Stream amount can be specified as units of mole or mass.

Stream amount cannot be specified when inflows are specified as concentration or molar concentration units.

specifying species inputs

The three types of species that can be specified in the water sample are "Cations", "Anions" or "Neutrals". Example input and description are given below.

{
    "group": "Cations",
    "name": "NAION",
    "unit": "mg/L",
    "value": 100,
    "charge": 1
}

key	value type	description
group	string	species type, i.e. "Cations", "Anions", or "Neutrals"
name	string	species name
unit	string	species composition units
value	number	species composition
charge	number	species charge

species composition unit types	units
concentration	mg/L, g/L, kg/m3, lb/ft3, lb/gal
molar concentration	mol/L, mol/m3, mmol/L, lbmol/ft3
mole	see Inflows input
mass	see Inflows input
mole fraction	see Inflows input
mass fraction	see Inflows input

name and charge can be retrieved using chemistry information call.

charge input is optional. A warning will be generated in the output if user input charge is inconsistent with the current chemistry model, and the chemistry model value will be used.

units for species input can be found here.

Electroneutrality options

Since the charge balance may not be conserved for the water sample data, OLI supports several options to reconcile the electroneutrality. Example input and description are given below.

{
    "group": "Electroneutrality Options",
    "name": "ElectroNeutralityBalanceType",
    "value": "DominantIon"
}

value	description
DominantIon	the species with the most charge contribution is added or removed
ProrateCations	all cations are added or removed proportionally w.r.t. original molar concentration
ProrateAnions	all anions are added or removed proportionally w.r.t. original molar concentration
Prorate	all cations or anions are added proportionally w.r.t. original molar concentration
AutoNACL	NAION or CLION is added
MakeupIon	a user-selected ion species is added or removed

if "MakeupIon" is selected, then an additional object is needed to specify the user-selected ion. See the example below.

{
    "group": "Electroneutrality Options",
    "name": "MakeupIonBaseTag",
    "value": "CAION"
}

Allowing solids to form

Users can specify whether to allow potential solids to form. To select excluding or including specified solid(s) to form, please refer to excluded/included solid species section in Optional Inputs.

{
    "group": "Calculation Options",
    "name": "AllowSolidsToForm",
    "value": true
}

Calculating alkalinity

Optionally the alkalinity of the solution can be computed. Example input and description are given below.

{
    "group": "Calculation Options",
    "name": "CalcAlkalnity",
    "value": true
},
{
    "group": "Calculation Options",
    "name": "AlkalinityPhTitrant",
    "value": "H2SO4"
},
{
    "group": "Properties",
    "name": "AlkalinityTitrationEndPointpH",
    "value": 4.5
}

group	name	type of value	description
Calculation Options	CalcAlkalnity	boolean	option to calculate alkalinity
Calculation Options	AlkalinityPhTitrant	string	name of pH titrant used in alkalinity measurement
Properties	AlkalinityTitrationEndPointpH	number	endpoint pH in alkalinity measurement

Property reconciliation type

Different property reconciliation types can be specified with the type specified in the value field. Example input and description are given below.

{
    "group": "Calculation Options",
    "name": "CalcType",
    "value": "EquilCalcOnly"
}

value	description
EquilCalcOnly	only perform equilibrium calculation without any property reconciliation
ReconcilePh	reconcile solution pH to a specified measured value by adjusting acid and base titrant amount
ReconcilePhAndAlkalinity	reconcile both pH and alkalinity to measured values by adjusting pH and alkalinity titrant amount
ReconcilePhAndAlkalinityAndTic	reconcile pH, alkalinity, and total inorganic carbon (TIC) to measured values by adjusting titrant amount
ReconcileCo2Gas	reconcile gas-phase CO2 content (mole %) to a measured value by adjusting CO2 amount

These options are described in more detail below.

Reconciling pH only

There is an option to only reconcile pH to a measured value. Example input and description are given below.

{
    "group": "Calculation Options",
    "name": "CalcType",
    "value": "ReconcilePh"
},
{
    "group": "Properties",
    "name": "pH",
    "value": 10
},
{
    "group": "Calculation Options",
    "name": "PhAcidTitrant",
    "value": "HCL"
},
{
    "group": "Calculation Options",
    "name": "PhBaseTitrant",
    "value": "NAOH"
}

group	name	value type	description
Calculation Options	CalcType	string	set to "ReconcilePh"
Properties	pH	number	measured pH
Calculation Options	PhAcidTitrant	string	pH acid titrant name
Calculation Options	PhBaseTitrant	string	pH base titrant name
Calculation Options	Titrant	string	single pH titrant name

Both PhAcidTitrant and PhBaseTitrant need to be specified; otherwise, Titrant needs to specified as a single pH titrant. The "value" field of the titrant object needs to be specified as the inflow name of the titrant species. The available inflow names in the chemistry model can be retrieved from chemistry information call under result.inflows.

Reconcile pH and alkalinity

Both pH and alkalinity may be reconciled simultaneously. In addition to the specifications of "Reconcile pH", measured alkalinity also needs to be specified. Example input and description are given below.

{
    "group": "Calculation Options",
    "name": "CalcType",
    "value": "ReconcilePhAndAlkalinity"
},
{
    "group": "Calculation Options",
    "name": "AlkalinityPhTitrant",
    "value": "H2SO4"
},
{
    "group": "Properties",
    "name": "AlkalinityTitrationEndPointpH",
    "value": 4.5
},
{
    "group": "Properties",
    "name": "Alkalinity",
    "unit": "mg HCO3/L",
    "value": 600
},
{
    "group": "Properties",
    "name": "pH",
    "value": 10
},
{
    "group": "Calculation Options",
    "name": "PhAcidTitrant",
    "value": "HCL"
},
{
    "group": "Calculation Options",
    "name": "PhBaseTitrant",
    "value": "NAOH"
}

group	name	type of value	description
Calculation Options	CalcType	string	set to "ReconcilePhAndAlkalinity"
Calculation Options	AlkalinityPhTitrant	string	inflow name of alkalinity pH titrant
Properties	AlkalinityTitrationEndPointpH	number	endpoint pH in alkalinity measurement
Properties	Alkalinity	number	measured alkalinity value

Units for alkalinity can be found here.

Reconcile pH, alkalinity, and TIC

This option allows reconciling measured pH, alkalinity, and total inorganic carbon (TIC) simultaneously. In addition to the specifications of "Reconcile pH and alkalinity", measured TIC also needs to be specified. Example input and description are given below.

{
    "group": "Calculation Options",
    "name": "CalcType",
    "value": "ReconcilePhAndAlkalinityAndTic"
},
{
    "group": "Properties",
    "name": "TIC",
    "unit": "mol C/L",
    "value": 0.1
},
{
    "group": "Calculation Options",
    "name": "AlkalinityPhTitrant",
    "value": "H2SO4"
},
{
    "group": "Properties",
    "name": "AlkalinityTitrationEndPointpH",
    "value": 4.5
},
{
    "group": "Properties",
    "name": "Alkalinity",
    "unit": "mg HCO3/L",
    "value": 5000
},
{
    "group": "Properties",
    "name": "pH",
    "value": 5
},
{
    "group": "Calculation Options",
    "name": "PhAcidTitrant",
    "value": "HCL"
},
{
    "group": "Calculation Options",
    "name": "PhBaseTitrant",
    "value": "NAOH"
}

group	name	value (type)	description
Calculation Options	CalcType	string	set to "ReconcilePhAndAlkalinityAndTic"
Properties	TIC	number	measured Total Inorganic Carbon

Units for TIC can be found here.

Reconcile gas-phase CO2 content

In this calculation option, CO2 is added to reach measured gas phase CO2 content, with the rest of the gas phase filled with CH4.

{
    "group": "Calculation Options",
    "name": "CalcType",
    "value": "ReconcileCo2Gas"
},
{
    "group": "Properties",
    "name": "CO2GasFraction",
    "unit": "mole %",
    "value": 5
}

group	name	type of value	description
Calculation Options	CalcType	string	set to "ReconcileCo2Gas"
Properties	CO2GasFraction	number	measured gas-phase CO2 content

Units for CO2GasFraction can be found here.

This option required CO2 and CH4 to be present in the chemistry model.

Response (status = PROCESSED)

{
    "code": 200,
    "data": {
        "result": {
            ...<snip>...
                "waterAnalysisOutput": {
                    "addedIonsToBalance": {
                    "values": {
                        "NASO4ION": 0.0,
                        "ACETATEION": 340.10765079501346,
                        "SO4ION": 0.0,
                        ...<snip>...
                    },
                    "unit": "mg/L"
                },
                "addedPhTitrants": [
                    {
                        "name": "NAOH",
                        "value": 7861.67985421445,
                        "unit": "mg/L"
                    }
                ],
                "alkalinity": {
                    "value": 4997.743719276631,
                    "unit": "mg HCO3/L"
                },
                "addedAlkalinityTitrant": {
                    "name": "ACETACID",
                    "value": 16960.960688946394,
                    "unit": "mg/L"
                },
                "addedTICTitrant": {
                    "name": "CO2",
                    "value": 4207.220494479175,
                    "unit": "mg/L"
                }
            }
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}

The output of this calculation is the stream output which is common result output for all OLI's flash calculations or an error. In addition to this output the result also contains the water analysis output information and can be conveniently retrieved from the data.result.waterAnalysisOutput object. A description of this object is given below.

data.result.waterAnalysisOutput	type	description
addedIonsToBalance	[valueObject with name]	ions that were added to maintain electronuetrality
addedPhTitrants	[valueObject with name]	amount of titrant added to reconcile pH
alkalinity	valueObject	calculated alkalinity value
addedAlkalinityTitrant	valueObject with name	amount of titrant to reconcile alkalinity
addedTICTitrant	valueObject with name	amount of titrant added to reconcile TIC

Survey Calculation

Survey calculation is supported for the variables below. Please refer to Survey calculation for explained input schema.

supported params.surveyInputs[{}].field

"/params/waterAnalysisInputs/i/value" where i is the index (0 based) of params.waterAnalysisInputs variable object to be surveyed