# 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

<mark style="color:green;">`POST`</mark> `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       |

{% tabs %}
{% tab title="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"
}
```

{% endtab %}
{% endtabs %}

### Request payload

```javascript
{
    "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.

| <p>params.waterAnalysisInputs </p><p><a href="/pages/-MKpla3yKkV7cet4Iee_">\[ { } ]</a></p> | 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

```javascript
{
    "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](/input-unit-set.md).

### specifying volume

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

units of **volume** can be found [here](/input-unit-set.md).

{% hint style="warning" %}
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.
{% endhint %}

### specifying stream amount

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

Stream amount can be specified as [units](/inflows-input.md#units-in-batch-systems) of mole or mass.

{% hint style="warning" %}
Stream amount cannot be specified when inflows are specified as concentration or molar concentration units.
{% endhint %}

### 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.

```javascript
{
    "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](/inflows-input.md#units-in-batch-systems) |
| mass                           | see [Inflows input](/inflows-input.md#units-in-batch-systems) |
| mole fraction                  | see [Inflows input](/inflows-input.md#units-in-batch-systems) |
| mass fraction                  | see [Inflows input](/inflows-input.md#units-in-batch-systems) |

{% hint style="info" %}
**name** and **charge** can be retrieved using [chemistry information](/group1/api-functions/chemistry-info.md) call.&#x20;
{% endhint %}

{% hint style="info" %}
**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.&#x20;
{% endhint %}

units for species input can be found [here](/input-unit-set.md).

### **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.

```javascript
{
    "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                                      |

{% hint style="warning" %}
if **"MakeupIon"** is selected, then an additional object is needed to specify the user-selected ion. See the example below.
{% endhint %}

```javascript
{
    "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](/optional-inputs.md).

```javascript
{
    "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.

```javascript
{
    "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.

```javascript
{
    "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.

```javascript
{
    "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   |

{% hint style="warning" %}
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](/group1/api-functions/chemistry-info.md) call under **result.inflows**.
{% endhint %}

#### 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.

```javascript
{
    "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](/input-unit-set.md).

#### 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.

```javascript
{
    "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](/input-unit-set.md).

#### 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.&#x20;

```javascript
{
    "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](/input-unit-set.md).

{% hint style="danger" %}
This option required CO2 and CH4 to be present in the chemistry model.
{% endhint %}

### Response (status = PROCESSED)

```javascript
{
    "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 ](/stream-output-json.md)which is common result output for all OLI's flash calculations or an [error](/error-output.md).  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](/terms-definition.md)] | ions that were added to maintain electronuetrality |
| addedPhTitrants                 | \[[valueObject with name](/terms-definition.md)] | amount of titrant added to reconcile pH            |
| alkalinity                      | [valueObject](/terms-definition.md)              | calculated alkalinity value                        |
| addedAlkalinityTitrant          | [valueObject with name](/terms-definition.md)    | amount of titrant to reconcile alkalinity          |
| addedTICTitrant                 | [valueObject with name](/terms-definition.md)    | amount of titrant added to reconcile TIC           |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation.md) 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 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devdocs.olisystems.com/group1/api-functions/wateranalysis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.