# Welcome to the OLI API documentation

### What are the OLI API(s) ?

The OLI API(s) lets the user run common OLI Calculations quickly and efficiently directly in the cloud, fully managed by OLI. They are exposed as http endpoints and the calculation specification can be passed in easy to understand JSON format. The result of the calculation is also obtained in the same format. This makes it a great choice for automation workflows and does not require the user to install any additional software for running the calculations.

This is OLI technology at its core level and the API backend computations you are accessing is the state of science in first-principles electrolyte thermodynamics. Simply put, you are using the best available technology for modeling electrolyte systems.

**Please contact OLI sales to create a cloud account to be able to use the OLI API(s).** 


# Basic workflow

There are essentially three basic steps to be followed to run a calculation using the cloud API(s)

1. Login request to the OLI Cloud authentication endpoint using user credentials. The JWT(JSON Web Token obtained in this step will be passed in the authorization header in all subsequent calls to the API)
2. Upload a chemistry model file (.dbs) to the upload endpoint and receive the file id.
3. Send a request to a specific calculation endpoint with required JSON input in body payload. The chemistry model file will be part of calculation endpoint URL
4. Poll on the results link obtained from step 2 until calculation is processed and result is obtained in JSON format

{% hint style="info" %}
Once a chemistry file is uploaded and a file id is obtained, it is not necessary to reupload the file again for subsequent calculations. Only the file id is needed
{% endhint %}

A basic block diagram of this calculation workflow is given below. Click on image to expand

![](https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MXxnmVUL3EWl6gd-QdH%2F-MXxyYxJUuwk0mHbeULo%2Fimage.png?alt=media\&token=66d18bfd-9016-4fc5-81c3-cefb352e3bfe)


# Authentication

The OLI API supports two authentication methods: **Bearer Tokens** and **API Keys**. Each serves distinct purposes and is suited for different use cases. This summary provides an overview of both methods, highlighting their advantages and best practices.

## **Bearer Tokens**

#### **Overview**

Bearer tokens are short-lived credentials obtained through authentication using a username and password. They are required to access API endpoints and are used to generate API keys.

#### **Key Characteristics**

* **Authentication Flow**: Requires a username, password, and client credentials to obtain the token.
* **Time-Limited**: Typically valid for 24 hours.
* **Usage**: Ideal for manual or interactive sessions where a user logs in to perform actions.
* **Rate-Limited**: The token generation process is subject to rate limits, ensuring fair usage and preventing abuse.

***

## **API Keys**

#### **Overview**

API keys are long-lived credentials generated by authenticated users. They are designed for automated scenarios, such as scheduled tasks or system-to-system communication.

#### **Key Characteristics**

* **Generated Using Bearer Tokens**: API keys are created via a dedicated endpoint after bearer token authentication.
* **Time-Limited**: Can have custom expiration dates to control their validity period.
* **Flexible**: Can be named for easy identification and managed (listed or deleted) through the API.
* **Usage**: Ideal for automated processes to reduce the need for frequent authentication.

***

## **Why Use API Keys for Automation?**

* **Reduced Transaction Overhead**:
  * Eliminates the need to repeatedly authenticate via bearer token, reducing login-related delays.
* **Rate Limitation Avoidance**:
  * Avoids frequent login attempts that are subject to rate limits, making it more suitable for high-frequency operations.
* **Custom Expiry**:
  * API keys can be configured with specific expiration dates to control access duration.
* **Scalability**:
  * Simplifies integration with applications that need persistent, secure access to the API.

***

### **Best Practices for Using API Keys**

1. **Set Expiry Dates**:
   * Use a reasonable expiration period to limit the exposure of compromised keys.
2. **Limit Active Keys**:
   * Each user can have up to 5 active keys. Regularly review and delete unused keys.
3. **Secure Storage**:
   * Store API keys securely. They are displayed only once during generation.
4. **Rotate Keys Periodically**:
   * Regularly replace keys to maintain security and minimize risk.

***

### **When to Use Which?**

* **Bearer Tokens**:
  * Best for **interactive sessions** or when initial authentication is required (e.g., generating API keys).
* **API Keys**:
  * Best for **automated systems** or when long-term access without frequent authentication is required.

By combining bearer tokens for initial authentication and API keys for ongoing automated operations, you can optimize security and performance while adhering to best practices.

***

### **Bearer Tokens**


# Bearer Token

The API uses OpenID Connect (OIDC) protocol to authenticate users. The user is issued a username and password from OLI, with which they can use obtain a **JWT** (JSON Web Token) based access token. **This token is then passed in the http headers to all the endpoints.**

## User Authentication

<mark style="color:green;">`POST`</mark> `https://auth.olisystems.com/auth/realms/api/protocol/openid-connect/token`

method returns JWT tokens on successful authentication with username and password

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| Content-Type | string | application/x-www-form-urlencoded |

#### Request Body

| Name        | Type   | Description  |
| ----------- | ------ | ------------ |
| username    | string | {user\_name} |
| password    | string | {password}   |
| grant\_type | string | password     |
| client\_id  | string | apiclient    |

{% tabs %}
{% tab title="200 " %}

```
{
    "access_token": "eyJhbGciOiJ...",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJI...",
    "token_type": "bearer",
    "not-before-policy": 1588002927,
    "session_state": "b0451c5f-5233-4404-b601-558253efe3a6",
    "scope": "oli_user_role"
}
```

{% endtab %}
{% endtabs %}

### Response description

| field                                   | type   | description                                            |
| --------------------------------------- | ------ | ------------------------------------------------------ |
| access\_token                           | string | JWT (JSON Web Token)                                   |
| expires\_in                             | number | token expiration time in seconds                       |
| refresh\_token\_expire&#x73;*\_*&#x69;n | number | refresh token expiration time in seconds               |
| refresh\_token                          | string | used to obtain a new JWT after the current one expires |

{% hint style="warning" %}
currently the **access\_token** is set to expire in 24 hours and the **refresh token** in 7 days.&#x20;
{% endhint %}

## Refreshing

<mark style="color:green;">`POST`</mark> `https://auth.olisystems.com/auth/realms/api/protocol/openid-connect/token`

method refreshes the access token using the refresh token obtained after login. This is needed when the access token expires.&#x20;

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| Content-Type | string | application/x-www-form-urlencoded |

#### Request Body

| Name           | Type   | Description      |
| -------------- | ------ | ---------------- |
| refresh\_token | string | {refresh\_token} |
| grant\_type    | string | refresh\_token   |
| client\_id     | string | apiclient        |

{% tabs %}
{% tab title="200 " %}

```
refresh_expires_in
```

{% endtab %}
{% endtabs %}


# API Keys

API keys provide a secure and flexible way to authenticate requests to the OLI API. They serve as an alternative to bearer tokens, allowing users to manage long-lived authentication credentials for various use cases. Here's an overview of API key functionality

This token can passed using the Authorization header to all endpoints

{% hint style="info" %}
This token can passed using the Authorization header to all endpoints
{% endhint %}

| Header Key    | Header Value       |
| ------------- | ------------------ |
| Authorization | `API-KEY <apiKey>` |

### **Features of API Keys**

1. **Generation**:
   * API keys can be generated by authenticated users via a [`POST` request.](/authentication/api-keys/generate-a-key)
   * Keys can be customized with a name and an optional expiry date (in epoch milliseconds).
2. **Management**:
   * A user can have up to **5 active API keys** at a time.
   * The list of active and deleted API keys can be retrieved via the [`GET` endpoint.](/authentication/api-keys/list-all-keys)
3. **Deletion**:
   * API keys can be deleted when no longer needed using the [`DELETE` endpoint.](/authentication/api-keys/delete-a-key)
   * Deleted keys are immediately invalidated.

### **Security Best Practices**

* **Use expiration dates** to limit the lifespan of API keys.
* Regularly **review and delete unused keys** to minimize security risks.
* Store API keys securely; they are only visible at the time of creation.


# Generate a Key

API keys are generated by making a `POST` request to the API key endpoint. Authentication via a bearer token is required to access this endpoint.

{% hint style="warning" %}
After generation a key cannot be retrieved in full, please ensure you make a copy of the key.
{% endhint %}

## Create a new API Key

<mark style="color:orange;">`POST`</mark> `https://api.olisystems.com/user/api-key`

**Headers**

| Name                                            | Value              |
| ----------------------------------------------- | ------------------ |
| Content-Type                                    | `application/json` |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>`   |

**Body (Optional)**

<table><thead><tr><th width="119">Name</th><th width="101" data-type="checkbox">Optional</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>true</td><td>string</td><td>A custom name for the API key (max 50 characters).</td></tr><tr><td><code>expiry</code></td><td>true</td><td>number</td><td>The expiration date of the API key, specified as an epoch timestamp in milliseconds.</td></tr></tbody></table>

**Example Request**

```json
{
  "name": "My API Key",
  "expiry": 1735689600000
}
```

**Example Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "code": 200,
  "data": {
    "apiKey": "gAAAAABnP7fAh9VNmiIkHlpLRMmDNduOCDls4rgdngQpqA0GDNQXipd2ljo4YmNec9K56kvPP5u6zfsEIVrQXD9C_ZInRmH7XZ9BpguHJgd2W2xJVqdZL_Rp6xHR6nb-T",
    "apiKeyId": "d0e13388-c3b8-4bd4-8361-4b699828cde6"
  },
  "message": "User API KEY. PLEASE make a copy. This key can not be retrieved again.",
  "status": "success"
}
```

{% endtab %}

{% tab title="400 - Invalid Date" %}

```json
{
  "status": "ERROR",
  "message": "Invalid expiry date. Expiry date is provided in milliseconds"
}
```

{% endtab %}

{% tab title="400 - Epoch Formatting" %}

```json
{
  "status": "ERROR",
  "message": "Invalid expiry date milliseconds",
}
```

{% endtab %}

{% tab title="400 - Too Many Keys" %}

```json
{
  "status": "ERROR",
  "message": "User api key exceeds allowed limit",
}
```

{% endtab %}
{% endtabs %}

####


# List All Keys

You can retrieve a list of all API keys (both active and deleted) linked to your account by making a `GET` request to the API key list endpoint.

<mark style="color:green;">`GET`</mark> `https://api.olisystems.com/user/api-key`

**Headers**

| Name                                            | Value            |
| ----------------------------------------------- | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>` |

**Example Response**

{% tabs %}
{% tab title="200" %}

```json
  {
  "code": 200,
  "data": [
  {
      "apiKey": "**********aBVUu1tg-T",
      "apiKeyId": "d1e13388-c3c8-4bd4-8361-4b698829cde6",
      "dateCreated": "Thu, 21 Nov 2024 22:44:16 GMT",
      "expiry": "Thu, 21 Nov 2024 23:43:43 GMT",
      "name": "Test Key",
      "status": "ACTIVE"
    }
  ],
  "message": "User's API_KEY information",
  "status": "success"
}

```

{% endtab %}
{% endtabs %}


# Delete a Key

The delete API key operation requires the `apiKeyId`, which can be retrieved using the **List API Keys** endpoint.

<mark style="color:red;">`DELETE`</mark>`https://api.olisystems.com/user/api-key/{apiKeyId}`

**Headers**

| Name                                            | Value            |
| ----------------------------------------------- | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>` |

**Example Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "message": "User API KEY successfully deleted"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "message": "No API key found with API Key ID"
}
```

{% endtab %}

{% tab title="500" %}

```json
{
  "status": "ERROR",
  "message": "Unexpected Error occurred.  Please Try again",
}
```

{% endtab %}
{% endtabs %}


# Generating chemistry model files

### What is a chemistry model file?

The chemistry model file contains the chemical components and the associated thermodynamic parameters that the user has selected for their system. The OLI Software database contains several thousand species and several hundred thousand parameters. The user will be interested in only a portion of these, and so a subset of this database to run the calculation. This "subset" is called the Chemistry Model. As the user chooses, for example NaCl, acetone and hexane as inflows, the software retrieves the relevant species and parameters and places them into this file. It has the extension of **.dbs** or **.pkg.** The file is updated each time a new component is added or if one is removed. The chemistry model file essentially encapsulates all of the chemistry data based on the chosen thermodynamic framework, inflows and other settings.&#x20;

### Generating a chemistry model file

In order to run any of the OLI calculations right now the user needs to first obtain a chemistry model file. Currently, the chemistry model files can be generated using one of the following methods:&#x20;

<table><thead><tr><th width="185">API Suite</th><th width="263">Chemistry Generation Method</th><th>File Extension</th></tr></thead><tbody><tr><td>OLI Engine API</td><td><ol><li>ChemBuilder API</li><li>OLI Studio Export</li><li>OLI Chemistry Wizard</li></ol></td><td>.dbs</td></tr><tr><td>OLI Corrosion API</td><td><p></p><ol><li>ChemBuilder API</li><li>OLI Studio Export</li><li>OLI Chemistry Wizard</li></ol></td><td>.dbs</td></tr><tr><td>OLI Process API</td><td><ol><li>OLI Flowsheet:ESP Export </li><li>Direct Upload from OLI Flowsheet:ESP </li></ol></td><td>.pkg</td></tr><tr><td>OLI ScaleChem API</td><td><ol><li>ChemBuilder API</li><li>OLI ScaleChem Export</li><li>OLI Chemistry Wizard</li></ol></td><td>.dbs or .pkg</td></tr></tbody></table>

{% hint style="info" %}
**Note:** The OLI ScaleChem API calculation may require multiple .dbs files. In these instances, the files should be compressed into a single .zip archive, renamed with a .pkg extension, and uploaded to the ScaleChem chemistry upload endpoint.
{% endhint %}


# ChemBuilder API

### What is Chemistry Builder Cloud API ?

The Chemistry Builder API is a new addition to OLI's cloud services, designed to integrate smoothly with other OLI cloud products. It simplifies the process by allowing users to generate chemistry model files directly in the cloud, eliminating the need for manual creation and upload of .dbs files through OLI's desktop applications.

The Chemistry Builder Cloud API requires a JSON file containing essential chemistry data. This file can be generated either programmatically via Chemistry Builder Query APIs or manually from a JSON template. For programmatic creation, users first gather data on inflows, kinetics, or redox through Query APIs, then merge these details into one JSON file. The ChemBuilder Query API offer comprehensive lists of default settings and permissible user selections.


# Getting Started with ChemBuilder

### Here is an example DBS file generation request.

Here is a request to generate a DBS file using a sample JSON file. The JSON file should list all the required fields.

## Run a sample case using .DBS file

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/channel/dbs`&#x20;

Run **.dbs** file generation&#x20;

#### Headers

| Name                                            | Type   | Description              |
| ----------------------------------------------- | ------ | ------------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {{access\_token}} |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json         |

{% tabs %}
{% tab title="200: OK  " %}

```json
{
    "data": {
        "fileName": "testModel.dbs",
        "id": "12345a67e89123" 
    },
    "message": "DBS file generated successfully",
    "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}

### JSON Request Payload Format:

```json
  {
      "params": {
        "thermodynamicFramework": "MSE (H3O+ ion)",
        "modelName": "testModel",
        "privateDatabanks": []
      "phases": [
        "liquid1",
        "vapor",
        "solid", 
        "liquid2"
      ],
        "inflows": [
            {
                "name": "H2O"
            },
            {
                "name": "NACL"
            }
        ]
    }
}
```

### Field description

<table><thead><tr><th width="251.51898734177217">params</th><th width="98" align="center">required</th><th width="143" align="center">type</th><th>description</th></tr></thead><tbody><tr><td>thermodynamicFramework</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String </td><td><p>OLI Thermodynamic Framework.</p><p><br>Options: <br>Aqueous (H+ ion) <br>MSE-SRK (H3O+ ion) <br>MSE (H3O+ ion)</p></td></tr><tr><td>privateDatabanks</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td align="center">Array of String</td><td>Array of Private Data Bank Codes.<br><br>e.g. <br>["COR","CER"]</td></tr><tr><td>modelName </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String</td><td>Name of the Generated DBS File in OLI Cloud.</td></tr><tr><td>phases</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of String</td><td><p></p><p>Array of Strings Defining Included Phases:</p><ul><li>"liquid1"</li><li>"solid"</li><li>"vapor"</li><li>"liquid2"</li></ul></td></tr><tr><td>inflows </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of Object</td><td><p>The Array of JSON Objects Containing Valid Species Identities:</p><ul><li>{"name": "CO2"}</li><li>{"name": "HSION"}</li></ul></td></tr></tbody></table>

{% hint style="warning" %}
The '**liquid1**' phase must always be included in the 'phases' array.
{% endhint %}

### Example Program Demonstrating DBS Generation Process

> Incorporate the following example in conjunction with the OLIAPI class provided in the [Quickstart example](/quickstart).

```python
if __name__ == "__main__":
    oliapi = OLIApi("username", "password")  # TODO : Update username and password
    if oliapi.login():
        # Create a input JSON for .dbs file creation
        dbs_data = {
            "params": {
                "thermodynamicFramework": "MSE (H3O+ ion)",
                "modelName": "testModel",
                "phases": [
                    "liquid1",
                    "vapor",
                    "solid",
                    "liquid2"
                ],
                "inflows": [
                        {
                            "name": "CO2"
                        },
                        {
                            "name": "H2S"
                        },
                        { 
                            "name": "SIO2"
                        }, 
                        { 
                            "name": "BOH3" 
                        }, 
                        {
                            "name": "NAION"
                        }, 
                        { 
                            "name": "KION"
                        }, 
                        { 
                            "name": "CAION"
                        }, 
                        { 
                            "name": "MGION"
                        }, 
                        { 
                            "name": "SRION"
                        }, 
                        { 
                            "name": "BAION"
                        }, 
                        { 
                            "name": "FEIIION"
                        }, 
                        { 
                            "name": "CLION"
                        }, 
                        { 
                            "name": "SO4ION"
                        }, 
                        { 
                            "name": "HCO3ION"
                        }, 
                        { 
                            "name": "HSION"
                        }, 
                        { 
                            "name": "ACETATEION"
                        }
                    ]
            }
        }

        # Invoke the Chemistry Builder Function in the OLI Wrapper.
        result = oliapi.generate_chemistry_file("chemistry-builder", "", dbs_data)
        print(json.dumps(result, indent=2).encode('utf8'))

        chemistry_file_id = result["data"]["id"]
        print(f'chemistry fileid: {chemistry_file_id}')
```

### Response (status = SUCCESS)

```json
{
    "data": {
        "fileName": "testModel.dbs",
        "id": "079e5204-d88f-41d9-a90d-07211c1e4ef1",
        "metadata": {
            "executionTime": {
                "unit": "ms",
                "value": 855.0
            },
            "versionInfo": {
                "fullVersion": "11.5.1.9"
            }
        }
    },
    "message": "DBS file generated successfully",
    "status": "SUCCESS"
}
```

Upon successful generation of the chemistry file, the result output will include the Chemistry file ID, retrievable from the data.id field.

### Save and Reuse the Output Chemistry File ID

The Chemistry Builder saves the chemistry model file on the cloud server upon successful execution, returning a file ID to the user. The file ID format resembles this example: `079e5204-d88f-41d9-a90d-07211c1e4ef1`

Regenerate a chemistry model file only if the new calculation employs a different thermodynamic framework or if there are changes in chemical composition, allowed phases, redox conditions, or kinetics.

{% hint style="info" %}
A chemistry model file can be reused in calculations as long as the chemistry remains unchanged.
{% endhint %}

### Delete Chemistry File

You can delete your DBS files by providing the file ID. For more information, please refer to the '[delete-file](/additional-functions/delete-file)' documentation.


# Set Thermodynamic Framework

In the OLI Platform, there are three thermodynamic frameworks: Aqueous (H+ ion), MSE (H3O+ ion), and MSE-SRK (H3O+ ion). Users can select the framework that best suits their chemistry.<br>

| framework          | JSON string value  | description                                     |
| ------------------ | ------------------ | ----------------------------------------------- |
| Aqueous (H+ ion)   | Aqueous (H+ ion)   | Aqueous                                         |
| MSE (H3O+ ion)     | MSE (H3O+ ion)     | Mixed Solvent Electrolyte                       |
| MSE-SRK (H3O+ ion) | MSE-SRK (H3O+ ion) | Mixed Solvent Electrolyte – Soave Redlich-Kwong |

{% hint style="warning" %}
The thermodynamic framework is a mandatory field, and its value must exactly match the data in the 'JSON string value' column.
{% endhint %}

The thermodynamic framework JSON string is a unique value comprising the official name of the thermodynamic framework. This name aligns with those used in OLI Studio, accessible via OLI Studio -> Chemistry -> Model Options -> Databanks. Public databanks associated with a framework are automatically loaded upon selection of a thermodynamic framework.&#x20;

Here is an example of the thermodynamic framework field:

```json
"thermodynamicFramework": "MSE (H3O+ ion)"
```


# Include Private Databanks

Private databanks enable users to incorporate a diverse range of species not present in the default OLI databases. If a species exists solely in a user's private databank or a supplemental OLI databank , the user must provide this data to ensure the species is accurately included in the analysis.&#x20;

Private databanks are associated with specific thermodynamic frameworks. First, a thermodynamic framework must be selected. Then, a list of the private databank codes to be used is specified as a JSON array. A private databank code typically consists of the first three letters of the private databank name in uppercase. To verify the validity of a databank code, users are encouraged to call the [databank query method](/chemistry-model-files/chembuilder-api/chembuilder-query/databank-query) to obtain a list of supported private databank codes.

{% hint style="info" %}
"**privateDatabanks**" is an optional field in the JSON input file.
{% endhint %}

Here is an example with multiple private databanks selected:

> ```json
> "privateDatabanks": ["EXC", "COR"], # ion exchange and corrosion in Aqueous model
> ```

Here is an example without any private databanks specified:

> ```json
> "privateDatabanks": [], # No private databanks used;
> ```


# Include Inflows

The "inflow" field is utilized to select all the species necessary to construct a chemistry model file. This field is mandatory, and all input species must be included in the public or private databank selected with the thermodynamic framework. To verify if a species exists in a thermodynamic framework and its associated databanks, use the [Species Query](/chemistry-model-files/chembuilder-api/chembuilder-query/species-query) method and check if the species are listed in the output array.&#x20;

The "inflows" field is an array of JSON objects containing a valid list of species. The order in which species are added is not significant, and specific species can be enabled or disabled as needed using the "enabled" switch.&#x20;

Here is an example of the "inflows" field:

```json
"inflows": [
    {
        "name": "H2O"
    },
    { 
        "name": "NACL"
    }, 
    { 
        "name": "BENZENE",
        "enabled": false
    } 
]
```

{% hint style="info" %}
[Assays ](/chemistry-model-files/chembuilder-api/getting-started-with-chembuilder/include-inflows/include-assays)and [PseudoComponents ](/chemistry-model-files/chembuilder-api/getting-started-with-chembuilder/include-inflows/include-pseudocomponent)are also considered inflow species. For further details, please refer to the respective subpages.
{% endhint %}

{% hint style="danger" %}
Only OLI tags are permitted in the inflow. Please refer [Species Query](/chemistry-model-files/chembuilder-api/chembuilder-query/species-query)to retrieve the OLI tags for each species. OLI tags should always be written in uppercase.
{% endhint %}

{% hint style="info" %}
"H2O" will always be automatically included as an inflow species by default.
{% endhint %}


# Include Assays

To include assays in the inflow, users must define additional JSON objects containing `"type": "assay"`. Users can provide a custom name for the assay "name" field.&#x20;

Below is a sample input to add an assay to the inflow:

```json
{       
         "inflows": [
            {
                "name": "H2O"
            },
            {
                "name": "test",
                "type": "assay",
                "data": {
                    "assayDataType": "ASTM D1160",
                    "thermoMethod": "API-8",
                    "assayBulkDensity": {
                        "type": "Specific Gravity",
                        "value": 0.769
                    },
                    "distillationCurveCuts": 7,
                    "distillationData": {
                        "temperatureUnit" : "°C",
                        "data": [
                        {
                            "volumePercentDistilled": 5,
                            "temperature": 68.7
                        },
                        {
                            "volumePercentDistilled": 10,
                            "temperature": 105.7
                        },
                        {
                            "volumePercentDistilled": 20,
                            "temperature": 171.9
                        },
                        {
                            "volumePercentDistilled": 30,
                            "temperature": 235.8
                        },
                        {
                            "volumePercentDistilled": 40,
                            "temperature": 295
                        },
                        {
                            "volumePercentDistilled": 50,
                            "temperature": 350.3
                        },
                        {
                            "volumePercentDistilled": 60,
                            "temperature": 405.3
                        },
                        {
                            "volumePercentDistilled": 70,
                            "temperature": 462.5
                        }
                    ]
                }
            }
        }
    ] 
 }   
    

```

The assay object consists of three keys: "name", "type", and "data".

<table><thead><tr><th align="center">assay</th><th width="151" align="center">required</th><th width="120">type</th><th>description </th></tr></thead><tbody><tr><td align="center">name</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td>String</td><td>A name provided by the user for this input assay.</td></tr><tr><td align="center">type</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td>String</td><td>This field is used to specify the type of inflow (e.g., "assay" or "pseudo").</td></tr><tr><td align="center">data</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td>JSON Object </td><td>This field contains the user-defined input for an assay.</td></tr></tbody></table>

The "data" section has the following keys:

| data                  |       required       | type        |
| --------------------- | :------------------: | ----------- |
| assayDataType         | :heavy\_check\_mark: | String      |
| thermoMethod          | :heavy\_check\_mark: | String      |
| assayBulkDensity      | :heavy\_check\_mark: | JSON Object |
| distillationCurveCuts | :heavy\_check\_mark: | Integer     |
| distillationData      | :heavy\_check\_mark: | JSON Object |

## A few key points to remember are:

{% hint style="info" %}
The "type" must be specified as either "assay" or "pseudo". Otherwise, the species is treated as a regular inflow species.
{% endhint %}

{% hint style="info" %}
The supported thermodynamic methods include `API-8`, `API-5`, `Cavett`, and `Kessler`.
{% endhint %}

{% hint style="info" %}
The supported density types include `Specific Gravity`, `API Gravity`, and `Watson K`.
{% endhint %}

{% hint style="info" %}
The supported thermo methods are`ASTM D1160`, `ASTM D86, ASTM D2887,` and

`TBP Curve.`
{% endhint %}

{% hint style="danger" %}
The number of distillation data points must be greater than 4.
{% endhint %}

{% hint style="danger" %}
The maximum temperature allowed is 923.15 K.&#x20;
{% endhint %}

{% hint style="danger" %}
The distillation data for temperature and volume percent must be entered by the user in ascending order.
{% endhint %}

{% hint style="info" %}
The assay object and its associated input JSON object can be enabled or disabled using ["enabled" Keyword](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/enabled-keyword)
{% endhint %}


# Include Pseudocomponent

Individual pseudocomponents with specific properties can be added to the inflow if distillation data is unavailable. The "type" must be set as "pseudo" to add a pseudocomponent JSON object. Users can customize the pseudocomponent name using the "name" field.

Below is a sample input to add a pseudocomponent to the inflow:

```json
{ 
	"inflows": [
	{
	     "name": "H2O"
	}, 
    	{
            "name": "PSEUDOAA",
            "type": "pseudo",
            "enabled": true,
            "data": {
		"thermodynamicMethod": "API-8",
		"normalBoilingPoint": {
			"unit": "°C",
			"value": 69.0,
			"enabled": true
		},
		"specificGravity": {
			"value": 1.2,
			"enabled": false
		},
		"molecularWeight": {
			"value": 86.0,
			"enabled": true
		},
		"criticalTemperature": { 
			"value": 379,
			"unit": "°C",
			"enabled": true
		},  
		"criticalPressure": { 
			"unit": "atm",
			"value": 217,
			"enabled": true
		}, 
		"criticalVolume": { 
			"unit": "L", 
			"value": 0.057,
			"enabled": true
		}, 
		"acentric": { 
			"value": 0.34,
			"enabled": true
		}
		}
	    } 
	]	
} 
```

<table><thead><tr><th width="182" align="center">Pseudocomponent</th><th width="152" align="center">required</th><th width="133">type</th><th>description</th></tr></thead><tbody><tr><td align="center">name</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td>String</td><td>A name provided by the user for this input assay.</td></tr><tr><td align="center">type</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td>String</td><td>This field is used to identify the type of inflow. Allowed values include "assay" or "pseudo".</td></tr><tr><td align="center">data</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td>JSON Object</td><td>Contains the user-defined input for an assay.</td></tr></tbody></table>

### Optional Properties

| data                | required | type        |
| ------------------- | :------: | ----------- |
| thermodynamicMethod |    :x:   | String      |
| normalBoilingPoint  |    :x:   | JSON Object |
| specificGravity     |    :x:   | JSON Object |
| molecularWeight     |    :x:   | JSON Object |
| criticalTemperature |    :x:   | JSON Object |
| criticalPressure    |    :x:   | JSON Object |
| criticalVolume      |    :x:   | JSON Object |
| accentric           |    :x:   | JSON Object |

## A few key points to remember are:

{% hint style="info" %}
The "type" must be specified as either "assay" or "pseudo". Otherwise, the species is treated as a regular inflow species.
{% endhint %}

{% hint style="info" %}
The supported thermodynamic methods are `API-8`, `API-5`, `Cavett`, and `Kessler`.
{% endhint %}

{% hint style="info" %}
A minimum of 2 of the folllowing properties "`normalBoilingPoint`", "`specificGravity`", and "`molecularWeight`" are required.
{% endhint %}

{% hint style="info" %}
All supercritical properties are optional and can be disabled.
{% endhint %}

{% hint style="info" %}
The pseudo object and its associated input JSON object can be enabled or disabled using ["enabled" Keyword](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/enabled-keyword)
{% endhint %}


# Choose Phases

The "Phases" field is utilized to select the phases expected to form in the system. This field is an array of strings and must include the "aqueous (liquid1)" phase at a minimum. It is required for chemistry file generation, and the selected phases impact the chemistry model.&#x20;

Below is an example of the "Phases" field:

```json
{
    "params": {
    "thermodynamicFramework": "Aqueous (H+ ion)", 
    "modelName": "testModel",
      "phases": [
        "liquid1",
        "vapor",
        "solid", 
        "liquid2"
      ],
        "inflows": [
            {
                "name": "H2O"
            },
            {
                "name": "NACL"
            }
        ]
    }
}
```

| phase   | value   |
| ------- | ------- |
| aqueous | liquid1 |
| vapor   | vapor   |
| solid   | solid   |
| organic | liquid2 |

Here are the requirements and assumptions you need to be aware of:

1. For DBS file generation, the "phases" field must be explicitly entered by the user and cannot be left empty (e.g., `"phases":[]` is incorrect).
2. The aqueous phase or "liquid1" phase should always be specified (e.g., `"phases": ["vapor", "solid"]` is incorrect).
3. The order or sequence of phase names does not matter.
4. Duplicate phase names are not allowed (e.g., `"phases": ["liquid1", "liquid1", "vapor", "solid"]` is incorrect).
5. In the Aqueous and MSE-SRK models, the vapor phase is required to model the organic phase. Thus, the vapor phase will be automatically selected by default if the organic phase is enabled.
6. In query methods, if a user doesn't specify any phases explicitly, "liquid1" or aqueous phase, "vapor", and "solid" will be enabled by default. The "liquid2" or organic phase is not included.


# Specify Model Name

This keyword is used to specify the name of the output file. It is a required field, and when correctly specified, the output chemistry model file generated on the cloud storage will carry this user-defined name. \
\
In the example below, the generated .dbs file will be named "tutorial.dbs".<br>

```json
"modelName": "tutorial"
```


# Choose Redox

Redox offers the capability to specify all oxidation states for a chemical element. A sample code featuring a Redox field is available below.

```json
{
  "params": {
    "thermodynamicFramework": "MSE (H3O+ ion)",
    "modelName": "testModel",
    "phases": [
      "liquid1",
      "vapor",
      "solid",
      "liquid2"
    ],
    "inflows": [
      {
        "name": "H2O"
      },
      {
        "name": "NACL"
      },
      {
        "name": "UREA"
      },
      {
        "name": "NH3"
      },
      {
        "name": "CO2"
      },
      {
        "name": "CACO3"
      },
      {
        "name": "Benzene"
      },
      {
        "name": "Ethanol"
      }
    ],
    "redox": {
      "enabled": "true",
      "subSystems": [
        {
          "name": "Chlorine",
          "enabled": false,
          "valenceStates": [
            {
              "name": "Cl(-1)",
              "enabled": true
            },
            {
              "name": "Cl(+1)",
              "enabled": false
            },
            {
              "name": "Cl(+7)",
              "enabled": true
            }
          ]
        },
        {
          "name": "Calcium",
          "enabled": true,
          "valenceStates": [
            {
              "name": "Ca(0)",
              "enabled": true
            },
            {
              "name": "Ca(+2)"
            }
          ]
        },
        {
          "name": "Nitrogen",
          "valenceStates": [
            {
              "name": "N(-3)",
              "enabled": true
            },
            {
              "name": "N(-2)"
            },
            {
              "name": "N(-1)",
              "enabled": true
            },
            {
              "name": "N",
              "enabled": true
            },
            {
              "name": "N(+1)",
              "enabled": true
            },
            {
              "name": "N(+2)"
            },
            {
              "name": "N(+3)",
              "enabled": true
            },
            {
              "name": "N(+4)"
            },
            {
              "name": "N(+5)",
              "enabled": true
            }
          ]
        }
      ]
    }
  }
}
```

{% hint style="info" %}
The Redox field is optional for generating .dbs files.
{% endhint %}

If Redox is enabled, the "subSystems" object becomes mandatory. Within this object, users must include the name along with a list of all valence states.

| redox      |    always required   | type                 |
| ---------- | :------------------: | -------------------- |
| subSystems | :heavy\_check\_mark: | Array of JSON Object |

Subsystem properties

| subSystems    |    always required   | type                 |
| ------------- | :------------------: | -------------------- |
| name          | :heavy\_check\_mark: | String               |
| valenceStates | :heavy\_check\_mark: | Array of JSON Object |

{% hint style="info" %}
Enabling a subSystem element automatically enables all of its valence states by default.
{% endhint %}

{% hint style="info" %}
To disable specific valence states, the user must explicitly set `"enabled": false`.
{% endhint %}

{% hint style="info" %}
Please refer to [Redox Query](/chemistry-model-files/chembuilder-api/chembuilder-query/redox-query) for information on element availability and its valence states. The output of a Redox Query can be directly inserted into the JSON input for generating .dbs files, as the JSON structure of both datasets is identical.
{% endhint %}

{% hint style="info" %}
The JSON object of Redox and its internal JSON objects can be enabled or disabled using ["enabled" Keyword](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/enabled-keyword)
{% endhint %}


# Choose Solids

You can include or exclude solid phases in your calculation. Here's an example demonstrating how to include or exclude a particular solid phase of a species.<br>

The example below illustrates how to include specific solid phases in the system.

```json
{
  "params": {
    "thermodynamicFramework": "MSE (H3O+ ion)",
    "privateDatabanks": [
    ],
    "modelName": "testModel",
    "phases": [
      "liquid1",
      "vapor",
      "solid",
      "liquid2"
    ],
    "inflows": [
      {
        "name": "H2O"
      },
      {
        "name": "NACL"
      },
      {
        "name": "UREA"
      },
      {
        "name": "NH3"
      },
      {
        "name": "CO2"
      },
      {
        "name": "CACO3"
      },
      {
        "name": "Benzene"
      },
      {
        "name": "Ethanol"
      }
    ],
    "includedSolids": {
      "enabled": true,
      "solids": [
        "NACLPPT",
        "NAOHPPT",
        "CACO3PPT",
        "UREAPPT"
      ]
    }
  }
}

```

{% hint style="info" %}
The "`includedSolids`" and "`excludedSolids`" parameters are optional in the input file for generating a .dbs file. Note that you cannot use "`includedSolids`" and "`excludedSolids`" simultaneously.
{% endhint %}

{% hint style="warning" %}
"includedSolids" will only include the solid phases of species explicitly specified by the user. An unspecified solid phase of species will be excluded by default.
{% endhint %}

The example below illustrates how to exclude certain solid phases in the system.

```json
{
  "params": {
    "thermodynamicFramework": "MSE (H3O+ ion)",
    "privateDatabanks": [
      "URE"
    ],
    "modelName": "testModel",
    "phases": [
      "liquid1",
      "vapor",
      "solid",
      "liquid2"
    ],
    "inflows": [
      {
        "name": "H2O"
      },
      {
        "name": "NACL"
      },
      {
        "name": "UREA"
      },
      {
        "name": "NH3"
      },
      {
        "name": "CO2"
      },
      {
        "name": "CACO3"
      },
      {
        "name": "Benzene"
      },
      {
        "name": "Ethanol"
      }
    ],
    "excludedSolids": {
      "enabled": true,
      "solids": [
        "CACL2.6H2O",
        "UREA"
      ]
    }
  }
}
```

{% hint style="warning" %}
"excludedSolids" will only exclude the solid phases of species explicitly specified by the user. An unspecified solid phase of species will be included by default.
{% endhint %}


# Add Kinetics

Kinetic reactions and their rate constants can be incorporated into the chemistry file using the "kinetics" field. The OLI Engine supports two types of kinetics: Arrhenius and user-defined. These are derived from the Reaction Kinetics (section 1.11) and Non-standard Rate Law (section 1.11.2) in the OLI Studio user manual.&#x20;

Below is a sample code featuring kinetics.

```json
{
  "params": {
    "thermodynamicFramework": "MSE (H3O+ ion)",
    "modelName": "testModel",
    "phases": [
      "liquid1",
      "vapor",
      "solid",
      "liquid2"
    ],
    "inflows": [
      {
        "name": "H2O"
      },
      {
        "name": "NACL"
      },
      {
        "name": "UREA"
      },
      {
        "name": "NH3"
      },
      {
        "name": "CO2"
      },
      {
        "name": "CACO3"
      },
      {
        "name": "Benzene"
      },
      {
        "name": "Ethanol"
      }
    ],
    "kinetics": {
      "enabled": true,
      "data": [
        {
          "enabled": true,
          "reaction": "2NH3AQ+CO2AQ=UREAAQ+H2O",
          "rateSpecification": "Arrhenius",
          "comment": "decide rate type names std/arrhenious vs user-defined/spec",
          "rateData": [
            {
              "name": "KF",
              "value": 2000.0,
              "enabled": true
            },
            {
              "name": "AR",
              "value": 1.2e-4,
              "enabled": true
            },
            {
              "name": "BR",
              "value": 3480.78
            },
            {
              "name": "ER1",
              "value": 2.0
            },
            {
              "name": "ER2",
              "value": 1.0
            },
            {
              "name": "EP1",
              "value": 1.0
            },
            {
              "name": "EP2",
              "value": 0.0
            }
          ]
        },
        {
          "enabled": true,
          "reaction": "NH3AQ+H2O=NH4ION+OHION",
          "rateSpecification": "user-defined",
          "comment": "decide rate type names std/arrhenious vs user-defined/spec",
          "rateData": [
            {
              "name": "FXRATE",
              "value": "LNH3AQ+ANH3AQ+LH2O+AH2O",
              "enabled": true
            },
            {
              "name": "RXRATE",
              "value": "LNH4ION+ANH4ION+LOHION+AOHION",
              "enabled": true
            },
            {
              "name": "KF1",
              "value": 3.0,
              "enabled": true
            },
            {
              "name": "KR1",
              "value": "KF1/KEQ",
              "enabled": true
            }
          ],
          "rate": "(KF1*EXP(FXRATE)-KR1*EXP(RXRATE))*VOLLIQ/1000"
        }
      ]
    }
  }
}
```

{% hint style="info" %}
Kinetics is an optional field for generating .dbs files.
{% endhint %}

The "`data`" JSON object is always required when utilizing kinetics.&#x20;

| kinetics |    always required   | type        |
| -------- | :------------------: | ----------- |
| data     | :heavy\_check\_mark: | JSON Object |

Within "`data`" object, the following input fields must be included.

| data              |    always required   | type                 |
| ----------------- | :------------------: | -------------------- |
| reaction          | :heavy\_check\_mark: | String               |
| rateSpecification | :heavy\_check\_mark: | String               |
| rateData          | :heavy\_check\_mark: | Array of JSON Object |

{% hint style="info" %}
Please refer to section 1.11, "Reaction Kinetics," and section 1.11.2, "Non-standard Rate Law," in the OLI Studio manual for more information on reactions and user-defined equations.
{% endhint %}

{% hint style="info" %}
Refer to [Kinetics Query](/chemistry-model-files/chembuilder-api/chembuilder-query/kinetics-query) for information on species and equilibrium reactions.
{% endhint %}

{% hint style="info" %}
In the "rateSpecification", either "Arrhenius" for standard rate law or "user-defined" for non-standard rate law is required.
{% endhint %}

{% hint style="info" %}
Kinetics and its internal JSON objects can be enabled or disabled using ["enabled" Keyword](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/enabled-keyword).
{% endhint %}


# ChemBuilder Query

In this section, we will present a set of query methods that offer various ways to query chemistry details. It's important to note that the output generated by specific query methods, such as Redox Query and Solid Phase Query, conforms to a valid format for input specifications. This allows users to easily utilize the output to directly stitch together a JSON payload to create a .dbs file.


# Species Query

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/chemistry/query/species`

#### Headers

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | String |             |

The Species query method can clarify whether a species exists in the databank of an associated thermodynamic framework and whether the entered name of the species is valid or not, addressing potential user uncertainties.

### Request Payload&#x20;

```json
{ 
    "params":{ 
        "thermodynamicFramework": "MSE (H3O+ ion)",
      }
}
```

<table><thead><tr><th width="266.3333333333333" align="center">Keyword in JSON</th><th align="center">Required </th><th align="center">Type</th></tr></thead><tbody><tr><td align="center"><strong>params</strong></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">JSON Object</td></tr><tr><td align="center"><strong>thermodynamicFramework</strong></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String</td></tr></tbody></table>

{% hint style="info" %}
Only the "thermodynamicFramework" parameter is needed here. All public and private databank information for this thermodynamic framework will be displayed in the output.
{% endhint %}

### Response (status=SUCCESS)

If no run-time [errors ](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/chembuilder-errors)are encountered, the [Query output](/chemistry-model-files/chembuilder-api/chembuilder-query/query-output-results) with the requested contents will be available for users to view.


# Redox Query

The input inflow species may contain elements that react and change their oxidation states, which should be accurately accounted for in the calculation. Certain metal elements like Iron and Zinc have all their valence states enabled by default, while others like Chlorine may require user selections. The Redox query lists each element's oxidation states, enabling users to view available valence states and generate a template format that can be readily applied in the Chemistry Builder input JSON file.

### Request Payload

```json
 {   
	"params": {
	"thermodynamicFramework": "Aqueous (H+ ion)",
	"privateDatabanks": [
		"COR"
	],
	"inflows": [
		{
			"name": "H2O"
		},
		{
			"name": "NACL"
		},
		{
			"name": "FECL3"
		}]	
	}
 }


```

<table><thead><tr><th width="255" align="center">params</th><th width="113" align="center">required</th><th width="135" align="center">type </th><th>description</th></tr></thead><tbody><tr><td align="center">thermodynamicFramework</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String</td><td>The name of thermodynamic framework (e.g. Aqueous (H+ ion))</td></tr><tr><td align="center">privateDatabanks</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td align="center">Array of String</td><td>The array of private data bank codes (e.g. "COR" and "CER")</td></tr><tr><td align="center">inflows</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of JSON Object</td><td>The array of JSON object  containing a valid identity of inflow species (e.g. {"name": "CO2"} for carbon dioxide)</td></tr></tbody></table>

### Response (status=SUCCESS)

If no run-time [errors ](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/chembuilder-errors)are encountered, the [Query output](/chemistry-model-files/chembuilder-api/chembuilder-query/query-output-results) with the requested contents will be available for users to view.


# Solid Phase Query

Once the user specifies the inflow species and their corresponding oxidation states, all solid phases can be accessed through the solid query method. These solid phases can then be included or excluded in the Chemistry Builder inflow file as needed.

### Request Payload&#x20;

```json
 {   
	"params": {
	"thermodynamicFramework": "Aqueous (H+ ion)",
	"privateDatabanks": [
		"COR", 
		"CER"
	],
	"inflows": [
		{
			"name": "H2O"
		},
		{
			"name": "NACL"
		},
		{
			"name": "FECL3"
		}],
	  "redox": {
		"enabled": true,
		"subSystems": [
			{
				"name": "Chlorine",
				"enabled": false,
				"valenceStates": [
					{
						"name": "Cl(-1)",
						"enabled": true
					},
					{
						"name": "Cl(+1)",
						"enabled": true
					},
					{
						"name": "Cl(+3)",
						"enabled": true
					},
					{
						"name": "Cl(+5)",
						"enabled": true
					},
					{
						"name": "Cl(+7)",
						"enabled": true
					},
					{
						"name": "Cl(+4)",
						"enabled": true
					}
				]
			},
			{
				"name": "Iron",
				"enabled": false,
				"valenceStates": [
					{
						"name": "Fe(0)",
						"enabled": true 
					},
					{
						"name": "Fe(+2)",
						"enabled": true
					},
					{
						"name": "Fe(+3)",
						"enabled": false 
					},
					{
						"name": "Fe(+6)",
						"enabled": false
					}
				]
			},
			{
				"name": "Sodium",
				"enabled": false,
				"valenceStates": [
					{
						"name": "Na(0)",
						"enabled": true
					},
					{
						"name": "Na(+1)",
						"enabled": true
					}
				]
			}
		]
	}
    }
 }


```

<table><thead><tr><th width="265" align="center">params</th><th width="98" align="center">required</th><th width="138" align="center">type</th><th>description</th></tr></thead><tbody><tr><td align="center">thermodynamicFramework</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String</td><td>The name of thermodynamic framework (e.g. Aqueous (H+ ion))</td></tr><tr><td align="center">privateDatabanks</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td align="center">Array of String</td><td>The array of private data bank codes (e.g. "COR" and "CER")</td></tr><tr><td align="center">inflows</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of JSON Object</td><td>The array of JSON object containing a valid identity of inflow species (e.g. {"name": "CO2"} for carbon dioxide)</td></tr><tr><td align="center">redox</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td align="center">JSON Object</td><td>enable or disable valence states for a particular element in a species</td></tr></tbody></table>

### Response (status=SUCCESS)

If no run-time [errors ](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/chembuilder-errors)are encountered, the [Query output](/chemistry-model-files/chembuilder-api/chembuilder-query/query-output-results) with the requested contents will be available for users to view.


# Databank Query

When dealing with species not readily available in public databanks within a thermodynamic framework, users can turn to a private databank. The databank query assists users in verifying if the species is supported by the private databank linked to a thermodynamic framework. Additionally, since the list of species in a databank changes over time and users may struggle to keep track of versions and associated species, the databank query streamlines the process by offering an up-to-date list of all species in both public and private databanks.

```json
{ 
    "params":{ 
        "thermodynamicFramework": "Aqueous (H+ ion)",
        "privateDatabanks": ["COR", "CER"]
    }
}
```

<table><thead><tr><th width="273.76195506047435" align="center">params</th><th width="130" align="center">required </th><th width="141" align="center">type</th><th>Description</th></tr></thead><tbody><tr><td align="center">thermodynamicFramework</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String</td><td>The name of thermodynamic framework (e.g. Aqueous (H+ ion))</td></tr><tr><td align="center">privateDatabanks</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of String</td><td>The array of private data bank codes (e.g. "COR" and "CER")</td></tr></tbody></table>

{% hint style="info" %}
The private databank is an optional field. If a user lists the private databanks, all the species contained in these databanks will be displayed in the output.
{% endhint %}

{% hint style="info" %}
The valid code representing a private databank can be accessed using [Query Output Results](/chemistry-model-files/chembuilder-api/chembuilder-query/query-output-results)
{% endhint %}

### Response (status=SUCCESS)

If no run-time [errors ](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/chembuilder-errors)are encountered, the [Query output](/chemistry-model-files/chembuilder-api/chembuilder-query/query-output-results) with the requested contents will be available for users to view.


# Kinetics Query

When species, databanks, redox, and solid phases are correctly specified, equilibrium equations formulated based on the resulting species are available via the kinetics query method.

### Request Payload&#x20;

```json
 {   
	"params": {
	"thermodynamicFramework": "Aqueous (H+ ion)",
	"privateDatabanks": [
		"COR"
	],
	"inflows": [
		{
			"name": "H2O"
		},
		{
			"name": "NACL"
		},
		{
			"name": "FECL3"
		}],
	"phases": [
        	"liquid1",
        	"vapor",
        	"solid", 
        	"liquid2"
      ],
	  "redox": {
		"enabled": true,
		"subSystems": [
			{
				"name": "Chlorine",
				"enabled": false,
				"valenceStates": [
					{
						"name": "Cl(-1)",
						"enabled": true
					},
					{
						"name": "Cl(+1)",
						"enabled": true
					},
					{
						"name": "Cl(+3)",
						"enabled": true
					},
					{
						"name": "Cl(+5)",
						"enabled": true
					},
					{
						"name": "Cl(+7)",
						"enabled": true
					},
					{
						"name": "Cl(+4)",
						"enabled": true
					}
				]
			},
			{
				"name": "Iron",
				"enabled": false,
				"valenceStates": [
					{
						"name": "Fe(0)",
						"enabled": false
					},
					{
						"name": "Fe(+2)",
						"enabled": true
					},
					{
						"name": "Fe(+3)",
						"enabled": false
					},
					{
						"name": "Fe(+6)",
						"enabled": false
					}
				]
			},
			{
				"name": "Sodium",
				"enabled": false,
				"valenceStates": [
					{
						"name": "Na(0)",
						"enabled": true
					},
					{
						"name": "Na(+1)",
						"enabled": true
					}
				]
			}
		]
	}, 
        "includedSolids": {
            "enabled": true,
            "solids": [
				"FECL3"
            ]
        }
	}
 }


```

<table><thead><tr><th width="252" align="center">params</th><th width="116" align="center">required</th><th width="136" align="center">type</th><th align="center">description</th></tr></thead><tbody><tr><td align="center">thermodynamicFramework</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String</td><td align="center">The name of thermodynamic framework (e.g. Aqueous (H+ ion))</td></tr><tr><td align="center">privateDatabanks</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td align="center">Array of String</td><td align="center">The array of private data bank codes (e.g. "COR" and "CER")</td></tr><tr><td align="center">Inflows</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of JSON Object</td><td align="center">The array of JSON object containing a valid identity of inflow species (e.g. {"name": "CO2"} for carbon dioxide)</td></tr><tr><td align="center">phases</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of String</td><td align="center">The array of String which specify phases to be included (e.g. ["liquid1", "vapor", "solid"])</td></tr><tr><td align="center">redox</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">JSON Object</td><td align="center">enable or disable valence states for a particular element in a species.</td></tr></tbody></table>

### Response (status=SUCCESS)

If no run-time [errors ](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/chembuilder-errors)are encountered, the [Query output](/chemistry-model-files/chembuilder-api/chembuilder-query/query-output-results) with the requested contents will be available for users to view.


# Query Output Results

This page offers an overview of the output file generated by a query method. A typical output from the query method includes "data" and "result" sections if no errors occur during execution. The "data" and "result" sections contain the following information:

```json
{
    "data": {
        "metaData": {
            "executionTime": {
                "unit": "ms",
                "value": 344.0
            }
        },
        "result": {  
            // Either one of the type will be shown below
            // Type 1: species query
            "species": [
                { 
                    // species information
                } 
            ]
            // Type 2: Databank query 
            "publicDataBankInfo": [ 
                {
                } 
            ], 
            "privateDataBankInfo": [
                {
                }
            ]          
            // Type 3: redox query 
            "redox": { 
                // redox selection 
            }
            // Type 4: kinetics query
            "species": [
                // species name 
                // species phases
            ],
            "equilibriumReactions": [
                // equilibruim reactions
             ]         
        }
     }, 
    "message": "Chemistry generated successfully",
    "status": "SUCCESS"       
} 
```

### The "metaData" field

This section contains metadata, which provides runtime system information. Currently, the version number of the running software is included in the "metaData".

### The "result" field

This section presents all the contents produced by query methods.

{% tabs %}
{% tab title="Databank Query" %}
This method will return both the public and private databank information to users.

```json
    "publicDataBankInfo": [
            {
                "code": "MSE",
                "fullName": "MSE (H3O+ ion)",
                "framework": "H3OION",
                "description": "",
                "versions": {
                    "major": 11,
                    "minor": 0,
                    "revision": 1
                }
            }
        ],
        "privateDataBankInfo": [
            {
                "code": "AMI",
                "fullName": "AMINEHCL Databank",
                "framework": "H3OION",
                "description": "",
                "versions": {
                    "major": 9,
                    "minor": 2,
                    "revision": 1
                    }
            },
            {
                "code": "XSC",
                "fullName": "Surface Complexation Double Layer Model (MSE)",
                "framework": "H3OION",
                "description": "",
                "versions": {
                    "major": 11,
                    "minor": 0,
                    "revision": 1
                    }
            }
        ]


```

|        result       |     always shown     |         type         |
| :-----------------: | :------------------: | :------------------: |
|  publicDataBankInfo | :heavy\_check\_mark: | Array of JSON Object |
| privateDataBankInfo | :heavy\_check\_mark: | Array of JSON Object |

{% hint style="info" %}
The keyword "code" in "privateDataBankInfo" can be used as an input in "privateDatabank", which is an array of strings.
{% endhint %}

Both public and private databanks contain information in an identical format.
{% endtab %}

{% tab title="Species Query" %}
This method will return every species in the databank used in the query.

```json
        "species": [
            {
                "baseTag": "ABIETICAC",
                "synonyms": [
                    "Abietic acid",
                    "1-Phenanthrenecarboxylic acid, 1,2,3,4,4a,4b,5,6,10,10a-decahydro-1,4a-dime",
                    "7,13-Abietadien-18-oic acid",
                    "l-Abietic acid",
                    "Podocarpa-7,13-dien-15-oic acid, 13-isopropyl-",
                    "Sylvic acid",
                    "13-Isopropylpodocarpa-7,13-dien-15-oic acid"
                ],
                "chemicalFormula": "C20H30O2",
                "IUPAC": "Abietic acid",
                "CASNO": "514-10-3"
            },
            {
                "baseTag": "ACENAPHTHN",
                "synonyms": [
                    "Naphthyleneethylene",
                    "Periethylenenaphthalene",
                    "1,2-Dihydroacenaphthylene",
                    "Acenaphthylene, 1,2-dihydro-",
                    "1,8-Ethylenenaphthalene",
                    "Acenaphthene"
                ],
                "chemicalFormula": "C12H10",
                "IUPAC": "1,8-Ethylenenaphthalene",
                "CASNO": "83-32-9"
            },
            {
                "baseTag": "ZRSO42.1H2O",
                "synonyms": [
                    "Zirconium sulfate monohydrate"
                ],
                "chemicalFormula": "ZrSO42.1H2O",
                "IUPAC": "Zirconium sulfate monohydrate",
                "CASNO": ""
            },
            {
                "baseTag": "ZRSO42.4H2O",
                "synonyms": [
                    "Zirconium sulfate tetrahydrate"
                ],
                "chemicalFormula": "Zr(SO4)2.4H2O",
                "IUPAC": "Zirconium sulfate tetrahydrate",
                "CASNO": ""
            }
        ]
```

Each element of "species" is a JSON object that contains a variety of valid representations of a species used by OLI software.

<table><thead><tr><th align="center">species info</th><th width="123" align="center">always shown</th><th width="144" align="center">type</th><th align="center">inflow ready</th></tr></thead><tbody><tr><td align="center"><strong>baseTag</strong></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td></tr><tr><td align="center"><strong>synonyms</strong></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td></tr><tr><td align="center"><strong>chemicalFormula</strong></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td></tr><tr><td align="center"><strong>IUPAC</strong></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td></tr><tr><td align="center"><strong>CASNO</strong></td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td></tr></tbody></table>

{% hint style="info" %}
The fourth column in the table, "Inflow Ready", indicates if this output section can be directly used with the subsequent calculations input, i.e., the inflow section of the Chemistry Builder input JSON file.
{% endhint %}

{% hint style="info" %}
"synonyms" and "CASNO" can be empty in the output.
{% endhint %}
{% endtab %}

{% tab title="Redox Query" %}
This method displays all available valence states for the elements of species in the inflow. By default, valence states of Iron (Fe) are enabled, while all valence states of Chlorine (Cl) are disabled.

```json
        "redox": {
            "enabled": false,
            "subSystems": [
                {
                    "name": "Chlorine",
                    "enabled": false,
                    "valenceStates": [
                        {
                            "name": "Cl(-1)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+1)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+3)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+5)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+7)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+4)",
                            "enabled": false
                        }
                    ]
                },
                {
                    "name": "Iron",
                    "enabled": true,
                    "valenceStates": [
                        {
                            "name": "Fe(0)",
                            "enabled": true
                        },
                        {
                            "name": "Fe(+2)",
                            "enabled": true
                        },
                        {
                            "name": "Fe(+3)",
                            "enabled": true
                        },
                        {
                            "name": "Fe(+6)",
                            "enabled": true
                        }
                    ]
                }
            ]
        }
```

{% hint style="info" %}
The JSON object "redox" can be directly inserted into an input JSON file to enable or disable redox for .dbs file generation.
{% endhint %}

{% hint style="info" %}
If each element in the "subSystems" is enabled, then all of its valence states in "valenceStates" will be enabled by default. You can also refer to "[Redox Example 5](/chemistry-model-files/chembuilder-api/supporting-information-for-chembuilder/enabled-keyword)" section for more details.
{% endhint %}
{% endtab %}

{% tab title="Solid Phase Query" %}
This method displays all available solid phases given the inflow species and selections of phases.

```json

        "includedSolids": {
            "enabled": true,
            "solids": [
                "FECL3",
                "FECL3.2.5H2O",
                "FECL3.2H2O",
                "FECL3.6H2O",
                "FEIII2O3",
                "FEIIIOH3",
                "FEOOH",
                "NACL",
                "NAFEO2",
                "NAOH",
                "NAOH.1H2O"
            ]
        }
```

{% hint style="info" %}
The JSON object "includedSolids" can be directly inserted into the input JSON file to enable the solid phase of a particular species.
{% endhint %}

{% hint style="info" %}
The "Solids" accessed by this query method include "solid", "hydrate", and "surface species".
{% endhint %}
{% endtab %}

{% tab title="Kinetics Query" %}
This method presents all equilibrium reactions available based on users' selections of inflow species, phases, redox, and solid phases.

```json
        "species": [
            {
                "trueName": "H2O",
                "phase": "liquid"
            },
            {
                "trueName": "FECL3AQ",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOH3AQ",
                "phase": "liquid"
            },
            {
                "trueName": "H2AQ",
                "phase": "liquid"
            },
            {
                "trueName": "HCLAQ",
                "phase": "liquid"
            },
            {
                "trueName": "O2AQ",
                "phase": "liquid"
            },
            {
                "trueName": "CLION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIII2OH2ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIICL2ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIICL4ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIICLION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOH2ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOH4ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOHION",
                "phase": "liquid"
            },
            {
                "trueName": "HION",
                "phase": "liquid"
            },
            {
                "trueName": "NAION",
                "phase": "liquid"
            },
            {
                "trueName": "OHION",
                "phase": "liquid"
            },
            {
                "trueName": "FECL3PPT",
                "phase": "solid"
            },
            {
                "trueName": "FECL3.2.5H2O",
                "phase": "solid"
            },
            {
                "trueName": "FECL3.2H2O",
                "phase": "solid"
            },
            {
                "trueName": "FECL3.6H2O",
                "phase": "solid"
            },
            {
                "trueName": "FEIII2O3PPT",
                "phase": "solid"
            },
            {
                "trueName": "FEIIIOH3PPT",
                "phase": "solid"
            },
            {
                "trueName": "FEOOHPPT",
                "phase": "solid"
            },
            {
                "trueName": "NACLPPT",
                "phase": "solid"
            },
            {
                "trueName": "NAFEO2PPT",
                "phase": "solid"
            },
            {
                "trueName": "NAOHPPT",
                "phase": "solid"
            },
            {
                "trueName": "NAOH.1H2O",
                "phase": "solid"
            },
            {
                "trueName": "H2OVAP",
                "phase": "vapor"
            },
            {
                "trueName": "H2VAP",
                "phase": "vapor"
            },
            {
                "trueName": "HCLVAP",
                "phase": "vapor"
            },
            {
                "trueName": "O2VAP",
                "phase": "vapor"
            }
        ],
        "equilibriumReactions": [
            "FECL3.2.5H2O=FEIIIION+3CLION+2.5H2O",
            "FECL3.2H2O=FEIIIION+3CLION+2H2O",
            "FECL3.6H2O=FEIIIION+3CLION+6H2O",
            "FECL3AQ=FEIIICL2ION+CLION",
            "FECL3PPT=FEIIIION+3CLION",
            "FEIII2O3PPT+6HION=2FEIIIION+3H2O",
            "FEIII2OH2ION=2FEIIIION+2OHION",
            "FEIIICL2ION=FEIIICLION+CLION",
            "FEIIICL4ION=FECL3AQ+CLION",
            "FEIIICLION=FEIIIION+CLION",
            "FEIIIOH2ION=FEIIIOHION+OHION",
            "FEIIIOH3AQ=FEIIIOH2ION+OHION",
            "FEIIIOH3PPT=FEIIIION+3OHION",
            "FEIIIOH4ION=FEIIIOH3AQ+OHION",
            "FEIIIOHION=FEIIIION+OHION",
            "FEOOHPPT+H2O=FEIIIION+3OHION",
            "H2O=HION+OHION",
            "H2OVAP=H2O",
            "H2VAP=H2AQ",
            "HCLAQ=HION+CLION",
            "HCLVAP=HCLAQ",
            "NACLPPT=NAION+CLION",
            "NAFEO2PPT+2H2O=NAION+FEIIIION+4OHION",
            "NAOH.1H2O=NAION+OHION+H2O",
            "NAOHPPT=NAION+OHION",
            "O2VAP=O2AQ"
        ]
```

The output consists of two sections. The first section includes all species participating in equilibrium reactions. Each participating species has its true name and phase status. Internally, "trueName" is used by the engine and contains a suffix indicating its phase. The second section includes all equilibrium equations to be considered. These generated equations use the true name of species.

{% hint style="info" %}
The "liquid" phase for a species could apply to either aqueous or organic phase.
{% endhint %}
{% endtab %}
{% endtabs %}


# Supporting Information for ChemBuilder

This section illustrates some basic features and input requirements that the query methods and .dbs file generation will reference.


# Add Comment

JSON does not support user-defined comments. However, a workaround is to add comments as key-value pairs in a JSON object. In the example below, we add comments in a JSON object using custom keywords such as "comment", "\_comment", "comments", or any other descriptive keyword chosen by the user. When Chemistry Builder parses an input JSON file, these custom keywords are safely ignored, and only the required keywords will be matched and processed.

```json
  {
      "params": {
        "thermodynamicFramework": "MSE (H3O+ ion)",
        "comments": "This is a comment", 
        "modelName": "testModel",
        "privateDatabanks": []
      "phases": [
        "liquid1",
        "vapor",
        "solid", 
        "liquid2"
      ],
        "inflows": [
            {
                "name": "H2O",
                "comment": "water is added" 
            },
	    { 
		"name": "NaCl"
	    },
            {
                "name": "CO2"
            },
            {
                "name": "N2"
            }, 
            {
                "name": "BENZENE", 
                "_comment": "comment here" 
                
            },
            {
                "name": "CaCO3"
            } 
        ]	
    }
}
```


# "enabled" Keyword

The "enabled" keyword appears in multiple Chemistry Builder JSON objects, facilitating quick toggling of properties or options without the need to create or delete JSON objects explicitly, thereby reducing parameter tuning efforts. Here are guidelines, examples, and exceptions for its usage:

* The "enabled" keyword must be a Boolean type, accepting only true or false.
* It must be enclosed within "{ }" in a JSON object.
* When set to 'true', the input within the JSON object is processed.
* When set to 'false', the input within the JSON object is disregarded.
* If the "enabled" keyword is absent, the JSON object is processed by default.
* If the "enabled" field contains values other than 'true' or 'false', the JSON object is still processed.

{% tabs %}
{% tab title="Inflow Example 1" %}

```json
{
    	"inflows": [
		{
			"name": "H2O", 
			"enabled": true 
		},
		{
			"name": "NACL",
			"enabled": false
		},
		{ 
			"name": "CO2", 
		} ]
} 
```

In this example, "H2O" and "CO2" are included as inflow species, whereas "NaCl" is excluded.
{% endtab %}

{% tab title="Inflow Example 2" %}

```json
{
    	"inflows": [
		{
			"name": "H2O", 
		},
		{
			"name": "NACL",
		},
		{ 
			"name": "CO2", 
			"enabled": "true"
			
		} ]
}
```

The "enabled" field for CO2 is assigned a string value instead of a boolean value. However, CO2 will still be added as an input despite the incorrect data type.
{% endtab %}

{% tab title="Redox Example 3" %}

```json
  "redox": {
        "enabled": false,
        "subSystems": [
            {
                "name": "Chlorine",
                "enabled": true,
                "valenceStates": [
                    {
                        "name": "Cl(-1)",
                        "enabled": true
                    },
                    {
                        "name": "Cl(+1)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+3)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+5)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+7)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+4)",
                        "enabled": false
                    }
                ]
            }
        ]
    }
    
        
```

In this example, "redox" is disabled, resulting in the exclusion of everything within the object.
{% endtab %}

{% tab title="Redox Example 4" %}

```json
    "redox": {
        "enabled": true,
        "subSystems": [
            {
                "name": "Chlorine",
                "enabled": true,
                "valenceStates": [
                    {
                        "name": "Cl(-1)",
                        "enabled": true
                    },
                    {
                        "name": "Cl(+1)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+3)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+5)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+7)",
                        "enabled": false
                    },
                    {
                        "name": "Cl(+4)",
                        "enabled": false
                    }
                ]
            }
        ]
    }
```

In this example, "redox" and "Chlorine" are enabled, with only the "Cl (-1)" valence state being active. All other valence states are ignored.
{% endtab %}

{% tab title="Redox Example 5" %}

```json
 {   
	"params": {
	"thermodynamicFramework": "MSE (H3O+ ion)",
	"privateDatabanks": [
	],
	"modelName": "quickTest",
	"inflows": [
		{ 
			"name": "H2O"
		} ,	
		{
			"name": "NACL"
		},
		{
			"name": "CO2"
		},
		{
			"name": "BENZENE"
		},
		{ 
			"name": "ETHANOL" 
		}
		],
	"phases": [
		"liquid1",
		"vapor",
		"solid",
		"liquid2"
	],
	"redox": {
		"enabled": true,
		"subSystems": [
			{
				"name":"Carbon", 
				"enabled": true
			}, 
			{
				"name": "Chlorine",
				"enabled": false,
				"valenceStates": [
					{
						"name": "Cl(-1)",
						"enabled": true
					},
					{
						"name": "Cl(+1)",
						"enabled": true
					},					
					{
						"name": "Cl(+3)",
						"enabled": false
					},
					{
						"name": "Cl(+5)",
						"enabled": false
					},
					{
						"name": "Cl(+7)",
						"enabled": false
					}
	
				]
			}
		] 
	} 
	}
 }


```

In this example:

* Carbon, as a subsystem, is enabled, resulting in all its valence states being enabled by default.
* Chlorine is enabled, with Cl(+1) and Cl(-1) valence states explicitly enabled. Cl(+4) is not specified, so it defaults to enabled. Other valence states are explicitly disabled.
* Sodium is not included in the input, thus all its valence states are disabled by default.

It's important to note the default behaviors: missing known JSON objects are assumed to be disabled; hence Sodium is disabled by default. For the "redox" valence state, if an element like "Chlorine" is enabled, all its valence states are automatically enabled. Thus, if a valence state such as Cl(+4) is absent, it's automatically enabled. This approach mirrors OLI Studio's behavior.

To disable an individual valence state, `"enabled": false` must be explicitly set to override its default value.
{% endtab %}
{% endtabs %}


# ChemBuilder Errors

This page outlines several error messages that users may encounter when utilizing Chemistry Builder. The following errors occur specifically when the thermodynamic framework value is misspelled:

```json
{
    "data": {
        "error": {
            "error": {
                "messages": [
                    {
                        "code": 0,
                        "functionName": "oli_process_api::ChemistryBuilderAPI::setChemModel::<lambda_76b84038b7c916aae3a6b0c08ba8103d>::operator ()",
                        "message": [
                            "The input name of thermodynamic framework 'Aueous (H+ ion)' is not supported; Please enter a valid name of supported thermodynamic frameworks"
                        ],
                        "messageType": "error",
                        "objectType": "ChemistryBuilderAPI"
                    },
                    {
                        "code": 0,
                        "functionName": "oli_process_api::ChemistryBuilderAPI::initialize::<lambda_3f42c0f8e472529a61e2551c61fd79a7>::()::<lambda_280f20c46ba155cc50138f64d484b31a>::operator ()",
                        "message": [
                            "Fail to create the chemistry model; Query species exits"
                        ],
                        "messageType": "error",
                        "objectType": "ChemistryBuilderAPI"
                    }
                ]
            }
        },
        "metaData": {
            "executionTime": {
                "unit": "ms",
                "value": 1.0
            }
        }
    },
    "message": "Chemistry could not be generated",
    "status": "FAILED"
}
```

### JSON Format Errors

Users may occasionally encounter issues with formatting JSON input files, as illustrated in the following example:

```json
{ 
    "name": "H2O" // A comma is missing following the input 
    "enabled": false 
} 
```

Missing commas or parentheses in the JSON input file can lead to the following error:

```json
"Errors in parsing input JSON file; Check the format and argument of every keyword in the JSON file"
```


# Chemistry Wizard

This page guides the user through the steps of generating a chemistry model file via the Chemistry Wizard Desktop product

<div align="left"><img src="https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MQmCoaDUo1PPakJI47e%2F-MQmE8V2mj60Mb5DTQkg%2Fimage.png?alt=media&amp;token=f7050a8b-f12a-4732-83c7-f26c61cf2bd9" alt="The user chooses the name of chemistry model file and the directory in which it will be generated"></div>

<div align="left"><img src="https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MQmCoaDUo1PPakJI47e%2F-MQmEqkyQmwFpJH_Fc8T%2Fimage.png?alt=media&amp;token=3a58ee78-fe1b-4cbc-86c4-40b763d4cc1a" alt="The user chooses a thermodynamic framework along with any additional databases"></div>

<div align="left"><img src="https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MQmCoaDUo1PPakJI47e%2F-MQmFJKZdsN2iqCdxHWN%2Fimage.png?alt=media&amp;token=8d29540f-2c5a-41b3-939c-6bbad58a7b6b" alt="User adds the components (inflows) to the chemistry model"></div>

<div align="left"><img src="https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MQmCoaDUo1PPakJI47e%2F-MQmFwh3lgxTNPnK6ip1%2Fimage.png?alt=media&amp;token=30420a9b-2355-458f-8f23-e3172995e7bb" alt="User can optionally enable redox and add any psuedo component and assays to the chemistry model"></div>

<div align="left"><img src="https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MQmGA1mvNqXlVIrBeCU%2F-MQmGaOxpjSnReVZi30X%2Fimage.png?alt=media&amp;token=5156cef4-5d46-422b-9eae-62745fae8b20" alt="Users can choose the phases to be enabled and the solid phases that are allowed to precipitate"></div>

<div align="left"><img src="https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MQmGA1mvNqXlVIrBeCU%2F-MQmH5S-0oTbP0-SFqBG%2Fimage.png?alt=media&amp;token=be0437a3-cc1f-44bf-b034-18f2cea4aab8" alt="On clicking &#x22;Generate Files Now&#x22; the dbs file will be generated in the directory chosen in the first step"></div>

<div align="left"><img src="https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MK1GD7JkzSzCRydAEH3%2F-MQmNNQq4isP7xtB28jh%2F-MQmNZ7thvFIIgEdbZyt%2Fimage.png?alt=media&amp;token=fa345394-76eb-408c-8aa1-5fba0c222cb0" alt="If everything generated successfully, the user should see this screen"></div>

{% hint style="warning" %}
Currently adding Kinetics to the chemistry model via Chemistry Wizard is not supported
{% endhint %}


# Uploading chemistry model files

Chemistry model files need to be uploaded to the OLI cloud so that they can be referenced in the calculation input parameters.&#x20;

### \[1] Upload directly via the API

## upload dbs file

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/channel/upload/dbs`

uploads the dbs file to the OLI cloud as **multipart/form-data**

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% tabs %}
{% tab title="200 " %}

```
{
  "file": [
    {
      "filename": "H2O-CO2.dbs", 
      "id": "fc8034d3-a6e3-4992-bc55-6c77c8d5b780"
    }
  ], 
  "status": "UPLOADED", 
  "type": "dbs"
}

```

{% endtab %}
{% endtabs %}

### Response description

| field              | type            | description                             |
| ------------------ | --------------- | --------------------------------------- |
| file               | array of object | information of files uploaded:          |
| file\[  ].filename | string          | name of file with extension             |
| file\[  ].id       | string          | unique identifier for the uploaded file |
| status             | string          | **"UPLOADED"** or **"FAILED"**          |
| type               | string          | type of file                            |

### \[2] Uploading chemistry model files via the web UI

1. Login to OLI Application Builder(<https://appbuilder.olisystems.com>) with username and password
2. Select the **username\_private** channel from the left pane
3. Go to the files tab in the center pane
4. Upload the dbs file using the "upload" button
5. Refresh the page if required.
6. Once uploaded, click on the file button on this pane&#x20;
7. On the right hand pane you can obtain the file id, this is used in API(s), it should look something like this: **aae24777-fa3f-44a2-8f51-e56bc58f3811**


# Get list of uploaded files

## dbs file list

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/channel/dbs`

method returns a list of all dbs file uploaded

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% tabs %}
{% tab title="200 data is an array containing information for each dbs file that was uploaded." %}

```
{
    "data": [
        {
            "channelId": "b84a80ce-c0cb-4ab2-a042-4fff3086f29f",
            "channelName": "Cloud_private",
            "createdAt": 1618101144.33366,
            "createdBy": "cd7ca261-6761-4433-b119-8fa77807abfe",
            "fileId": "9dc132ea-dbe4-49d3-a051-387da0549974",
            "path": "OLI_APP_FILES/0011W00002SDj0xQAD/dbs/cd7ca261-6761-4433-b119-8fa77807abfe/9dc132ea-dbe4-49d3-a051-387da0549974/test_isothermal.dbs",
            "type": "dbs"
        },
        {
            "channelId": "b84a80ce-c0cb-4ab2-a042-4fff3086f29f",
            "channelName": "Cloud_private",
            "createdAt": 1617933192.18494,
            "createdBy": "cd7ca261-6761-4433-b119-8fa77807abfe",
            "fileId": "a1fff4ee-4346-48f2-83f3-0c4fc6d4105b",
            "path": "OLI_APP_FILES/0011W00002SDj0xQAD/dbs/cd7ca261-6761-4433-b119-8fa77807abfe/a1fff4ee-4346-48f2-83f3-0c4fc6d4105b/test_isothermal.dbs",
            "type": "dbs"
        }
    ],
    "message": "List of all DBS files, user has access to",
    "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}


# Quickstart example: Python

A convenient Python wrapper class has been provided as an example to get quickly up and running calculations with the OLI API(s).&#x20;

### Sample wrapper class&#x20;

{% tabs %}
{% tab title="Python" %}
The user can simple copy this code over and use in an existing Python project. This class provides a simple interface described below.&#x20;

{% hint style="success" %}
Please go to the very end of this page to see an example program using this class
{% endhint %}

```python
import requests
import json
import time

class OLIApi:
    '''
    A class to wrap OLI Cloud API calls to be accessible in a simple manner. This
    is just an example
    '''
    def __init__(self, username, password):
        '''
        Constructs all necessary attributes for OLIApi class

        username: user's username
        password: user's password
        '''
        self.__username = username
        self.__password = password
        self.__jwt_token = ""
        self.__refresh_token = ""
        self.__root_url = "https://api.olisystems.com"
        self.__auth_url = "https://auth.olisystems.com/auth/realms/api/protocol/openid-connect/token"
        self.__dbs_url = self.__root_url + "/channel/dbs"
        self.__upload_dbs_url = self.__root_url + "/channel/upload/dbs"

    def login(self):
        '''
        Login into user credentials for the OLI Cloud and returns:
        :return: True on success, False on failure
        '''

        headers = {
            "Content-Type": "application/x-www-form-urlencoded"
        }

        body = {
            "username": self.__username,
            "password": self.__password,
            "grant_type": "password",
            "client_id": "apiclient",
        }

        req_result = requests.post(self.__auth_url, headers=headers, data=body)
        if req_result.status_code == 200:
            req_result = req_result.json()
            if "access_token" in req_result:
                self.__jwt_token = req_result["access_token"]
                if "refresh_token" in req_result:
                    self.__refresh_token = req_result["refresh_token"]
                    return True

        return False

    def refresh_token(self):
        '''
        Refreshes the access token using the reresh token got obtained on login and returns:
        :return: True on success, False on failure
        '''

        headers = {
            "Content-Type": "application/x-www-form-urlencoded"
        }

        body = {
            "refresh_token": self.__refresh_token,
            "grant_type": "refresh_token",
            "client_id": "apiclient",
        }

        req_result = requests.post(self.__auth_url, headers=headers, data=body)
        if req_result.status_code == 200:
            req_result = req_result.json()
            if bool(req_result):
                if "access_token" in req_result:
                    self.__jwt_token = req_result["access_token"]
                    if "refresh_token" in req_result:
                        self.__refresh_token = req_result["refresh_token"]
                        return True

        return False

    def request_auto_login(self, req_func):
        '''
        Gets a new access token if the request returns with an expired token error. First tries with the refresh token
        if its still active or simple relogs in using the username and password.

        :param req_func: function to call
        :return: Returns an empty dict if failed
        '''

        num_tries = 1
        while num_tries <= 2:

            headers = {
                "authorization": "Bearer " + self.__jwt_token
            }

            req_result = req_func(headers)
            if req_result.status_code == 200:
                ret_val = json.loads(req_result.text)
                return ret_val
            elif num_tries == 1 and req_result.status_code == 401:
                req_result = req_result.json()
                if not self.refresh_token():
                    if not self.login():
                         break
            else:
                break
            num_tries = num_tries + 1

        return dict()

    def upload_dbs_file(self, file_path):
        '''
        Uploads a dbs file to the OLI Cloud given a full file path.

        :param file_path: full path to dbs file
        :return: dictionary containing the
        uploaded file id
        '''
        req_result = dict()

        # read the file data in
        try:
            with open(file_path, "rb") as file:
                files = {"files": file}

                req_result = self.request_auto_login(lambda headers: requests.post(self.__upload_dbs_url, headers=headers,
                                               files=files))
        except IOError:
            pass

        return req_result

    def get_user_dbs_files(self):
        '''
        Returns a dictionary containing a list of dbs file(s) uploaded

        :return: dictionary containing list of dbs files
        '''
        return self.request_auto_login(
            lambda headers: requests.get(self.__dbs_url, headers=headers))

    def call(self, function_name, chemistry_model_file_id, json_input = dict(), poll_time = 1.0, max_request = 1000):
        '''
        calls a function in the OLI Engine API.

        :param function_name: name of function to call
        :param chemistry_model_file_id: the chemistry model file if for this calculation
        :param json_input: calculation input JSON
        :param poll_time: max delay between each call
        :param max_request: maximum requests
        :return: dictionary containing result or error
        '''

        # formulate url
        endpoint = ""
        method = "POST"
        if function_name == "chemistry-info" or function_name == "corrosion-contact-surface":
            endpoint = self.__root_url + "/engine/file/" + chemistry_model_file_id + "/" + function_name
            method = "GET"
        else:
            endpoint = self.__root_url + "/engine/flash/" + chemistry_model_file_id + "/" + function_name
            method = "POST"

        # http body
        if bool(json_input):
            data = json.dumps(json_input)
        else:
            data = ""

        def add_additional_header(headers):
            headers["content-type"] = "application/json"
            if method == "POST":
                return requests.post(endpoint, headers=headers, data=data)

            output = requests.get(endpoint, headers=headers, data=data)
            return output

        #first call
        results_link = ""
        start_time = time.time()
        request_result1 = self.request_auto_login(add_additional_header)
        end_time = time.time()
        request_time = end_time - start_time
        print("First request time =", request_time)
        if bool(request_result1):
            if request_result1["status"] == "SUCCESS":
                if "data" in request_result1:
                    if "status" in request_result1["data"]:
                        if request_result1["data"]["status"] == "IN QUEUE" or request_result1["data"]["status"] == "IN PROGRESS":
                            if "resultsLink" in request_result1["data"]:
                                results_link = request_result1["data"]["resultsLink"]

        print(results_link)

        # error in getting results link
        if results_link == "":
            return dict()

        # poll on results link until success
        data = ""
        endpoint = results_link
        method = "GET"
        request_iter = 0
        while True:
            # make request and time
            start_time = time.time()
            request_result2 = self.request_auto_login(add_additional_header)
            end_time = time.time()
            request_time = end_time - start_time
            print("Second request time =", request_time)

            # check if max requests exceeded
            request_iter = request_iter + 1
            if request_iter > max_request:
                break

            # extract
            print(request_result2)
            if bool(request_result2):
                if "status" in request_result2:
                    status = request_result2["status"]
                    print(status)
                    if status == "PROCESSED" or status == "FAILED":
                        if "data" in request_result2:
                            return request_result2["data"]
                        else:
                            break
                    elif status == "IN QUEUE" or status == "IN PROGRESS":
                        if poll_time > request_time:
                            time.sleep(poll_time - request_time)
                        continue
                    else:
                        break
                else:
                    break
            else:
                break

        return dict()
```

{% endtab %}
{% endtabs %}

### Example program demonstrating running an isothermal calculation

{% tabs %}
{% tab title="Python" %}
Replace "username" and "password" with correct values.

```python
# example program (Isothermal flash)
if __name__ == "__main__":
    oliapi = OLIApi("username", "password")
    if oliapi.login():

        # upload chemistry file (this needs to be done only once to get the file id)
        # this needs to be only done once per chemistry model file
        # after that the id is suffcient
        result = oliapi.upload_dbs_file("API_CALL_ISOTHERMAL\\test_isothermal.dbs")
        print(json.dumps(result, indent=2))

        chemistry_file_id = result["file"][0]["id"]

        # display all available dbs files
        result = oliapi.get_user_dbs_files()
        print(json.dumps(result, indent=2))

        # get chemistry information
        result = oliapi.call("chemistry-info", chemistry_file_id)
        print(json.dumps(result, indent=2))

        # create isothermal flash input
        flash_input = {
            "params": {
                "temperature": {
                    "value": 30.0,
                    "unit": "°C"
                },
                "pressure": {
                    "value": 1.5,
                    "unit": "atm"
                },
                "inflows": {
                    "unit": "mol",
                    "values": {
                        "H2O": 50.0,
                        "CO2": 10.0,
                        "NACL": 20.0,
                        "BENZENE": 10.0
                    }
                }
            }
        }

        # call the flash function
        result = oliapi.call("isothermal", chemistry_file_id, flash_input)
        print(json.dumps(result, indent=2).encode('utf8'))
```

{% endtab %}
{% endtabs %}


# Known issues and Limitations

### Known issues

* JSON input passed as input in http body needs to be UTF-8 encoded. If not this could cause undefined behavior.
* Values for unit entries need to be specified as given in this document. Error in this input could cause undefined behavior. This issue is being resolved at the moment
* Currently, in some unusual cases, there may be some discrepancy between units chosen for output and the units that are actually used.
* When an equilibrium calculation fails or when there is bad user input, there could be cases when the http response status could be still be 200 OK. Please verify the data object to be sure i.e. error object or result object. The data object will contain information on the state of the last call

### Limitations

* Currently there is no way to generate a chemistry model file(.dbs) directly with the cloud API(s). This capability is currently in development.
* Currently the cloud API(s) do not support ScaleChem specific calculations. This capability is currently in development.
* Batch calculations on the same chemistry model are not supported. The user would have to issue individual requests for each calculation
* System limits:
  * max queue: Maximum number of calculations that can be queued
  * max concurrency: Maximum simultaneous calculations that can be performed
* In the event that an computation engine crash occurs, the backend could take up to 1 minute to respond to the error during the polling cycle.


# Main methods


# API call blueprint

The time to run a calculation using the OLI API cannot be predicted accurately and also some calculations may take longer to compute than others. Hence, a polling mechanism is required to retrieve the result of each calculation. The steps for this mechanism is described below.

1. Send a **GET/POST** request to the specific URL
2. If the request was successful(status:200), the JSON response back will contain a link to the results and status of the computation. The status can be **IN QUEUE/IN PROGRESS**
3. Keep polling the results link with a **GET** request until status of the response changes to **PROCESSED/FAILED/ERROR**
4. &#x20;if status is **PROCESSED**, then response will also contain the result of the computation

### Here is an example for an isothermal flash call

## Isothermal flash \[1st request]

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/isothermalFlash`

&#x20;The first request to initiate an isothermal flash calculation

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-Type  | string | application/json       |

{% tabs %}
{% tab title="200 " %}

```
{
	"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 %}

### Response description

| field            | description                                                     |
| ---------------- | --------------------------------------------------------------- |
| code             | HTTP response status code                                       |
| data.file\_id    | the dbs file reference identifier                               |
| data.jobId       | the current request job identifier                              |
| data.resultsLink | the https endpoint to poll to get the final result              |
| data.status      | current status of the job                                       |
| message          | message describing the request                                  |
| status           | status of the current request, can be **SUCCESS** or **FAILED** |

{% hint style="warning" %}
**access\_token** in the request authorization header is obtained as shown here.

**db\_file\_id** is the id of the dbs file, you can obtain it [here](/uploading-oli-files).
{% endhint %}

## Result of computation \[2nd request and onwards]

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/result/flash/{jobId}?context=engine`

URL contains the result of the computation if status is processed

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-Type  | string | application/json       |

{% tabs %}
{% tab title="200 " %}

```
{
    "code": 200, 
    "data": {
        "result": {
          ...
          }
    }, 
    "message": "Results returned successfully", 
    "resultsLink": "https://devapi.olisystems.com/result/flash/fbce59ee-f31e-447b-b450-ba5b0d0a1a99?context=engine", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
status can be **IN QUEUE**, **IN PROGRESS**, **PROCESSED, FAILED** or **ERROR**

if status = **IN QUEUE**/**IN PROGRESS**, keep polling the endpoint in resultsLink

if status = **PROCESSED**, result should be in **data.result**

if status = **FAILED**, computation failure. error will be be in **data.error**

if status = **ERROR**, a system error occurred
{% endhint %}

#### Example chain of request responses

```javascript
// 1st Response
{
  "code": 200, 
  "data": {
    "fileId": "b60c97de-3486-4165-8589-d9885d14a382", 
    "jobId": "318e35c7-609b-466f-876f-e872a5b0a4a0", 
    "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
    "status": "IN PROGRESS"
  }, 
  "message": "Process execution started Successfully", 
  "status": "SUCCESS"
}

// 2nd response on GET resultsLink
{
  "code": 200, 
  "data": {}, 
  "message": "Results returned successfully", 
  "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
  "status": "IN PROGRESS"
}

// 3rd request on GET resultsLink (still in progress)
{
  "code": 200, 
  "data": {}, 
  "message": "Results returned successfully", 
  "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
  "status": "IN PROGRESS"
}

// 4th request on GET resultsLink (processed!), result in data.result
{
  "code": 200, 
  "data": {
    "result": {
      ...
      }
    },
  "message": "Results returned successfully",
  "status": "PROCESSED"
}
```

{% hint style="warning" %}
Presence of the **data.result** object signifies that results are available. if **data.error** object is present, then this means that the computation has failed
{% endhint %}


# Chemistry information

This function is used to obtain useful chemistry information that is based on the chemistry model file chosen. The output of this function can be for the most part used to determine the inflows required to craft the input for other OLI calculations.&#x20;

## chemistry information

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/engine/file/{dbs_file_id}/chemistry-info`

get information on the inflows, species and thermodynamic framework for a given chemistry model

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% tabs %}
{% tab title="200 Please look at the "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://devapi.olisystems.com/result/flash/f6b3375e-cd0f-4ace-a5ee-71e047b76754?context=engine",
		"status": "IN PROGRESS"
	},
	"message": "Process execution started Successfully",
	"status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}

### Response (status = PROCESSED)

```javascript
{
    "data": {
        "result": {
            "inflows": [
                {
                    "baseName": "H2O",
                    "mw": 18.01533
                },
                {
                    "baseName": "CO2",
                    "mw": 44.00991
                },
                {
                    "baseName": "BENZENE",
                    "mw": 78.11442
                },
                {
                    "baseName": "HCL",
                    "mw": 36.46097
                },
                ...<snip>...
            ],
            "species": [
                {
                    "baseName": "H2O",
                    "charge": 0.0,
                    "mw": 18.01533,
                    "phase": "liquid",
                    "trueName": "H2O"
                },
                {
                    "baseName": "H2O",
                    "charge": 0.0,
                    "mw": 18.01533,
                    "phase": "vapor",
                    "trueName": "H2OVAP"
                }
                {
                    "baseName": "H2O",
                    "charge": 0.0,
                    "mw": 18.01533,
                    "phase": "solid",
                    "trueName": "H2OPPT"
                },
                {
                    "baseName": "NA2CO3",
                    "charge": 0.0,
                    "mw": 105.98924,
                    "phase": "solid",
                    "trueName": "NA2CO3PPT"
                },
                {
                    "baseName": "NA3HCO32",
                    "charge": 0.0,
                    "mw": 189.99648000000002,
                    "phase": "solid",
                    "trueName": "NA3HCO32PPT"
                },
                {
                    "baseName": "NA5H3CO34",
                    "charge": 0.0,
                    "mw": 358.01096,
                    "phase": "solid",
                    "trueName": "NA5H3CO34PPT"
                },
                ...<snip>...
            ],
            "thermodynamicFramework": "MSE"
        }
    },
    "message": "Results returned successfully",
    "status": "PROCESSED"
}
```

There may be more inflows generated here than that was specified during the chemistry model generation stage. These extra inflows are called "related inflows", as they are the other possible inflows that can be formed from the combination of individual material species that formed the original inflows.

The response contains two main keys i.e. the **result.inflows** and **result.species**. Both are array type objects. Their values are described below

| data.result.inflows[\[ { } \] ](/terms-definition) | type   | description      |
| -------------------------------------------------- | ------ | ---------------- |
| baseName                                           | string | name of inflow   |
| mw                                                 | number | molecular weight |

| data.result.species[\[ { } \]](/terms-definition) | type   | value                         |
| ------------------------------------------------- | ------ | ----------------------------- |
| baseName                                          | string | species name                  |
| trueName                                          | string | name of species with suffix   |
| mw                                                | number | molecular weight              |
| charge                                            | number | species charge                |
| phase                                             | string | phase in which species exists |

{% hint style="warning" %}
if a species exists in **"aqeuous"** phase, this means it can be present in **liquid1** and/or **liquid2** phases
{% endhint %}

### Description of "trueName"&#x20;

OLI's species naming scheme internally attaches a suffix at the end of species name to indicate the type of species.&#x20;

| suffix | species type            | possible phases  |
| ------ | ----------------------- | ---------------- |
| AQ     | molecular (neutral)     | liquid1, liquid2 |
| ION    | ionic (charged)         | liquid1, liquid2 |
| PPT    | precipitate             | solid            |
| .nH2O  | hydrate                 | solid            |
| SOL    | surface species         | surface          |
| CPI    | surface ionic species   | surface          |
| CPM    | surface neutral species | surface          |

{% hint style="info" %}
The only exception is H2O species, it does not have a suffix and is understood to be in the aqueous phase and/or the second liquid phase.&#x20;
{% endhint %}


# Isothermal flash

This method is the most common thermodynamic flash function and is used to determine the equilibrium solution output at a constant temperature and pressure.

## isothermal&#x20;

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/isothermal`

run an isothermal flash calculation

#### 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 to find out how to obtain results" %}

```
{
	"code": 200,
	"data": {
		"file_id": "dee854a6-59db-487d-ad08-a20dee691133",
		"jobId": "f6b3375e-cd0f-4ace-a5ee-71e047b76754",
		"resultsLink": "https://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 20.0,
                "BENZENE": 10.0
            }
        }
    }
}
```

| **params**  | type                             | description                                                               |
| ----------- | -------------------------------- | ------------------------------------------------------------------------- |
| temperature | [valueObject](/terms-definition) | specified temperature with [unit](/input-unit-set)                        |
| pressure    | [valueObject](/terms-definition) | specified pressure with [unit](/input-unit-set)                           |
| inflows     | object                           | specified inflow species composition, see [Inflows Input](/inflows-input) |

{% hint style="info" %}
In addition to the inputs shown above, some optional properties may also be specified. They can be viewed [here](/optional-inputs).
{% endhint %}

{% hint style="info" %}
If kinetic reactions are defined in the chemistry model, kinetic calculation inputs are required to be specified. A detailed description can be found [here](/kinetic-calculation-inputs).
{% endhint %}

### Response (status = PROCESSED)

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output).

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |


# Isenthalpic flash

This function is used to determine the equilibrium solution output at constant pressure and enthalpy. Here the temperature is a free variable that is determined along with the equilibrium solution output.

## isenthalpic

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/isenthalpic`

run an isenthalpic flash calculation

#### 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 to find out how to obtain results" %}

```
{
	"code": 200,
	"data": {
		"file_id": "dee854a6-59db-487d-ad08-a20dee691133",
		"jobId": "f6b3375e-cd0f-4ace-a5ee-71e047b76754",
		"resultsLink": "https://devapi.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": {
        "temperature": {
            "value": 40.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "enthalpy": {
            "value": -7.34600e6,
            "unit": "cal"
        },
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "BENZENE": 10.0,
                "CH4": 20.0,
                "NAOH": 35.0
            },
            "totalAmount":
            {
                "value": 115.0,
                "unit": "mol"
            }
        }
}
```

| **params**  | type                             | description                                                               |
| ----------- | -------------------------------- | ------------------------------------------------------------------------- |
| temperature | [valueObject](/terms-definition) | specified initial guess temperature with [unit](/input-unit-set)          |
| pressure    | [valueObject](/terms-definition) | specified pressure with [unit](/input-unit-set)                           |
| enthalpy    | [valueObject](/terms-definition) | specified total enthalpy with [unit](/input-unit-set)                     |
| inflows     | object                           | specified inflow species composition, see [Inflows Input](/inflows-input) |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

{% hint style="info" %}
If kinetic reactions are defined in the chemistry model, kinetic calculation inputs are required to be specified. A detailed description can be found [here](/kinetic-calculation-inputs).
{% endhint %}

### Response (status = PROCESSED)

```javascript
{
    "code": 200,
    "data": {
        "result": {
           ...<snip>...
            "calculatedVariables": [
                {
                    "name": "temperature",
                    "value": 39.93432750114107,
                    "unit": "°C"
                }
            ],
        }
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output). In addition to this output the result also contains the solution temperature which can be conveniently retrieved from the **data.result.calculatedVariable** array&#x20;

| data.result.calculatedVariables [\[ { } \]](/terms-definition) | type   | description                                                                                                                                       |
| -------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                                           | string | name of the calculated variable, i.e. temperature                                                                                                 |
| value                                                          | number | value of the calculated variable                                                                                                                  |
| unit                                                           | string | unit of the calculated variable, which is the same as the one specified in the input initial guess, i.e. **params.temperature.unit** in the input |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |
| "/params/enthalpy/value"                     |


# Bubble point flash

This function calculates mixture bubble point temperature or pressure depending on the input option.&#x20;

## bubble point

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/bubblepoint`

run a bubblepoint temperature or pressure calculation

#### 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 to find out how to obtain results" %}

```
{
	"code": 200,
	"data": {
		"file_id": "dee854a6-59db-487d-ad08-a20dee691133",
		"jobId": "f6b3375e-cd0f-4ace-a5ee-71e047b76754",
		"resultsLink": "https://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "calculatedVariable": "pressure",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 20.0,
                "BENZENE": 10.0
            }
        }
    }
}
```

| **params**         | type                             | description                                                               |
| ------------------ | -------------------------------- | ------------------------------------------------------------------------- |
| temperature        | [valueObject](/terms-definition) | specified or initial guess temperature with [unit](/input-unit-set)       |
| pressure           | [valueObject](/terms-definition) | specified or initial guess pressure with [unit](/input-unit-set)          |
| calculatedVariable | string                           | variable to be calculated, i.e. "temperature" or "pressure"               |
| inflows            | object                           | specified inflow species composition, see [Inflows Input](/inflows-input) |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

{% hint style="info" %}
If kinetic reactions are defined in the chemistry model, kinetic calculation inputs are required to be specified. A detailed description can be found [here](/kinetic-calculation-inputs).
{% endhint %}

### Response (status = PROCESSED)

{% tabs %}
{% tab title="bubble point pressure" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
        "calculatedVariables": [
                {
                    "name": "pressure",
                    "unit": "atm",
                    "value": 41.88444899543713
                }
            ],
            ...<snip>...
        }
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"   
}
```

{% endtab %}

{% tab title="bubble point temperature" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
            "calculatedVariables": [
                {
                    "name": "temperature",
                    "unit": "°C",
                    "value": -74.08896826274247
                }
            ],
            ...<snip>...
        }
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

The output of this calculation is the [**stream output** ](/stream-output-json)which is common result output for all OLI's flash calculations or an [**error**](/error-output)**.** In addition to this output the result also contains the solution temperature/pressure which can be conveniently retrieved from the **data.result.calculatedVariables** array&#x20;

| data.result.calculatedVariables [\[ { } \]](/terms-definition) | type   | description                                                                                                                                                |
| -------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                                           | string | name of the calculated variable, i.e. temperature/pressure as specified in JSON input **params.calculatedVariable**                                        |
| value                                                          | number | value of the calculated variable                                                                                                                           |
| unit                                                           | string | unit of the calculated variable, which is the same as specified in the input initial guess, i.e. **params.pressure.unit/params.temperature.unit** in input |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |


# Dew point flash

This function calculates mixture dew point temperature or pressure depending on the input option.&#x20;

## dew point

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/dewpoint`

run a dewpoint temperature or pressure calculation

#### 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 to find out how to obtain results" %}

```
{
	"code": 200,
	"data": {
		"file_id": "dee854a6-59db-487d-ad08-a20dee691133",
		"jobId": "f6b3375e-cd0f-4ace-a5ee-71e047b76754",
		"resultsLink": "https://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "calculatedVariable": "pressure",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 20.0,
                "BENZENE": 10.0
            }
        }
    }
}
```

| **params**         | type                             | description                                                               |
| ------------------ | -------------------------------- | ------------------------------------------------------------------------- |
| temperature        | [valueObject](/terms-definition) | specified or initial guess temperature with [unit](/input-unit-set)       |
| pressure           | [valueObject](/terms-definition) | specified or initial guess pressure with [unit](/input-unit-set)          |
| calculatedVariable | string                           | variable to be calculated, i.e. "temperature" or "pressure"               |
| inflows            | object                           | specified inflow species composition, see [Inflows Input](/inflows-input) |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

{% hint style="info" %}
If kinetic reactions are defined in the chemistry model, kinetic calculation inputs are required to be specified. A detailed description can be found [here](/kinetic-calculation-inputs).
{% endhint %}

### Response (status = PROCESSED)

{% tabs %}
{% tab title="dew point temperature" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
           "calculatedVariables": [
                {
                    "name": "temperature",
                    "unit": "°C",
                    "value": 110.74053319131087
                }
            ],
            ...<snip>...
        }
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}

{% tab title="dew point pressure" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
           "calculatedVariables": [
                {
                    "name": "pressure",
                    "unit": "atm",
                    "value": 0.044180122983096495
                }
            ],
            ...<snip>...
        }
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [**error**](/error-output)**.** In addition to this output the result also contains the solution temperature/pressure which can be conveniently retrieved from the **data.result.calculatedVariables** array&#x20;

| data.result.calculatedVariables [\[ { } \]](/terms-definition) | type   | description                                                                                                                                                |
| -------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                                           | string | name of the calculated variable, i.e. temperature or pressure as specified in JSON input **params.calculatedVariable**                                     |
| value                                                          | number | value of the calculated variable                                                                                                                           |
| unit                                                           | string | unit of the calculated variable, which is the same as specified in the input initial guess, i.e. **params.temperature.unit/params.pressure.unit** in input |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |


# Vapor amount flash

This function calculates the mixture temperature or pressure at a fixed amount of vapor phase.

## vapor amount

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/vapor-amount`

run a fix vapor amount calculation by varying temperature or pressure

#### 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://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "vaporAmountMoles": {
            "value": 20.0,
            "unit": "mole"
        },
        "calculatedVariable": "pressure",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 20.0,
                "BENZENE": 10.0
            }
        }
    }
}
```

| **params**         | type                             | description                                                               |
| ------------------ | -------------------------------- | ------------------------------------------------------------------------- |
| temperature        | [valueObject](/terms-definition) | specified or initial guess temperature with [unit](/input-unit-set)       |
| pressure           | [valueObject](/terms-definition) | specified or initial guess pressure with [unit](/input-unit-set)          |
| vaporAmountMoles   | [valueObject](/terms-definition) | specified vapor phase moles with [unit](/input-unit-set)                  |
| calculatedVariable | string                           | variable to be calculated, i.e. "temperature" or "pressure"               |
| inflows            | object                           | specified inflow species composition, see [Inflows Input](/inflows-input) |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

{% hint style="info" %}
If kinetic reactions are defined in the chemistry model, kinetic calculation inputs are required to be specified. A detailed description can be found [here](/kinetic-calculation-inputs).
{% endhint %}

### Response (status = PROCESSED)

{% tabs %}
{% tab title="temperature" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
            ...<snip>...
            "calculatedVariables": [
                {
                    "name": "temperature",
                    "value": 25.0,
                    "unit": "°C"
                }
            ],
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}

{% tab title="pressure" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
            ...<snip>...
            "calculatedVariables": [
                {
                    "name": "pressure",
                    "value": 18.50115777667646,
                    "unit": "atm"
                }
            ]
        }
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output). In addition to this output the result also contains the solution temperature/pressure which can be conveniently retrieved from the **data.result.calculatedVariables** array&#x20;

| data.result.calculatedVariables [\[ { } \]](/terms-definition) | type   | description                                                                                                                                                |
| -------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                                           | string | name of the calculated variable, i.e. temperature or pressure as specified in JSON input **params.calculatedVariable**                                     |
| value                                                          | number | value of the calculated variable                                                                                                                           |
| unit                                                           | string | unit of the calculated variable, which is the same as specified in the input initial guess, i.e. **params.temperature.unit/params.pressure.unit** in input |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |
| "/params/vaporAmountMoles/value"             |


# Vapor fraction flash

This function calculates the mixture temperature or pressure at a fixed vapor phase mole fraction with respect to inflows i.e. (vapor phase moles/inflow moles)

## vapor fraction

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/vapor-fraction`

run a fix vapor fraction calculation by varying temperature or pressure

#### 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://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "vaporMolFrac": {
            "value": 15.0,
            "unit": "mole %"
        },
        "calculatedVariable": "pressure",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 20.0,
                "BENZENE": 10.0
            }
        }
    }
}
```

| **params**         | type        | description                                                               |
| ------------------ | ----------- | ------------------------------------------------------------------------- |
| temperature        | valueObject | specified or initial guess temperature with [unit](/input-unit-set)       |
| pressure           | valueObject | specified or initial guess pressure with [unit](/input-unit-set)          |
| vaporMolFrac       | valueObject | specified vapor/inflow by moles with [unit](/input-unit-set)              |
| calculatedVariable | string      | variable to be calculated, i.e. "temperature" or "pressure"               |
| inflows            | object      | specified inflow species composition, see [Inflows Input](/inflows-input) |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

{% hint style="info" %}
If kinetic reactions are defined in the chemistry model, kinetic calculation inputs are required to be specified. A detailed description can be found [here](/kinetic-calculation-inputs).
{% endhint %}

### Response (status = PROCESSED)

{% tabs %}
{% tab title="temperature" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
            "calculatedVariables": [
                {
                    "name": "temperature",
                    "unit": "°C",
                    "value": 47.055412429605155
                }
            ],
            ...<snip>...
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}

{% tab title="pressure" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
            "calculatedVariables": [
                {
                    "name": "pressure",
                    "unit": "atm",
                    "value": 0.7060155068553384
                }
            ],
            ...<snip>...
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

The output of this calculation is the [**stream output** ](/stream-output-json)which is common result output for all OLI's flash calculations or an [**error**](/error-output)**.** In addition to this output the result also contains the solution temperature/pressure which can be conveniently retrieved from the **data.result.calculatedVariable** array&#x20;

| data.result.calculatedVariable [\[ { } \]](/terms-definition) | type   | description                                                                                                                                                |
| ------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                                          | string | name of the calculated variable, i.e. temperature or pressure as specified in JSON input **params.calculatedVariable**                                     |
| value                                                         | number | value of the calculated variable                                                                                                                           |
| unit                                                          | string | unit of the calculated variable, which is the same as specified in the input initial guess, i.e. **params.temperature.unit/params.pressure.unit** in input |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |
| "/params/vaporMolFrac/value"                 |


# Isochoric flash

This function calculates the mixture temperature or pressure at a fixed total volume.

## isochoric

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/isochoric`

run an isochoric calculation by varying temperature or pressure

#### 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://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "totalVolume": {
            "value": 0.4,
            "unit": "m3"
        },
        "calculatedVariable": "pressure",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 20.0,
                "BENZENE": 10.0
            }
        }
    }
}
```

| **params**         | type                             | description                                                               |
| ------------------ | -------------------------------- | ------------------------------------------------------------------------- |
| temperature        | [valueObject](/terms-definition) | specified or initial guess temperature with [unit](/input-unit-set)       |
| pressure           | [valueObject](/terms-definition) | specified or initial guess pressure with [unit](/input-unit-set)          |
| totalVolume        | [valueObject](/terms-definition) | specified total volume with [unit](/input-unit-set)                       |
| calculatedVariable | string                           | variable to be calculated, i.e. "temperature" or "pressure"               |
| inflows            | object                           | specified inflow species composition, see [Inflows Input](/inflows-input) |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

### Response (status = PROCESSED)

{% tabs %}
{% tab title="temperature" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
            "calculatedVariables": [
                {
                    "name": "temperature",
                    "unit": "°C",
                    "value": 65.35602277638554
                }
            ],
            ...<snip>...
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}

{% tab title="pressure" %}

```javascript
{
    "code": 200,
    "data": {
        "result": {
            "calculatedVariables": [
                {
                    "name": "pressure",
                    "unit": "atm",
                    "value": 0.8025085833327293
                }
            ],
            ...<snip>...
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

The output of this calculation is the [**stream output** ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output). In addition to this output the result also contains the solution temperature/pressure which can be conveniently retrieved from the **data.result.calculatedVariables** array&#x20;

| data.result.calculatedVariables [\[ { } \]](/terms-definition) | type   | description                                                                                                                                                |
| -------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                                                           | string | name of the calculated variable, i.e. temperature or pressure as specified in input **params.calculatedVariable**                                          |
| value                                                          | number | value of the calculated variable                                                                                                                           |
| unit                                                           | string | unit of the calculated variable, which is the same as specified in the input initial guess, i.e. **params.temperature.unit/params.pressure.unit** in input |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |
| "/params/totalVolume/value"                  |


# set pH flash

This function calculates the equilibrium solution at a specified pH by varying inflows of acid and/or base titrant(s).

## set pH

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/setph`

fix the pH of the aqueous phase by varying acid/base amount

#### 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://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "targetPH": {
            "value": 8.0,
            "unit": ""
        },
        "pHAcidTitrant": "HCL",
        "pHBaseTitrant": "NAOH",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 20.0,
                "BENZENE": 10.0,
                "HCL": 0.0,
                "NAOH": 0.0
            }
        }
    }
}
```

| **params**    | type                             | description                                                         |
| ------------- | -------------------------------- | ------------------------------------------------------------------- |
| temperature   | [valueObject](/terms-definition) | specified or initial guess temperature with [unit](/input-unit-set) |
| pressure      | [valueObject](/terms-definition) | specified or initial guess pressure with [unit](/input-unit-set)    |
| targetPH      | value                            | specified target pH of the solution                                 |
| pHAcidTitrant | string                           | inflow species name for pH acid titrant                             |
| pHBaseTitrant | string                           | inflow species name for pH base titrant                             |

{% hint style="danger" %}
One or both of **params.pHAcidTitrant** and **params.pHBaseTitrant** need to be specified. If only one titrant is to be specified, it is the same to specify it as **params.pHAcidTitrant** or **params.pHBaseTitrant** regardless of the chemical nature of the solvent.
{% endhint %}

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

### Response (status = PROCESSED)

```javascript
{
    "code": 200,
    "data": {
        "result": {
            "addedTitrants": [
                {
                    "name": "NAOH",
                    "titrantType": "Base",
                    "unit": "mol",
                    "value": 9.998955177015539
                }
            ],
            ...<snip>...
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

The output of this calculation is the [**stream output** ](/stream-output-json)which is common result output for all OLI's flash calculations or an [**error**](/error-output)**.** In addition to this output the result also contains the amounts of added titrants and can be conveniently retrieved from the **data.result.addedTitrants** array&#x20;

| data.result.addedTitrants [\[ { } \]](/terms-definition) | type   | description                                                                                       |
| -------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| titrantType                                              | string | titrant type, i.e. "Acid" or "Base". This field will be missing if only one titrant is specified. |
| name                                                     | string | inflow name of the titrant                                                                        |
| value                                                    | number | added titrant amount                                                                              |
| unit                                                     | string | unit of added titrant amount                                                                      |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |
| "/params/targetPH/value"                     |


# Precipitation point flash

This function calculates the equilibrium solution at the precipitation point of a specified solid species by varying one inflow species.

## precipitation point

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/precipitation-point`

determine the minimum amount of an inflow species required to precipitate a solid

#### 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://devapi.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": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "solidToPrecipitate": "NACLPPT",
        "inflowToAdjust": "NACL",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 0.0,
                "BENZENE": 10.0
            }
        }
    }
}
```

| **params**         | type                             | description                                                                                |
| ------------------ | -------------------------------- | ------------------------------------------------------------------------------------------ |
| temperature        | [valueObject](/terms-definition) | specified or initial guess temperature with unit                                           |
| pressure           | [valueObject](/terms-definition) | specified or initial guess pressure with unit                                              |
| solidToPrecipitate | string                           | specified **solid species** at precipitation point                                         |
| inflowToAdjust     | string                           | **inflow species** whose amount is to be adjusted to achieve precipitation point condition |

{% hint style="info" %}
**params.solidToPrecipitate** and **params.inflowToAdjust** are species and inflow names retrieved from the [chemistry information](/group1/api-functions/chemistry-info) call, under **result.species(trueName)** and **result.inflows(baseName)** respectively.&#x20;
{% endhint %}

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

### Response (status = PROCESSED)

```javascript
{
    "code": 200,
    "data": {
        "result": {
           "calculatedVariables": [
                {
                    "name": "NACL",
                    "type": "inflow",
                    "unit": "mol",
                    "value": 5.531398835682553
                }
            ],
            ...<snip>...
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output). In addition to this output the result also contains the amount of the added  inflow (**params.inflowToAdjust**) can be conveniently retrieved from the **data.result.calculatedVariables** array

| <p>data.result.calculatedVariables</p><p><a href="/terms-definition"> </a><a href="/terms-definition">\[ { } ]</a></p> | type   | description                                                  |
| ---------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------ |
| type                                                                                                                   | string | type of calculated variable, i.e. inflow amount for "inflow" |
| name                                                                                                                   | string | name of adjusted inflow species                              |
| value                                                                                                                  | number | the final amount of adjusted inflow                          |
| unit                                                                                                                   | string | [unit](/input-unit-set) of inflow amount                     |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |


# Autoclave

{% hint style="danger" %}
This calculation is currently not supported
{% endhint %}

The **oliengine.autoclaveFlash** function mimics the autoclave application, which is a high pressure, high temperature hydrometallurgy unit with carefully controlled conditions.

{% hint style="info" %}
For this example purposes, let's assume the chemistry model file contains H2O, NACL, CO2, and CH4 as inflows in the MSE Thermodynamic framework
{% endhint %}

## JSON input (sample)

```javascript
{
    "method": "oliengine.autoclaveFlash",
    "params": {
        "ambientTemperature": {
            "value": 40.0,
            "unit": "°C"
        },
        "finalTemperature": {
            "value": 50.0,
            "unit": "°C"
        },
        "finalPressure": {
            "value": 2.0,
            "unit": "atm"
        },
        "vesselVolume": {
            "unit": "L",
            "value": 500.0
        },
        "computeAmbientCondition": true,
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "CO2": 10.0,
                "NACL": 0.1,
                "CH4": 10.0
            },
            "totalAmount":
            {
                "value": 70.1,
                "unit": "mol"
            }
        },
        "gasSpecifications": {
            "targetGases": [
                "CH4",
                "CO2"
            ],
            "specifiedTypePartialPressure": false,
            "unit": "mole %",
            "specifiedGasValues": {
                "CO2": 15.0
            }
        },
        ...<snip>...
}
```

{% hint style="info" %}
Most flash calls for OLI API follows a very similar input to describe the calculation with minor variation to specify calculation specific information
{% endhint %}

| **params**              | type        | description                                |
| ----------------------- | ----------- | ------------------------------------------ |
| ambientTemperature      | valueObject | temperature at ambient condition with unit |
| finalTemperature        | valueObject | temperature at final condition with unit   |
| finalPressure           | valueObject | pressure at final condition with unit      |
| vesselVolume            | valueObject | vessel volume with unit                    |
| computeAmbientCondition | boolean     | flash calculation condition                |

{% hint style="info" %}
A **valueObjec**t type is defined as JSON object of the type **{"value": number, "unit": "string" }**
{% endhint %}

{% hint style="info" %}
**params.temperature.unit**: °C, K, °F, R

**params.pressure.unit**: atm, bar, barg, mbar, Pa, kPa, MPa, mmHg, Torr, inHg, psia, psig, inH2O, kg/cm2

**params.computeAmbientCondition**:&#x20;

true: compute flash at ambient condition;&#x20;

false: compute flash at final condition
{% endhint %}

### Gas specification

| **params.gasSpecifications** | type      | description                                               |
| ---------------------------- | --------- | --------------------------------------------------------- |
| targetGases                  | \[string] | list of any number of gas species names as targeted gases |
| specifiedTypePartialPressure | boolean   | type of targeted gas composition                          |
| unit                         | string    | unit of targeted gas composition                          |
| specifiedGasValues           | object    | specified gas composition by {gas\_name: amount}          |

{% hint style="info" %}
**params.gasSpecifications.specifiedTypePartialPressure**:&#x20;

true: targeted gas composition specified by partial pressure. **params.gasSpecifications.unit** from atm, bar, barg, mbar, Pa, kPa, MPa, mmHg, Torr, inHg, psia, psig, inH2O, kg/cm2

false: targeted gas composition specified by mole fraction(s) in aqueous phase. **params.gasSpecifications.unit** from mol/mol, mole %, ppm (mole)
{% endhint %}

{% hint style="info" %}
**params.gasSpecifications.specifiedGasValues**: The number of specified gas should be the number of **gasSpecifications.targetGases** -1
{% endhint %}

{% hint style="info" %}
**params.gasSpecifications.targetGases** and the keys of **params.gasSpecifications.specifiedGasValues** are the inflow names of gas species, which can be retrieved from [oliengine.getChemistryInfo](/group1/api-functions/chemistry-info) call under **result.inflows**.
{% endhint %}

### Optional inputs

Some optional inputs can be specified in JSON input, see [Optional Inputs](/optional-inputs).

## JSON output (example)

```javascript
{
    "result": {
        "phases": {
            "liquid1": {
                ...<snip>...
                }
            },
            "vapor": {
                ...<snip>...
            },
            "solid": {
                ...<snip>...
            },
            "liquid2": {
                ...<snip>...
            }
        },
        "phaseSummary": [
            {
                "phase": "liquid1",
                "found": true
            },
            {
                "phase": "vapor",
                "found": true
            },
            {
                "phase": "solid",
                "found": false
            },
            {
                "phase": "liquid2",
                "found": false
            }
        ],
        "total": {
            "totalMolecularMoles": {
                "value": 85.54088467359415,
                "unit": "mol"
            },
            ...<snip>...
        },
        "calculatedVariable": [
            {
                "type": "calculatedParameter",
                "name": "ambientTemperature",
                "value": 40.0,
                "unit": "°C"
            },
            {
                "type": "calculatedParameter",
                "name": "ambientPressure",
                "value": 1.892610720086249,
                "unit": "atm"
            },
            {
                "type": "calculatedParameter",
                "name": "finalTemperature",
                "value": 50.0,
                "unit": "°C"
            },
            {
                "type": "calculatedParameter",
                "name": "finalPressure",
                "value": 2.0,
                "unit": "atm"
            },
            {
                "type": "calculatedParameter",
                "name": "vesselVolume",
                "value": 500.0,
                "unit": "L"
            },
            {
                "type": "inflow",
                "name": "CH4",
                "value": 35.43088467359407,
                "unit": "mol"
            },
            {
                "type": "inflow",
                "name": "CO2",
                "value": 0.009999999999999998,
                "unit": "mol"
            }
        ]
    }
}
```

This represents the **stream output JSON**, which is common to all OLI's flash calculation results. Here a condensed version of the output is shown with many major parts removed. A better description of the stream output is given here: [Stream output JSON](/stream-output-json)

| result.calculatedVariable \[{}] | type   | description                  |
| ------------------------------- | ------ | ---------------------------- |
| type                            | string | type of calculated variable  |
| name                            | string | name of calculated variable  |
| value                           | number | value of calculated variable |
| unit                            | string | unit of calculated variable  |


# Custom flash

This function calculates equilibrium condition with any number of fixed and freed system parameters.

## custom&#x20;

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/custom`

run a custom equilibrium calculation

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

```json
{
    "params": {
        "temperature": {
            "value": 40.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "fixedVars": [
            {
                "type": "vaporPhaseComposition",
                "name": "BENZENEVAP",
                "value": 16.0,
                "unit": "mole %"
            },
            {
                "type": "property",
                "name": "volume",
                "value": 440.0,
                "unit": "L"
            }
        ],
        "freedVars": [
            {
                "type": "inflow",
                "name": "BENZENE",
                "value": 0.0,
                "unit": "mol"
            },
            {
                "type": "state",
                "name": "temperature",
                "value": 0.0,
                "unit": "°C"
            }
        ],
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "BENZENE": 10.0,
                "CH4": 20.0,
                "NACL": 35.0
            },
            "totalAmount":
            {
                "value": 115.0,
                "unit": "mol"
            }
        }
}
```

| **params**  | type                             | description                                                         |
| ----------- | -------------------------------- | ------------------------------------------------------------------- |
| temperature | [valueObject](/terms-definition) | specified or initial guess temperature with [unit](/input-unit-set) |
| pressure    | [valueObject](/terms-definition) | specified or initial guess pressure with [unit](/input-unit-set)    |
| fixedVars   | array of objects                 | list of objects to describe fixed flash output variables            |
| freedVars   | array of objects                 | list of objects to describe freed flash input variables             |

{% hint style="danger" %}
The sizes of the object arrays, **params.fixedVars** and **params.freedVars** must be equal&#x20;
{% endhint %}

#### Here is a description of the **type** and **name** attributes for the **params.fixedVars** array

| **params.fixedVars\[*****index\_number*****].type** | **params.fixedVars\[*****index\_number*****].name** |
| --------------------------------------------------- | --------------------------------------------------- |
| property                                            | volume, enthalpy, pH                                |
| liquid1PhaseComposition                             | species name of liquid phase                        |
| liquid2PhaseComposition                             | species name of liquid phase                        |
| vaporPhaseComposition                               | species name of vapor phase                         |
| solid                                               | species name of solid phase                         |

{% hint style="info" %}
species name can be retrieved from [chemistry information call](/group1/api-functions/chemistry-info) under **result.species(trueName)**, respectively.
{% endhint %}

#### Here is a description of the **unit** attribute for the **params.fixedVars** array

| **params.fixedVars\[*****index\_number*****].type or .name**            | **params.fixedVars\[*****index\_number*****].unit**           |
| ----------------------------------------------------------------------- | ------------------------------------------------------------- |
| liquid1PhaseComposition, liquid2PhaseComposition, vaporPhaseComposition | mol/mol, mole %, ppm (mole)                                   |
| solid                                                                   | mol, kgmol, lbmol, mmol, µmol, (mol/100)                      |
| volume                                                                  | L, ml, cm3, m3, E3m3, E6m3, ft3, Mft3, MMft3, gal, MMgal, bbl |
| enthalpy                                                                | cal, E3cal, E6cal, J, kJ, MJ, Btu, MMBtu                      |

#### This section explains the available flash input variables can be freed for this calculation

| **params.freedVars\[*****index\_number*****].type** | **params.freedVars\[*****index\_number*****].name** | **params.freedVars\[*****index\_number*****].unit**                             |
| --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
| state                                               | temperature                                         | °C, K, °F, R                                                                    |
| state                                               | pressure                                            | atm, bar, barg, mbar, Pa, kPa, MPa, mmHg, Torr, inHg, psia, psig, inH2O, kg/cm2 |
| inflow                                              | inflow name                                         | mol, kgmol, lbmol, mmol, µmol, (mol/100)                                        |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

### JSON output (status = PROCESSED)

```javascript
{
    "code": 200,
    "data": {
        "result": {
            ...<snip>...
            "calculatedVariables": [
                {
                    "name": "BENZENE",
                    "value": 4.048793029736938,
                    "unit": "mol"
                },
                {
                    "name": "temperature",
                    "value": 45.5766850916292,
                    "unit": "°C"
                }
            ]
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output). In addition to this output the result also contains the values of the free variables which can be conveniently retrieved from the **result.calculatedVariables** array&#x20;

| result.calculatedVariables [\[{}\]](/terms-definition) | type   | description                     |
| ------------------------------------------------------ | ------ | ------------------------------- |
| name                                                   | string | name of calculated variable     |
| value                                                  | number | value of calculated variable    |
| unit                                                   | string | unit of the calculated variable |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field**                                                                  |
| ------------------------------------------------------------------------------------------------------------- |
| "/params/temperature/value"                                                                                   |
| "/params/pressure/value"                                                                                      |
| "/params/fixedVars/***i***/value" where ***i*** is the index (0 based) of **params.fixedVars** to be surveyed |
| "/params/freedVars/***i***/value" where ***i*** is the index (0 based) of **params.freedVars** to be surveyed |


# Corrosion contact surfaces

This function is used to obtain the name of contact surface metals which OLI supports for corrosion rate calculations. &#x20;

## corrosion contact surface

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/engine/file/{dbs_file_id}/corrosion-contact-surface`

get the corrosion contact surfaces applicable for the given chemistry model

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% 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 %}

### Response (status = PROCESSED)

```javascript
{
    "data": {
        "result": {
            "contactSurfaces": {
                "Aluminum": [
                    "Aluminum 1199 (pure)",
                    "Aluminum 1100"
                ],
                "Copper based alloy": [
                    "Cu",
                    "CuNi 9010",
                    "CuNi 7030"
                ],
                "Iron/Mild steel": [
                    "Fe (zone refined)",
                    "Fe (pure)",
                    "Carbon steel G10100 (generic)",
                    "Carbon steel A212B",
                    "Carbon steel A216",
                    "Carbon steel 1018"
                ],
                "Nickel based alloy": [
                    "Ni",
                    "Alloy 600",
                    "Alloy 690",
                    "Alloy 825",
                    "Alloy 625",
                    "Alloy C-276",
                    "Alloy C-22",
                    "Alloy 28",
                    "Alloy 29",
                    "Alloy 2535",
                    "Alloy 2550"
                ],
                "Stainless steel": [
                    "13%Cr stainless steel",
                    "Super13Cr stainless steel",
                    "Super15Cr stainless steel",
                    "Super17Cr stainless steel",
                    "Stainless steel 304",
                    "Stainless steel 316",
                    "Alloy 254SMO",
                    "Duplex stainless 2205",
                    "Duplex stainless 2507"
                ]
            }
        }
    },
    "message": "Results returned successfully",
    "status": "PROCESSED"
}
```

{% hint style="warning" %}
The keys inside **data.result.contactSurfaces** are the class names of contact surface metals. Each class holds the available contact surface metals under it. Not all class names might be shown in the result. This depends on the metal element inflows that are specified in the chemistry model.&#x20;
{% endhint %}

| data.result.contactSurfaces | type      | required inflow in chemistry model |
| --------------------------- | --------- | ---------------------------------- |
| Iron/Mild steel             | \[string] | FEEL                               |
| Stainless steel             | \[string] | FEEL                               |
| Aluminum                    | \[string] | ALEL                               |
| Nickel based alloy          | \[string] | NIEL                               |
| Copper based alloy          | \[string] | CUEL                               |


# Corrosion rates

This function calculates the corrosion rates of a given metal contact surface under a specified solution condition.

{% hint style="danger" %}
This calculation is currently only supported for the **AQ thermodynamic framework**
{% endhint %}

## corrosion rates

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/corrosion-rates`

calculate the corrosion rate

#### 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": {
        "temperature": {
            "value": 40.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "calculationType": "isothermal",
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "NACL": 0.01,
                "HNO3": 1,
                "FEEL": 0.0
            },
            "totalAmount":
            {
                "value": 51.01,
                "unit": "mol"
            }
        },
        "corrosionParameters":
        {
            "contactSurface": "Carbon steel G10100 (generic)",
            "flowType": "static"
        }
}
```

| **params**      | type                             | description                                                         |
| --------------- | -------------------------------- | ------------------------------------------------------------------- |
| temperature     | [valueObject](/terms-definition) | specified or initial guess temperature with [unit](/input-unit-set) |
| pressure        | [valueObject](/terms-definition) | specified or initial guess pressure with [unit](/input-unit-set)    |
| calculationType | string                           | single point flash calculation type of solution, e.g. isothermal    |

{% hint style="danger" %}
**params.calculationType** currently only supports the "isothermal" type.
{% endhint %}

### Corrosion parameters

| **params.corrosionParameters** | type   | description                                                                                                                           |
| ------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| contactSurface                 | string | contact surface metal name, which can be retrieved from [Corrosion contact surfaces](/group1/api-functions/corrosion-contact-surface) |
| flowType                       | string | flow configuration                                                                                                                    |

#### Options for flowType

| **params.corrosionParameters.flowType** | description                                                                |
| --------------------------------------- | -------------------------------------------------------------------------- |
| static                                  | mimics static flow                                                         |
| pipeFlow                                | mimics pipe flow                                                           |
| rotatingDisk                            | several parallel disks that are rotating                                   |
| rotatingCylinder                        | several parallel cylinders that are rotating                               |
| completeAgitation                       | liquid phase is completely agitated and no mass transfer limitations apply |
| definedShearStress                      | define the stress of applied force over material                           |
| approximateMultiPhaseFlow               | mimics an approximate multi-phase flow                                     |

{% hint style="info" %}
Additional corrosion parameters may be required for different flow types, which are explained as below
{% endhint %}

#### Additional parameters if flowType is pipeFlow

```javascript
{
    "params": {
        ...<snip>...,
        "corrosionParameters":
        {
            "contactSurface": "Carbon steel G10100 (generic)",
            "flowType": "pipeFlow",
            "pipeDiameter": {
                "value": 0.05,
                "unit": "m"
            },
            "pipeFlowVelocity": {
                "value": 6.0,
                "unit": "ft/s"
            }
        },
        ...<snip>...
}
```

| **params.corrosionParameters** | type                             | description                                    |
| ------------------------------ | -------------------------------- | ---------------------------------------------- |
| pipeDiameter                   | [valueObject](/terms-definition) | pipe diameter and [unit](/inflows-input)       |
| pipeFlowVelocity               | [valueObject](/terms-definition) | pipe flow velocity and [unit](/input-unit-set) |

#### Additional parameters if flowType is rotatingDisk

```javascript
{
    "params": {
        ...<snip>...,
        "corrosionParameters":
        {
            "contactSurface": "Carbon steel G10100 (generic)",
            "flowType": "rotatingDisk",
            "diskDiameter": {
                "value": 0.6,
                "unit": "in"
            },
            "diskRotationSpeed": {
                "value": 15.0,
                "unit": "cycle/s"
            }
        },
        ...<snip>...
}
```

| **params.corrosionParameters** | type                             | description                                     |
| ------------------------------ | -------------------------------- | ----------------------------------------------- |
| diskDiameter                   | [valueObject](/terms-definition) | disk diameter and [unit](/input-unit-set)       |
| diskRotationSpeed              | [valueObject](/terms-definition) | disk rotation speed and [unit](/input-unit-set) |

#### Additional parameters if flowType is rotatingCylinder

```javascript
{
    "params": {
        ...<snip>...,
        "corrosionParameters":
        {
            "contactSurface": "Carbon steel G10100 (generic)",
            "flowType": "rotatingCylinder",
            "rotorDiameter": {
                "value": 5,
                "unit": "mm"
            },
            "rotorRotation": {
                "value": 1000,
                "unit": "cycle/min"
            }
        },
        ...<snip>...
}
```

| **params.corrosionParameters** | type                             | description                                      |
| ------------------------------ | -------------------------------- | ------------------------------------------------ |
| rotorDiameter                  | [valueObject](/terms-definition) | rotor diameter and [unit](/input-unit-set)       |
| rotorRotation                  | [valueObject](/terms-definition) | rotor rotation speed and [unit](/input-unit-set) |

#### Additional parameters if flowType is definedShearStress

```javascript
{
    "params": {
        ...<snip>...,
        "corrosionParameters":
        {
            "contactSurface": "Carbon steel G10100 (generic)",
            "flowType": "definedShearStress",
            "shearStress": {
                "value": 0.01,
                "unit": "kPa"
            }
        },
        ...<snip>...
}
```

| **params.corrosionParameters** | type                             | description                              |
| ------------------------------ | -------------------------------- | ---------------------------------------- |
| shearStress                    | [valueObject](/terms-definition) | shear stress and [unit](/input-unit-set) |

#### Additional parameters if flowType is approximateMultiPhaseFlow

```javascript
{
    "params": {
        ...<snip>...,
        "corrosionParameters":
        {
            "contactSurface": "Carbon steel G10100 (generic)",
            "flowType": "approximateMultiPhaseFlow",
            "pipeDiameter": {
                "value": 10.0,
                "unit": "cm"
            },
            "liquidFlowInPipe": {
                "value": 0.2,
                "unit": "m3/s"
            },
            "gasFlowInPipe": {
                "value": 0.1,
                "unit": "m3/s"
            },
            "pipeRoughness": {
                "value": 0.15,
                "unit": "cm"
            },
            "viscAbs2ndLiq": {
                "value": 15.0,
                "unit": "cP"
            },
            "waterCutAtPointOfDispersionInversion": 0.7,
            "maxRelViscosityOfDispersionAtInversion": 10.0
        },
        ...<snip>...
}
```

| **params.corrosionParameters**         | type                             | description                                                  |
| -------------------------------------- | -------------------------------- | ------------------------------------------------------------ |
| pipeDiameter                           | [valueObject](/terms-definition) | pipe diameter and [unit](/input-unit-set)                    |
| liquidFlowInPipe                       | [valueObject](/terms-definition) | liquid flow in pipe and [unit](/input-unit-set)              |
| gasFlowInPipe                          | [valueObject](/terms-definition) | gas flow in pipe and [unit](/input-unit-set)                 |
| pipeRoughness                          | [valueObject](/terms-definition) | pipe roughness and [unit](/input-unit-set)                   |
| viscAbs2ndLiq                          | [valueObject](/terms-definition) | absolute viscosity of 2nd liquid and [unit](/input-unit-set) |
| waterCutAtPointOfDispersionInversion   | number                           | water cut at point of dispersion inversion                   |
| maxRelViscosityOfDispersionAtInversion | number                           | max relative viscosity of dispersion at inversion            |

{% hint style="info" %}
in addition to the inputs shown above some optional properties may also be specified. They can be viewed [here](/optional-inputs)
{% endhint %}

### Response (status = "PROCESSED")

```javascript
{
    "code": 200,
    "data": {
        "result": {
           ...<snip>...
            "corrosionOutputs": {
                "corrosionPotential": {
                    "value": -0.2751504098799078,
                    "unit": "V (SHE)"
                },
                "repassivationPotential": {
                    "value": -0.4851063187462839,
                    "unit": "V (SHE)"
                },
                "corrosionRateGPerMsqDay": {
                    "value": 382.2467320945027,
                    "unit": "g/m3-day"
                },
                "corrosionRateMmPerYear": {
                    "value": 17.728088591422296,
                    "unit": "mm/yr"
                },
                "corrosionRateMilPerYear": {
                    "value": 697.9562437567834,
                    "unit": "mil/yr"
                },
                "corrosionCurrentDensity": {
                    "value": 15.288766842782513,
                    "unit": "A/sq-m"
                },
                "maximumPitCurrentDensity": {
                    "value": 23.87887042448192,
                    "unit": "A/sq-m"
                }
            }
        }
    }, 
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output). In addition to this output the the corrosion output information can be conveniently retrieved from the **data.result.corrosionOutputs** array&#x20;

| data.result.corrosionOutputs | type                             | description                                |
| ---------------------------- | -------------------------------- | ------------------------------------------ |
| corrosionPotential           | [valueObject](/terms-definition) | corrosion potential                        |
| repassivationPotential       | [valueObject](/terms-definition) | repassivation potential                    |
| corrosionRateGPerMsqDay      | [valueObject](/terms-definition) | corrosion rate in gram per cubic meter day |
| corrosionRateMmPerYear       | [valueObject](/terms-definition) | corrosion rate in mm per year              |
| corrosionRateMilPerYear      | [valueObject](/terms-definition) | corrosion rate in mil per year             |
| corrosionCurrentDensity      | [valueObject](/terms-definition) | corrosion current density                  |
| maximumPitCurrentDensity     | [valueObject](/terms-definition) | maximum pit current density                |

{% hint style="warning" %}
All output units are fixed to what is shown in this example
{% endhint %}

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |


# 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="/terms-definition">\[ { } ]</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).

### specifying volume

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

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

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

{% hint style="info" %}
**name** and **charge** can be retrieved using [chemistry information](/group1/api-functions/chemistry-info) 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).

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

```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) 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).

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

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

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

### Survey Calculation

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


# Additional methods


# Flash history - Chemistry model

## flash history&#x20;

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/engine/flash/history/{dbs_file_id}`

retrieves the history of flash information, such as input for a given chemistry model

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% tabs %}
{% tab title="200 Response is an array of jobs submitted" %}

```
{
	"code": 200,
	"data": [
		{
			"flashInput": {...},
			"jobId": "188f614a-cfd9-4100-aa5a-4491287b34d7",
			"status": "PROCESSED"
		}
	],
	"message": "Results returned successfully",
	"status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

### Response description

Contains an array of jobs submitted in the **data** field

| field               | description                                                                  |
| ------------------- | ---------------------------------------------------------------------------- |
| code                | HTTP response status code                                                    |
| data\[n].flashInput | Input that was sent for the flash calculation                                |
| data\[n].jobId      | id that was created for the specific run                                     |
| data\[n].status     | status of the job. can be **"PROCESSED"**, **"IN PROGRESS"** or **"FAILED"** |
| message             | status message for this request                                              |
| status              | status of this request                                                       |


# Result - by jobId

## retrieves the result for a given jobId

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/result/flash/{jobId}`

return the result of a calculation given the jobId

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% tabs %}
{% tab title="200 " %}

```
{
	"code": 200,
	"data": {
		"result": {...}
	},
	"message": "Results returned successfully",
	"status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

### Response definition

| field   | description                             |
| ------- | --------------------------------------- |
| code    | HTTP response status code               |
| data    | contains result or error of calculation |
| message | status message for this request         |
| status  | status of this request                  |


# delete file

## delete file

<mark style="color:red;">`DELETE`</mark> `https://api.olisystems.com/channel/file/{dbs_file_id}`

delete a dbs file by its file id

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "File deleted successfully",
    "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}


# cancel run

## cancel run

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/cancel/run/{jobId}`

attempts to cancel a run given its jobId

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Job Cancellation request submitted Successfully",
    "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}


# Inflows input

This page explains the **params.inflows** object that is required as an input for most flash calculations.&#x20;

### JSON input (example)

```javascript
    "params": {
        ...<snip>...
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "BENZENE": 10.0,
                "CH4": 20.0,
                "NAOH": 35.0
            },
            "totalAmount": {
                "value": 3402.68,
                "unit": "g"
            }
        }
        ...<snip>...
    }
```

<table data-header-hidden><thead><tr><th width="177.87372218881546">params.inflows</th><th width="154.33333333333331">type</th><th>description</th></tr></thead><tbody><tr><td>params.inflows</td><td>type</td><td>description</td></tr><tr><td>unit</td><td>string</td><td>unit for inflows</td></tr><tr><td>values</td><td>object</td><td>the amount of each inflow specified as <strong>"inflow_name": number</strong>. Species with zero amount need not be specified.</td></tr><tr><td>totalAmount</td><td><a href="/terms-definition">valueObject</a></td><td>optional total stream amount</td></tr></tbody></table>

{% hint style="warning" %}
**params.inflows.totalAmount** is optional. However, when it's specified and conflicts with the summation of inflows, the totalAmount takes priority, and **params.inflows.values** are normalized proportionally.
{% endhint %}

### Units in batch systems

| unit types    | units                                                             |
| ------------- | ----------------------------------------------------------------- |
| moles         | mol, nmol, kgmol, nanomol, lbmol, micromol, µmol, mmol, (mol/100) |
| mole fraction | `mol/mol, mole %, ppm (mole)`                                     |
| mass          | mg, kg, nanog, lb, µg, microg, ng, g, tonne, (g/100)              |
| mass fraction | `g/g, mass %, ppm (mass)`                                         |

{% hint style="info" %}
**params.inflows.unit** can be specified from any units as listed in the above table.&#x20;
{% endhint %}

### Units in flowing systems

Unit types of moles and mass can be specified in flowing system by dividing a time unit, i.e. "mol/hr". Available time units are "s", "min", "hr", "day", "yr".&#x20;

### Unit consistency between inflows and total amount

Unit for **params.inflows.totalAmount** needs to be consistent with inflows as explained below:

| **params.inflows.unit**         | **params.inflows.totalAmount.unit**                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| moles or mass in batch system   | Optional. If specified, it can be any moles or mass units in batch system. And **params.inflows** will be scaled to match the total amount.                         |
| moles or mass in flowing system | Optional. If specified, it can be any moles or mass units in flowing system. And **params.inflows** will be scaled to match the total amount.                       |
| mole fraction or mass fraction  | Optional. If specified, it can be any moles or mass units in batch or flowing system. If not specified, a total amount of 100 mole in batch system will be assumed. |

### Normalize option (optional)

{% tabs %}
{% tab title="prorate" %}

```json
    "params": {
        ...<snip>...
        "inflows": {
            "unit": "mole %",
            "values": {
                "H2O": 50.0,
                "BENZENE": 10.0,
                "CH4": 20.0,
                "NAOH": 35.0
            },
            "normalize": {
                "option": "prorate"
            }
        }
        ...<snip>...
    }    
```

{% endtab %}

{% tab title="make up component" %}

```json
    "params": {
        ...<snip>...
        "inflows": {
            "unit": "mole %",
            "values": {
                "H2O": 50.0,
                "BENZENE": 10.0,
                "CH4": 20.0,
                "NAOH": 35.0
            },
            "normalize": {
                "option": "makeup",
                "makeupComponent": "CH4"
            }
        }
        ...<snip>...
    }   
```

{% endtab %}
{% endtabs %}

When specified from mole fraction units, inflow values will be normalized if they don't add up to 100%. Different normalization options could be specified as below:

| params.inflows.normalize.option | description                                                                                                                                     |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| "prorate"                       | All specified inflow values will be prorated                                                                                                    |
| "makeup"                        | One inflow component will be added or removed for normalization. **params.inflows.normalize.option.makeupComponent** specifies the inflow name. |

{% hint style="info" %}
"prorate" option is used by default if **params.inflows.normalize** object is not specified.
{% endhint %}

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/inflows/values/*\<InflowName>*"     |
| "/params/inflows/totalAmount/value"          |

{% hint style="warning" %}
When specific inflow value(s) is changed in the survey calculation and the total amount is given, the total amount will not be modified in survey input unless it's specified. In other words, the survey calculation will only overwrite the specified value field(s) to construct a series of JSON inputs to perform single-point calculations.
{% endhint %}


# Optional inputs

In addition to the mandatory inputs required for the various [flash calculations](/group1/api-functions), three additional inputs may also be present to control the calculation or for requesting additional data in the output. These are:-

* included/excluded solids
* optional properties
* output units

{% hint style="info" %}
In this example, let's assume the chemistry model file contains **H2O, NACL, CO2** and **BENZENE** as inflows and is using the **MSE thermodynamic framework.**&#x20;
{% endhint %}

### include or exclude solid species from precipitating&#x20;

OLI flash computations by default account for the formation of all solid species in the chemistry model. However, users can choose a subset of solid species in the computation by specifying them in the **params.excludedSolids** or **params.includedSolids** array.  Example input and description are given below.&#x20;

Note: Solids must be specified using the fully qualified tag. This is returned as the trueName when using the [Chemistry Info](/group1/api-functions/chemistry-info)[rmation](/group1/api-functions/chemistry-info) API.

{% tabs %}
{% tab title="exclude solids" %}

```javascript
"excludedSolids": [
            "NAOH.2H2O",
            "NAOH.4H2O",
            "NACLPPT"
        ]
```

{% endtab %}

{% tab title="exclude all solids" %}

```javascript
"includedSolids": [] 
```

{% endtab %}

{% tab title="include solids" %}

```javascript
"includedSolids": [
            "NAOH.2H2O",
            "NAOH.4H2O",
            "NACLPPT"
        ]
```

{% endtab %}
{% endtabs %}

| **params**     | type      | description                                                                                                      |
| -------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| excludedSolids | \[string] | list of excluded solid species in the flash computation                                                          |
| includedSolids | \[string] | list of included solid species in flash computation, if an empty array is specified, all solids will be excluded |

{% hint style="warning" %}
**params.excludedSolids** and **params.includedSolids** cannot be specified at the same time.&#x20;
{% endhint %}

### Optional properties

After the equilibrium solution is obtained, the user has the option to specify a number of optional properties to be computed along with this output. These can be turned on or off using a Boolean flag (true/false) in the **params.optionalProperties** objec&#x74;**.** Example input and description is given below

```javascript
{
    "params": {
        ...<snip>...
        "optionalProperties": {
            "electricalConductivity": true,
            "viscosity": true,
            "selfDiffusivity": true,
            "heatCapacity": true,
            "thermalConductivity": true,
            "surfaceTension": true,
            "interfacialTension": true,
            "prescalingTendencies": true
        }
    }
}
```

| params.optionalProperties       | type | desc                                                                |
| ------------------------------- | ---- | ------------------------------------------------------------------- |
| electricalConductivity          | bool | Electrical conductivity of the liquid phase                         |
| viscosity                       | bool | Viscosity for any liquid or gas phases                              |
| selfDiffusivityAndMobility      | bool | Self diffusivity and mobility for any liquid or gas phases          |
| heatCapacity                    | bool | Heat capacity for any phases                                        |
| thermalConductivity             | bool | Thermal conductivity for any phases                                 |
| surfaceTension                  | bool | Surface tension for any liquid phases                               |
| interfacialTension              | bool | Interfacial tension between liquid1 and liquid2 phases              |
| volumeStdConditions             | bool | liquid1, liquid2, and vapor phase volume at standard conditions     |
| prescalingTendenciesEstimated   | bool | prescaling tendencies of solids using the estimated method          |
| prescalingIndexEstimated        | bool | prescaling indices of solids using the estimated method             |
| prescalingTendenciesRigorous    | bool | prescaling tendencies of solids using the rigorous method           |
| prescalingIndexRigorous         | bool | prescaling indices of solids using the rigorous method              |
| scalingTendencies               | bool | scaling tendencies of solids                                        |
| scalingIndex                    | bool | scaling indices of solids                                           |
| hardness                        | bool | hardness of liquid1 phase                                           |
| ionicStrengthXBased             | bool | x-based ionic strength of any liquid phases                         |
| ionicStrengthMBased             | bool | m-based ionic strength of any liquid phases                         |
| totalDissolvedSolids            | bool | total dissolved solids in the liquid1 phase                         |
| vaporToInflowMoleFraction       | bool | vapor to inflow mole fraction                                       |
| partialPressure                 | bool | vapor phase partial pressures of all species                        |
| vaporDiffusivityMatrix          | bool | vapor diffusivity matrix                                            |
| entropyStream                   | bool | entropy of stream for all phases                                    |
| entropySpecies                  | bool | entropy of each species for all phases                              |
| entropyStreamStandardState      | bool | entropy of stream at standard state for all phases                  |
| entropySpeciesStandardState     | bool | entropy of each species at standard state for all phases            |
| gibbsEnergyStream               | bool | Gibbs free energy of stream for all phases                          |
| gibbsEnergySpecies              | bool | Gibbs free energy of each species for all phases                    |
| gibbsEnergyStreamStandardState  | bool | Gibbs free energy of stream at standard state for all phases        |
| gibbsEnergySpeciesStandardState | bool | Gibbs free energy of each species at standard state for all phases  |
| activityCoefficientsMBased      | bool | m-based activity coefficients of each species for all liquid phases |
| activityCoefficientsXBased      | bool | x-based activity coefficients of each species for all liquid phases |
| fugacityCoefficients            | bool | fugacity coefficients of each species for liquid2 and vapor phases  |
| vaporFugacity                   | bool | fugacities of each species for vapor phase                          |
| kValuesXBased                   | bool | x-based K-values for all equilibrium reactions                      |
| kValuesMBased                   | bool | x-based M-values for all equilibrium reactions                      |
| materialBalanceGroup            | bool | material balance group compositions for all phases                  |

{% hint style="warning" %}
**params.optionalProperties.volumeStdConditions** calculate liquid1, liquid2, and vapor phase volume at default standard conditions, which can be specified in [here](/optional-inputs#standard-conditions).
{% endhint %}

{% hint style="info" %}
**params.optionalProperties.scalingInductionTime** calculates induction time for scaling solids. Additional inputs are needed for this calculation and explained [here](#undefined). This property is only supported for MSE and MSE-SRK thermodynamic properties.
{% endhint %}

### Scaling Induction Time

Induction time is estimated based on the supersaturation level of the scaling solid. Therefore, such solids need to be excluded to calculate their induction times, as specified below.

```json
{
    "params": {
        ...<snip>...
        "inductionTimeExcludedSolids": [
            "ARAGONITEPPT",
            "BACO3PPT",
            "BASO4PPT",
            ...<snip>...
        ]
    }
}
```

#### Standard conditions

Standard conditions can be specified to calculate the optional property **params.optionalProperties.volumeStdConditions**.&#x20;

```javascript
{
    "params": {
        ...<snip>...
        "standardConditions": [
            {
                "phase": "oil",
                "temperature": {
                    "unit": "°C",
                    "value": 15.5556
                },
                "pressure": {
                    "unit": "atm",
                    "value": 1.0
                }
            },
            {
                "phase": "gas",
                ...<snip>...
            },
            {
                "phase": "aqueous",
                ...<snip>...
            }
        ]
    }
}
```

| params.standardConditions\[i] | type                                         | description                                          |
| ----------------------------- | -------------------------------------------- | ---------------------------------------------------- |
| phase                         | string                                       | name of the phase, which can be oil, aqueous, or gas |
| temperature                   | [valueObject](/terms-definition#valueobject) | standard condition temperature                       |
| pressure                      | [valueObject](/terms-definition#valueobject) | standard condition temperature                       |

| phase   | default temperature in °C | default pressure in atm |
| ------- | ------------------------- | ----------------------- |
| oil     | 15.5556                   | 1.0                     |
| gas     | 16.8500                   | 1.48038                 |
| aqueous | 25.0                      | 1.0                     |

### Output units&#x20;

Users can optionally specify units of the output values in the [Stream output](/stream-output-json). More details are explained in [User-defined output unit set](/user-defined-output-unit-set).&#x20;

{% hint style="info" %}
**params.unitSetInfo** is optional. OLIEngine default units will be used if this object is not specified.&#x20;
{% endhint %}

### Molecular conversion

There are two types of [speciation information](/stream-output-json#speciation-information) in the [stream output](/stream-output-json): true concentration and molecular concentration. While the true concentration reflects the speciation of the real species which is unique, the molecular concentration is one of many representations for the true species in molecular/inflow forms. Users have the option to specify three weighting methods for this molecular conversion:

```json
{
    "params": {
        ...<snip>...
        "molecularConversion": {
            "option": "userSpecified",
            "weightFactors": {
                "NAOH": 50.0,
                "CACO3": 10.0
            }
        }
    }    
}
```

| molecularConversion.option | description                                      |
| -------------------------- | ------------------------------------------------ |
| automatic                  | no weightage preference                          |
| inflowRateBased            | weightage is proportional to input inflow values |
| userSpecified              | user-specified weight factors for any inflows    |

{% hint style="info" %}
**molecularConversion.weightFactors** object is only specified when **molecularConversion.option** is "userSpecified". The weight factor of each inflow is specified as **"inflow\_name": number**, in the range from 0.0 to 100.0
{% endhint %}

{% hint style="info" %}
**params.molecularConversion** object is optional. By default, "inflowRateBased" option is used.
{% endhint %}

### JSON input (sample)

Below is the sample JSON input covering all three options using [isothermal flash](/group1/api-functions/isothermal) as an example.

```javascript
{
    "method": "oliengine.isothermalFlash",
    "params": {
        "temperature": {
            "value": 40.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "BENZENE": 10.0,
                "CH4": 20.0,
                "NAOH": 35.0
            },
            "totalAmount":
            {
                "value": 3402.68,
                "unit": "g"
            }
        },
        "excludedSolids": [
            "NAOH.2H2O",
            "NAOH.4H2O"
        ],
        "optionalProperties": {
            "electricalConductivity": true,
            "viscosity": true,
            "selfDiffusivity": true,
            "heatCapacity": true,
            "thermalConductivity": true,
            "surfaceTension": true,
            "interfacialTension": true,
            "prescalingTendencies": true
        },
        "unitSetInfo": {
            "inflows": "mol",
            "total": "g",
            "liq1_phs_comp": "mol/mol",
            ...<snip>...
            "hardness": "mg/L of Mg+2 and Ca+2",
            "tic": "mol C/L"
        }
}
```


# Kinetic calculation inputs

In addition to the mandatory inputs required for the various [flash calculations](/group1/api-functions), kinetic calculation inputs need to be specified in **params.kineticsParameters** if there are kinetic reactions defined in the chemistry model.

```javascript
{
    "params": {
        ...<snip>...
        "kineticsParameters": {
            "holdupTime": {
                "value": 100.0,
                "unit": "hr"
            },
            "numberSteps": {
                "value": 10,
                "unit": ""
            }
        }
    }
}
```

| params.kineticsParameters | type                             | description                                                                                                                       |
| ------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| holdupTime                | [valueObject](/terms-definition) | holdup time                                                                                                                       |
| numberSteps               | [valueObject](/terms-definition) | number of kinetics steps used in integrating kinetic rates, more steps lead to higher result accuracy and longer computation time |

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field**   |
| ---------------------------------------------- |
| "/params/kineticsParameters/holdupTime/value"  |
| "/params/kineticsParameters/numberSteps/value" |


# Kinetic calculation outputs

Kinetic calculation outputs are listed as an array of objects in **result.kineticOutputs**, for each kinetic reaction defined in the chemistry model.

```javascript
{
"result": {
    ...<snip>...
    "kineticOutputs": [
        {
            "reaction": "2NH3AQ+CO2AQ=UREAAQ+H2O",
            "AF": {
                "value": 0.0,
                "unit": ""
            },
            "BF": {
                "value": 0.0,
                "unit": ""
            },
            "AR": {
                "value": 1.2e-10,
                "unit": ""
            },
            "BR": {
                "value": 3480.78,
                "unit": ""
            },
            "ERPH": {
                "value": 0.0,
                "unit": ""
            },
            "EPPH": {
                "value": 0.0,
                "unit": ""
            },
            "ER0": {
                "value": 2.0,
                "unit": ""
            },
            "ER1": {
                "value": 1.0,
                "unit": ""
            },
            "EP0": {
                "value": 1.0,
                "unit": ""
            },
            "KFORWARD": {
                "value": 0.0,
                "unit": "mol/hr m3"
            },
            "KREVERSE": {
                "value": 0.0,
                "unit": "mol/hr m3"
            },
            "RATEFORWARD": {
                "value": 0.0,
                "unit": "mol/hr hr"
            },
            "RATEREVERSE": {
                "value": 0.0,
                "unit": "mol/hr hr"
            },
            "KFORWARDKRCF": {
                "value": 0.0,
                "unit": "mol/hr m3"
            },
            "KREVERSEKRCF": {
                "value": 0.0,
                "unit": "mol/hr m3"
            },
            "RATE": {
                "value": 0.00011907436930898546,
                "unit": "mol/hr hr"
            },
            "EXTENT": {
                "value": 0.0,
                "unit": "mol/hr"
            },
            "SUMEXTENTS": {
                "value": 0.0,
                "unit": "mol/hr"
            },
            "CONVERSION": {
                "value": 0.0,
                "unit": ""
            },
            "KEQ": {
                "value": 6.568856352382969,
                "unit": ""
            }
        },
        {
            "reaction": "NH3AQ+H2O=NH4ION+OHION",
            ...<snip>...
        }
    ]
    }
}
```

| result.kineticOutputs\[i]  | type                                         | description                                                       |
| -------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |
| reaction                   | string                                       | kinetic reaction expression                                       |
| AF, BF, AR, BR, ERPH, EPPH | [valueObject](/terms-definition#valueobject) | kinetic rate parameters for forward (F) and reverse (R) reactions |
| ER0, ER1...                | [valueObject](/terms-definition#valueobject) | exponent reaction order parameter of reactant 1, 2...             |
| EP0, EP1...                | [valueObject](/terms-definition#valueobject) | exponent reaction order parameter of product 1, 2...              |
| KFORWARD, KREVERSE         | [valueObject](/terms-definition#valueobject) | forward and reverse reaction K value                              |
| RATEFORWARD, RATEREVERSE   | [valueObject](/terms-definition#valueobject) | forward and reverse reaction rate                                 |
| KFORWARDKRCF, KREVERSEKRCF | [valueObject](/terms-definition#valueobject) |                                                                   |
| RATE                       | [valueObject](/terms-definition#valueobject) | reaction rate                                                     |
| EXTENT                     | [valueObject](/terms-definition#valueobject) | reaction extent                                                   |
| SUMEXTENTS                 | [valueObject](/terms-definition#valueobject) | sum of reaction extents                                           |
| CONVERSION                 | [valueObject](/terms-definition#valueobject) | reaction conversion                                               |
| KEQ                        | [valueObject](/terms-definition#valueobject) | calculated equilibrium constant                                   |


# Input units

This page describes the various units supported for the input values in the equilibrium calculations

| property                       | supported units                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| temperature                    | K, degree\_Fahrenheit, °C, °F, degree\_Celsius, R                                           |
| pressure                       | Pa, kPag, atm, psia, mbar, inH2O, barg, MPag, inHg, kg/cm2, psig, MPa, mmHg, bar, kPa, Torr |
| enthalpy                       | kJ, Btu, E3cal, E6cal, MMBtu, cal, J, MJ                                                    |
| <p></p><p>vaporAmountMoles</p> | mol, nmol, kgmol, nanomol, lbmol, micromol, µmol, mmol, (mol/100)                           |
| <p></p><p>vaporMolFrac</p>     | `mol/mol, mole %, ppm (mole)`                                                               |
| totalVolume                    | m3, MMft3, bbl, m3/100, cm3, gal, ft3, E6m3, MMgal, E3m3, L, ml, Mft3                       |
| pipeDiameter                   | dam, mi, mil, dm, µm, nm, micron, cm, km, in, Å, hm, yd, Angstrom, micrometer, ft, mm, m    |
| pipeFlowVelocity               | `m/s, km/hr, mi/hr, ft/s`                                                                   |
| diskDiameter                   | dam, mi, mil, dm, µm, nm, micron, cm, km, in, Å, hm, yd, Angstrom, micrometer, ft, mm, m    |
| diskRotatingSpeed              | `cycle/s, cycle/min`                                                                        |
| rotorDiameter                  | dam, mi, mil, dm, µm, nm, micron, cm, km, in, Å, hm, yd, Angstrom, micrometer, ft, mm, m    |
| rotorRotation                  | `cycle/s, cycle/min`                                                                        |
| shearStress                    | Pa, kPag, atm, psia, mbar, inH2O, barg, MPag, inHg, kg/cm2, psig, MPa, mmHg, bar, kPa, Torr |
| pipeDiameter                   | dam, mi, mil, dm, µm, nm, micron, cm, km, in, Å, hm, yd, Angstrom, micrometer, ft, mm, m    |
| <p></p><p>pipeRoughness</p>    | dam, mi, mil, dm, µm, nm, micron, cm, km, in, Å, hm, yd, Angstrom, micrometer, ft, mm, m    |
| liquidFlowInPipe               | `m3/s, m3/hr, L/s, L/hr, ft3/s, ft3/min, ft3/hr, gal/s, gal/min, gal/hr`                    |
| gasFlowInPipe                  | `m3/s, m3/hr, L/s, L/hr, ft3/s, ft3/min, ft3/hr, gal/s, gal/min, gal/hr`                    |
| <p></p><p>viscAbs2ndLiq</p>    | `cP, Poise, Pa-s`                                                                           |
| alkalinity                     | `mg HCO3/L, mg CO3/L, mol HCO3/L, mol CO3/L, eq/L, meq/L, mg CaCO3/L, mol CaCO3/L`          |
| TIC                            | `mol C/L, mg C/L, g C/L`                                                                    |
| CO2GasFraction                 | `mol/mol, mole %, ppm (mole)`                                                               |


# User defined output unit set

For all the flash computations, the user can optionally specify the unit of each output value in the [Stream output](/stream-output-json) in the **params.unitSetInfo** section. The table below describes the supported output units.

| params.unitSetInfo   | definition                        | default unit          | units available                                                                  |
| -------------------- | --------------------------------- | --------------------- | -------------------------------------------------------------------------------- |
| liq1\_phs\_comp      | liquid 1 phase composition        | mol                   | see composition units below                                                      |
| solid\_phs\_comp     | solid phase composition output    | mol                   | see composition units below                                                      |
| vapor\_phs\_comp     | vapor phase composition output    | mol                   | see composition units below                                                      |
| liq2\_phs\_comp      | liquid 2 phase composition output | mol                   | see composition units below                                                      |
| combined\_phs\_comp  | total composition output          | mol                   | see composition units below                                                      |
| density              | density of a phase/total stream   | g/L                   | g/ml, kg/m3, g/L, kg/L, lb/ft3, lb/gal                                           |
| mass                 | mass of a phase/total stream      | g                     | g, kg, lb, mg, (g/100), metric ton                                               |
| vol                  | volume of a phase/total stream    | L                     | L, ml, cm3, m3, E3m3, E6m3, ft3, Mft3, MMft3, gal, MMgal, bbl                    |
| moles                | total moles in a  phase/stream    | mol                   | mol, kgmol, lbmol, mmol, μmol, (mol/100)                                         |
| pt                   | pressure of stream                | atm                   | atm, bar, barg, mbar, Pa, kPa, MPa, mmHg, Torr, inHg, psia, psig, inH2O, kg/cm2  |
| t                    | temperature of stream             | °C                    | K, degree\_Fahrenheit, °C, °F, degree\_Celsius, R                                |
| enthalpy             | enthalpy of a phase/stream        | cal                   | cal, E3cal, E6cal, J, kJ, MJ, Btu, MMBtu                                         |
| visabs               | Absolute viscosity                | cP                    | cP, Poise, Pa-s                                                                  |
| i                    | Ionic strength, x-based           | mol/mol               | mol/mol                                                                          |
| im                   | Ionic strength, m-based           | mol/kg                | mol/kg                                                                           |
| econd                | Specific electric conductivity    | µmho/cm               | mho/m, mho/cm, µmho/m, µmho/cm                                                   |
| econdm               | Molar electric conductivity       | m2/ohm-mol            | m2/ohm-mol, cm2/ohm-mol                                                          |
| fug                  | Fugacity                          | atm                   | atm, bar, barg, mbar, Pa, kPa, MPa, mmHg, Torr, inHg, psia, psig, inH2O, kg/cm2  |
| mob                  | Mobilities                        | cm2/s-volt            | cm2/s-volt, m2/s-volt                                                            |
| dif                  | Self diffusivity                  | m2/s                  | m2/s                                                                             |
| alkalinity           | Alkalinity                        | mg HCO3/L             | eq/L, meq/L, mg HCO3/L, mg CO3/L, mol HCO3/L, mol CO3/L, mg CaCO3/L, mol CaCO3/L |
| tds                  | Total dissolved solids            | mg/L                  | mg/L                                                                             |
| cp                   | Heat capacity                     | cal/g K               | J/kg K, J/g K, cal/g K, Btu/lb R                                                 |
| entr                 | Entropy                           | cal/K                 | J/K, cal/K, Btu/R                                                                |
| thermalcond          | Thermal conductivity              | cal/hr m °C           | Btu/hr ft °F, cal/hr m °C, cal/s m °C, J/s m K                                   |
| surface\_tension     | Surface tension                   | N/m                   | N/m, dyne/cm                                                                     |
| mol\_entr            | Molar entropy                     | cal/mol K             | J/mol K, cal/mol K, Btu/mol R                                                    |
| interfacial\_tension | Interfacial tension               | N/m                   | N/m, dyne/cm                                                                     |
| kinetics\_k          | K value of kinetic reaction       | mol/hr m3             | mol/hr m3                                                                        |
| kinetics\_rate       | Kinetic reaction rate             | mol/hr hr             | mol/hr hr                                                                        |
| kinetics\_extent     | Kinetic reaction extent           | mol/hr                | mol/hr                                                                           |
| hardness             | Hardness                          | mg/L of Mg+2 and Ca+2 | mg/L of Mg+2 and Ca+2                                                            |
| tic                  | Total inorganic carbon            | mol C/L               | mg C/L, g C/L, mol C/L                                                           |
| energy               | Gibbs free energy                 | cal                   | cal, E3cal, E6cal, J, kJ, MJ, Btu, MMBtu                                         |
| mol\_energy          | Molar Gibbs free energy           | cal/mol               | cal/mol, E3cal/mol, E6cal/mol, J/mol, kJ/mol, MJ/mol, Btu/mol, MMBtu/mol         |
| part\_pressure       | Partial pressure                  | atm                   | atm, bar, barg, mbar, Pa, kPa, MPa, mmHg, Torr, inHg, psia, psig, inH2O, kg/cm2  |
| molefrac             | Mole fraction                     | mol/mol               | mol/mol, mole %, ppm (mole)                                                      |
| induction\_time      | scaling induction time            | hr                    | s, min, hr, day, yr                                                              |

{% hint style="success" %}
All unit entries do not have to be specified. The ones that are not will be overridden by the default.&#x20;
{% endhint %}

#### Composition units

| unit types    | units                                      |
| ------------- | ------------------------------------------ |
| moles         | `mol, kgmol, lbmol, mmol, µmol, (mol/100)` |
| mole fraction | `mol/mol, mole %, ppm (mole)`              |
| mass          | `g, kg, lb, mg, (g/100), metric ton`       |
| mass fraction | `g/g, mass %, ppm (mass)`                  |

{% hint style="info" %}
Composition units can be specified as any units above.
{% endhint %}

### JSON input (example)

Below is an input sample containing the **params.unitSetInfo** optional object using [isothermal flash](/group1/api-functions/isothermal) function input as an example.

```javascript
{
    "params": {
        ...<snip>...
        "unitSetInfo": {
            "liq1_phs_comp": "mol/mol",
            "solid_phs_comp": "mol/mol",
            "vapor_phs_comp": "mol/mol",
            "liq2_phs_comp": "mol/mol",
            "combined_phs_comp": "mol/mol",
            "density": "kg/m3",
            "mass": "g",
            "vol": "L",
            "moles": "mol",
            "pt": "atm",
            "t": "°C",
            "enthalpy": "J",
            "visabs": "cP",
            "i": "mol/mol",
            "im" "mol/kg",
            "econd": "µmho/cm",
            "econdm": "m2/ohm-mol",
            "fug": "atm",
            "mob": "m2/s-volt",
            "dif": "m2/s",
            "alkalinity": "mg HCO3/L",
            "tds": "mg/L",
            "current_den": "A/sq-m",
            "molefrac": "mole %",
            "cp": "cal/g K",
            "entr": "cal/K hr",
            "thermalcond": "cal/hr m °C",
            "surface_tension": "N/m",
            "part_pressure": "atm",
            "mol_entr": "cal/mol K",
            "interfacial_tension": "N/m",
            "kinetics_k": "mol/hr m3",
            "kinetics_rate": "mol/hr hr",
            "kinetics_extent": "mol",
            "hardness": "mg/L of Mg+2 and Ca+2",
            "tic": "mol C/L"
        }
}
```

Explanation of each property and available units will be documented later.


# Survey calculation

In comparison to single-point calculation, survey calculation allows users to perform a series of calculations by varying one or more input variables.

### JSON input (example)

Here two isothermal flash inputs are taken as examples to illustrate the survey calculation input.

{% tabs %}
{% tab title="one survey variable" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "params": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "NACL": 20.0
            }
        },
        "surveyInputs": [
            {
                "variableField": "/params/temperature/value",
                "values": [30.0, 35.0, 40.0, 45.0, 50.0]
            }
        ],
        "surveyOutputsByField": [
            {
                "field": "/solid/trueConcentration/values/NACL",
                "defaultValue": 0
            }
        ]
    }
}
</code></pre>

{% endtab %}

{% tab title="two survey variables" %}

```json
{
    "params": {
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 1.5,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mol",
            "values": {
                "H2O": 50.0,
                "NACL": 20.0
            }
        },
        "surveyInputs": [
            {
                "variableField": "/params/temperature/value",
                "values": [30.0, 30.0, 40.0, 40.0, 50.0, 50.0]
            },
            {
                "variableField": "/params/pressure/value",
                "values": [1.0, 1.5, 1.0, 1.5, 1.0, 1.5]
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

| params.surveyInputs[\[ { } \]](/terms-definition) | type             | description                                                                                          |
| ------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| variableField                                     | string           | [JSON pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the survey variable in input schema |
| values                                            | array of numbers | series of survey variable values for calculation                                                     |

The survey calculation runs the series of input JSON by overwriting the survey variable values.&#x20;

{% hint style="warning" %}
When an input variable is specified as a survey variable, e.g. "/params/temperature/value", the source input JSON field, **params.temperature.value**, is optional as it will be overwritten by the survey calculation inputs. However, **params.temperature.unit** is still required.
{% endhint %}

{% hint style="info" %}
When multiple survey variables are specified, the values in each **params.surveyInputs\[{}].values** array are updated simultaneously. When the arrays are specified in different sizes, the last value of the shorter array(s) will be used to run the survey calculation until the longest array is completed.
{% endhint %}

Specific stream output can be shown in an array for user's convinience.&#x20;

| params.surveyOutputsByField | type   | description                                                                                                              |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| field                       | string | [JSON pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the stream output of interest in the survey calculation |
| defaultValue                | number | optional, default value if specified field in stream output does not exist in specific point                             |

### Response (status = PROCESSED)

```json
{
    "code": 200,
    "result": {
        "surveyOutputs": [
            {
                "phases": {...<snip>...},
                "phaseSummary": [...<snip>...],
                "total": {...<snip>...}
            },
            {...<snip>...},
            {...<snip>...},
            {...<snip>...}
        ]
    },
    "surveyOutputsByField": [
    {
        "field": "/solid/trueConcentration/values/NACL",
        "results": [0.0, 1.35, 1.51, 1.7],
        "presence": [true, true, true, true]
    }],
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

**result.surveyOutputs** list an array of objects as the full [stream output ](/stream-output-json)of each survey calculation result. **result.surveyOutputsByField** lists the specific output in one array along the survey calculations.&#x20;

| result.surveyOutputsByField[\[{}\]](/terms-definition) | type             | description                                                                                                                                                                                                                        |
| ------------------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| field                                                  | string           | [JSON pointer](https://datatracker.ietf.org/doc/html/rfc6901) to the stream output of interest in the survey calculation, as specified in input                                                                                    |
| results                                                | array of numbers | specific values in the stream outputs along the survey calculations                                                                                                                                                                |
| presence                                               | array of boolean | presence of the specific output. False if the individual calculation inside the survey did not converge. Also false if the specific field does not exist in stream output, unless the "defaultValue" is provided in survey inputs. |


# Stream output

The stream output JSON describes the output all equilibrium flash calculations. this output contains the following objects.

| result       |                                                                      |
| ------------ | -------------------------------------------------------------------- |
| phases       | contains the output information for each phase                       |
| phaseSummary | contains information on whether a particular phase is present or not |
| total        | contains information of the total stream                             |

The sample below contains a condensed version of the stream output

```javascript
{
    "code": 200,
    "result": {
        "phases": {
            ...<snip>...
        },
        "phaseSummary": [
            ...<snip>...
        ],
        "total": {
            ...<snip>...
        }
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

### Phases in the system&#x20;

Contains objects pertaining to each phase available in the equilibrium output

| result.phases | type   | description                                           |
| ------------- | ------ | ----------------------------------------------------- |
| liquid1       | object | liquid1 phase information if phase is present         |
| vapor         | object | vapor phase information if vapor phase is present     |
| solid         | object | solid phase information if solid phase is present     |
| liquid2       | object | liquid2 phase information if liquid2 phase is present |

**result.total has the information about the full stream**

{% hint style="warning" %}
If a phase is not available the corresponding object will not be present.&#x20;
{% endhint %}

The sample below contains a condensed version of the phase information under the **result.phases** object

```javascript
{
    "result": {
        "phases": {
            "liquid1": {
                ..<snip>...
            },
            "vapor": {
                ...<snip>...
            },
            "solid": {
                ...<snip>...
            },
            "liquid2": {
                ...<snip>...
            }
        },
        "total": {
        ..<snip>...
        }
    }
}
```

### Speciation information&#x20;

Each phase object contains the following objects

| result.phases.phase\_name     | type                             | description                                                                         |
| ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
| totalMolecularMoles           | [valueObject](/terms-definition) | total molecular moles, also known as apparent moles in the phase                    |
| totalTrueMoles                | [valueObject](/terms-definition) | total true moles in the phase                                                       |
| molecularConcentration.values | object                           | contains the amount of each molecular species given as **"species\_name" : number** |
| molecularConcentration.unit   | string                           | unit for each species amount specified in **molecularConcentration.values**         |
| trueConcentration.values      | object                           | contains the amount of each true species given as **"species\_name" : number**      |
| trueConcentration.unit        | string                           | unit for each species amount specified in **trueConcentration.values**              |

{% hint style="info" %}
here **phase\_name** be either **liquid1, vapor, solid, vapor or total**
{% endhint %}

{% hint style="warning" %}
Here the names in the object **molecularConcentration.values** corresponds to the **inflows** names and the names in **trueConcentration.values** corresponds to the **species** names coming from the [chemistry information](/group1/api-functions/chemistry-info) function
{% endhint %}

{% hint style="info" %}
**molecularConcentration** is a representation of true species concentration in molecular/inflow form. Users can specify the molecular conversion method as explained in [Optional inputs](/optional-inputs#molecular-conversion).
{% endhint %}

Here the sample output for each phase is shown separately, but they are part of the same JSON output object in **result.phases**

{% tabs %}
{% tab title="liquid1" %}

```javascript
{
  "result": {
    "phases": {
      "liquid1": {
            "totalMolecularMoles": {
                "value": 21.226207616613667,
                "unit": "mol"
            },
            "molecularConcentration": {
                "unit": "mol/mol",
                "values": {
                    "H2O": 0.8980756720878806,
                    "CO2": 0.00012127280721685236,
                    "BENZENE": 0.00012121810265871872,
                    "HCL": 0.0,
                    "H2CO3": 0.0,
                    "NACL": 0.10168183416772372,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NA2CO3": 0.0,
                    "NA2O": 2.8345199111433006e-09,
                    "NA3HCO32": 0.0,
                    "NA5H3CO34": 0.0,
                    "NAHCO3": 0.0,
                    "NAOH.1H2O": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0
                }
            },
            "totalTrueMoles": {
                "value": 23.384516501904006,
                "unit": "mol"
            },
            "trueConcentration": {
                "unit": "mol/mol",
                "values": {
                    "H2O": 0.8151847728579172,
                    "CO2": 0.00010841376510336895,
                    "BENZENE": 0.00011003009678290568,
                    "HCL": 2.2808487226473268e-11,
                    "NAHCO3": 4.6343297486528063e-07,
                    "OHION": 1.3404451593976355e-12,
                    "CO3ION": 2.8319031932064318e-12,
                    "HCO3ION": 1.20254879862828e-06,
                    "HION": 1.6608253486241603e-06,
                    "NACO3ION": 2.5933560724207716e-12,
                    "NAION": 0.09229649908827389,
                    "CLION": 0.0922969573552263
                }
            },
            "properties": {
                "mass": {
                    "value": 469.8744595184318,
                    "unit": "g"
                },
                "enthalpy": {
                    "value": -6290492.86193959,
                    "unit": "J"
                },
                "ph": {
                    "value": 3.506293402644644,
                    "unit": ""
                },
                "ionicStrength": {
                    "value": 6.284844275084738,
                    "unit": ""
                },
                "volume": {
                    "value": 0.39889132965412266,
                    "unit": "L"
                },
                "osmoticPressure": {
                    "value": 417.3774507090581,
                    "unit": "atm"
                },
                "heatCapacity": {
                    "value": 0.6883875523093475,
                    "unit": "cal/g K"
                },
                "orp": {
                    "value": 0.0,
                    "unit": ""
                },
                "specificElectricalConductivity": {
                    "value": 0.3888779545938565,
                    "unit": "µmho/cm"
                },
                "molarElectricalConductivity": {
                    "value": 5.170668146037298,
                    "unit": "m2/ohm-mol"
                },
                "absoluteViscosity": {
                    "value": 1.1196506783843205,
                    "unit": "cP"
                },
                "relativeViscosity": {
                    "value": 2.046080906239711,
                    "unit": "cP"
                },
                "thermalConductivity": {
                    "value": 0.0,
                    "unit": "cal/hr m °C"
                },
                "idealStandardLiquidVolume": {
                    "value": 0.421019399748327,
                    "unit": "L"
                },
                "surfaceTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "interfacialTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "density": {
                    "value": 1177.9510472836255,
                    "unit": "kg/m3"
                },
                "hardness": {
                    "value": 0.0,
                    "unit": "mg/L of Mg+2 and Ca+2"
                },
                "ionicStrengthMBased": {
                    "value": 6.284844275084737,
                    "unit": "mol/kg"
                },
                "ionicStrengthXBased": {
                    "value": 0.09229815991645443,
                    "unit": "mol/mol"
                },
                "volumeStdConditions": {
                    "value": 0.3899494321783508,
                    "unit": "L"
                },
                "gibbsFreeEnergy": {
                    "value": -5405064.876853572,
                    "unit": "J"
                },
                "gibbsFreeEnergyStandardState": {
                    "value": -5364732.614802347,
                    "unit": "J"
                },
                "entropy": {
                    "value": 402.52249696366414,
                    "unit": "cal/K"
                },
                "entropyStandardState": {
                    "value": 368.1849240704805,
                    "unit": "cal/K"
                },
                "totalDissolvedSolids": {
                    "value": 316732.9367611623,
                    "unit": "mg/L"
                }
            },
            "mobilities": {
                "unit": "m2/s-volt",
                "values": {
                    "OHION": 1.0477530322319145e-07,
                    "CO3ION": 4.5521284815508306e-08,
                    "HCO3ION": 2.6682810347057602e-08,
                    "HION": 1.7471316433726358e-07,
                    "NACO3ION": 2.02107319598793e-08,
                    "NAION": 3.01959373362478e-08,
                    "CLION": 4.429241371474645e-08
                }
            },
            "selfDiffusivities": {
                "unit": "m2/s",
                "values": {
                    "H2O": 2.024176002497278e-09,
                    "CO2": 1.7484002869485418e-09,
                    "BENZENE": 9.881226550801429e-10,
                    "HCL": 1.6907916668742283e-09,
                    "NAHCO3": 8.584040486862172e-10,
                    "OHION": 3.6343124558205254e-09,
                    "CO3ION": 8.341437678389614e-10,
                    "HCO3ION": 9.836603781305234e-10,
                    "HION": 5.981318546296803e-09,
                    "NACO3ION": 7.383722894675519e-10,
                    "NAION": 1.1831936448580512e-09,
                    "CLION": 1.5679953664262656e-09
                }
            },
            "gibbsFreeEnergy": {
                "unit": "J/mol",
                "values": {
                    "H2O": -239764.1869055229,
                    "CO2": -399634.43639125564,
                    "BENZENE": 119944.96048947786,
                    "HCL": -149450.0860740784,
                    "NAHCO3": -876259.3345219601,
                    "OHION": -218072.07804470454,
                    "CO3ION": -596014.4046546705,
                    "HCO3ION": -617706.5138436517,
                    "HION": -21692.109995603936,
                    "NACO3ION": -854567.2252991025,
                    "NAION": -258552.8207846849,
                    "CLION": -127757.97582073502
                }
            },
            "gibbsFreeEnergyStandardStateXBased": {
                "unit": "J/mol",
                "values": {
                    "H2O": -239003.903975896,
                    "CO2": -378355.0490189462,
                    "BENZENE": 140604.9934336966,
                    "HCL": -87442.33585885077,
                    "NAHCO3": -840902.8450806803,
                    "OHION": -146112.94590453355,
                    "CO3ION": -515667.7416043327,
                    "HCO3ION": -578579.3952622324,
                    "HION": 10791.668865256031,
                    "NACO3ION": -781074.0069076401,
                    "NAION": -252592.58366227054,
                    "CLION": -121797.16716088422
                }
            },
            "activityCoefficientsXBased": {
                "unit": "",
                "values": {
                    "H2O": 0.9243838734161381,
                    "CO2": 3.3522070912701194,
                    "BENZENE": 4.159257161627117,
                    "HCL": 4.15925716162711,
                    "NAHCO3": 4.159257161627117,
                    "OHION": 1.7431270864188753,
                    "CO3ION": 0.03637016652648902,
                    "HCO3ION": 0.39392925849523136,
                    "HION": 3.3808164585153477,
                    "NACO3ION": 0.5090346708059645,
                    "NAION": 1.178708373817101,
                    "CLION": 1.1784518150479442
                }
            },
            "activityCoefficientsMBased": {
                "unit": "",
                "values": {
                    "H2O": 0.7535436578842564,
                    "CO2": 2.732668176269732,
                    "BENZENE": 3.3905631045586677,
                    "HCL": 3.390563104558662,
                    "NAHCO3": 3.3905631045586677,
                    "OHION": 1.420970658004854,
                    "CO3ION": 0.029648405938700582,
                    "HCO3ION": 0.321125133108523,
                    "HION": 2.755990096809142,
                    "NACO3ION": 0.41495731249776496,
                    "NAION": 0.9608651179758185,
                    "CLION": 0.9606559751738588
                }
            },
            "totalMBGMoles": {
                "value": 61.515157125730966,
                "unit": "mol"
            },
            "MBGComposition": {
                "unit": "mol/mol",
                "values": {
                    "H(+1)": 0.6197737781017071,
                    "Na(+1)": 0.03508598439898328,
                    "O(-2)": 0.30997058198077737,
                    "Cl(-1)": 0.03508598244284398,
                    "C(+4)": 4.1845975927089606e-05,
                    "BENZENE": 4.182709976123431e-05
                }
            },
            "entropy": {
                "unit": "cal/mol K",
                "values": {
                    "H2O": 18.61927150093834,
                    "CO2": 44.55439177545486,
                    "BENZENE": 49.68223713294719,
                    "HCL": 35.46867179684341,
                    "NAHCO3": 49.506592529360205,
                    "OHION": -7.835324275947642,
                    "CO3ION": 10.391179658472538,
                    "HCO3ION": 36.778099756338634,
                    "HION": 26.31175650485602,
                    "NACO3ION": 23.14335792325437,
                    "NAION": 12.68337354194955,
                    "CLION": 9.25296564346354
                }
            },
            "entropyStandardStateXBased": {
                "unit": "cal/mol K",
                "values": {
                    "H2O": 18.1511282477004,
                    "CO2": 24.39883616170846,
                    "BENZENE": 34.40187079613679,
                    "HCL": 15.857367282296764,
                    "NAHCO3": 10.922679142095149,
                    "OHION": -12.820184685551794,
                    "CO3ION": -24.954215268371627,
                    "HCO3ION": 14.992231663200073,
                    "HION": -7.981652580747323,
                    "NACO3ION": -19.06021603208501,
                    "NAION": 6.820429471554235,
                    "CLION": 3.384198818457662
                }
            }
        }
    }
  }
}
```

{% endtab %}

{% tab title="vapor" %}

```javascript
{
  "result": {
    "phases": {
        "vapor": {
            "totalMolecularMoles": {
                "value": 14.202172424670817,
                "unit": "mol"
            },
            "molecularConcentration": {
                "unit": "mol/mol",
                "values": {
                    "H2O": 0.06221167877156798,
                    "CO2": 0.696612589194416,
                    "BENZENE": 0.24117572375204308,
                    "HCL": 8.282042013416935e-09,
                    "H2CO3": 0.0,
                    "NACL": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NA2CO3": 0.0,
                    "NA2O": 0.0,
                    "NA3HCO32": 0.0,
                    "NA5H3CO34": 0.0,
                    "NAHCO3": 0.0,
                    "NAOH.1H2O": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0
                }
            },
            "totalTrueMoles": {
                "value": 14.202172424670817,
                "unit": "mol"
            },
            "trueConcentration": {
                "unit": "mol/mol",
                "values": {
                    "H2O": 0.06221167877156798,
                    "CO2": 0.696612589194416,
                    "BENZENE": 0.24117572375204308,
                    "HCL": 8.282042013416935e-09
                }
            },
            "properties": {
                "mass": {
                    "value": 718.884475325838,
                    "unit": "g"
                },
                "enthalpy": {
                    "value": -3806884.6435459694,
                    "unit": "J"
                },
                "ph": {
                    "value": 0.0,
                    "unit": ""
                },
                "ionicStrength": {
                    "value": 0.0,
                    "unit": ""
                },
                "volume": {
                    "value": 247.86468511163403,
                    "unit": "L"
                },
                "osmoticPressure": {
                    "value": 0.0,
                    "unit": "atm"
                },
                "heatCapacity": {
                    "value": 0.2415152457027691,
                    "unit": "cal/g K"
                },
                "orp": {
                    "value": 0.0,
                    "unit": ""
                },
                "specificElectricalConductivity": {
                    "value": 0.0,
                    "unit": "µmho/cm"
                },
                "molarElectricalConductivity": {
                    "value": 0.0,
                    "unit": "m2/ohm-mol"
                },
                "absoluteViscosity": {
                    "value": 0.012366440652502366,
                    "unit": "cP"
                },
                "relativeViscosity": {
                    "value": 0.0,
                    "unit": "cP"
                },
                "thermalConductivity": {
                    "value": 14.575964340152733,
                    "unit": "cal/hr m °C"
                },
                "idealStandardLiquidVolume": {
                    "value": 0.6912330153403138,
                    "unit": "L"
                },
                "surfaceTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "interfacialTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "density": {
                    "value": 2.900310203537324,
                    "unit": "kg/m3"
                },
                "volumeStdConditions": {
                    "value": 224.32703036551902,
                    "unit": "L"
                },
                "gibbsFreeEnergy": {
                    "value": -3754751.8887388613,
                    "unit": "J"
                },
                "gibbsFreeEnergyStandardState": {
                    "value": -3740447.147339126,
                    "unit": "J"
                },
                "entropy": {
                    "value": 788.6168219465585,
                    "unit": "cal/K"
                },
                "entropyStandardState": {
                    "value": 779.1222828112316,
                    "unit": "cal/K"
                }
            },
            "selfDiffusivities": {
                "unit": "m2/s",
                "values": {
                    "H2O": 1.4242539419660113e-05,
                    "CO2": 9.701040488087044e-06,
                    "BENZENE": 3.2321821400380015e-06,
                    "HCL": 9.20876405486835e-06
                }
            },
            "vaporDiffusivityMatrix": {
                "type": "rowMajorMatrix",
                "speciesNames": [
                    "H2O",
                    "CO2",
                    "BENZENE",
                    "HCL"
                ],
                "unit": "m2/s",
                "data": [
                    1.4242539419660113e-05,
                    1.5947634582597602e-05,
                    9.090354141730192e-06,
                    1.73118735518477e-05,
                    1.5947634582597602e-05,
                    9.701040488087044e-06,
                    5.485155932862653e-06,
                    1.068311110428046e-05,
                    9.090354141730192e-06,
                    5.485155932862653e-06,
                    3.2321821400380015e-06,
                    6.060952736145546e-06,
                    1.73118735518477e-05,
                    1.068311110428046e-05,
                    6.060952736145546e-06,
                    9.20876405486835e-06
                ]
            },
            "partialPressure": {
                "unit": "atm",
                "values": {
                    "H2O": 0.09331751815735198,
                    "CO2": 1.0449188837916241,
                    "BENZENE": 0.3617635856280646,
                    "HCL": 1.2423063020125402e-08,
                    "H2CO3": 0.0,
                    "NACL": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NA2CO3": 0.0,
                    "NA2O": 0.0,
                    "NA3HCO32": 0.0,
                    "NA5H3CO34": 0.0,
                    "NAHCO3": 0.0,
                    "NAOH.1H2O": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0
                }
            },
            "gibbsFreeEnergy": {
                "unit": "J/mol",
                "values": {
                    "H2O": -239764.18696742016,
                    "CO2": -399634.43615714944,
                    "BENZENE": 119944.96068468186,
                    "HCL": -149450.08593080845
                }
            },
            "gibbsFreeEnergyStandardStateXBased": {
                "unit": "J/mol",
                "values": {
                    "H2O": -233351.90735992635,
                    "CO2": -399741.5987011286,
                    "BENZENE": 122776.72892666652,
                    "HCL": -100524.45747929343
                }
            },
            "fugacityCoefficients": {
                "unit": "",
                "values": {
                    "H2O": 0.9852821111175118,
                    "CO2": 0.9959535822374131,
                    "BENZENE": 0.9634966009085911,
                    "HCL": 0.9941873536173533
                }
            },
            "fugacities": {
                "unit": "atm",
                "values": {
                    "H2O": 0.09194408129432251,
                    "CO2": 1.0406907054597871,
                    "BENZENE": 0.34855798508514435,
                    "HCL": 1.2350852147800078e-08
                }
            },
            "totalMBGMoles": {
                "value": 35.75607872964982,
                "unit": "mol"
            },
            "MBGComposition": {
                "unit": "mol/mol",
                "values": {
                    "H(+1)": 0.049420466614023974,
                    "Na(+1)": 0.0,
                    "O(-2)": 0.5780937377082296,
                    "Cl(-1)": 3.289594185991633e-09,
                    "C(+4)": 0.2766917530230073,
                    "BENZENE": 0.09579403936514483
                }
            },
            "entropy": {
                "unit": "cal/mol K",
                "values": {
                    "H2O": 50.40657775680302,
                    "CO2": 51.6920253779972,
                    "BENZENE": 67.92850641031691,
                    "HCL": 80.77220734485309
                }
            },
            "entropyStandardStateXBased": {
                "unit": "cal/mol K",
                "values": {
                    "H2O": 45.742734461964574,
                    "CO2": 51.80255121376831,
                    "BENZENE": 66.04035986965755,
                    "HCL": 44.62224480594159
                }
            }
        }
    }
  }
}
```

{% endtab %}

{% tab title="liquid2" %}

```javascript
{
  "result": {
    "phases": {
        "liquid2": {
            "totalMolecularMoles": {
                "value": 11.729939801929907,
                "unit": "mol"
            },
            "molecularConcentration": {
                "unit": "mol/mol",
                "values": {
                    "H2O": 0.004579587008357855,
                    "CO2": 0.008867371447473326,
                    "BENZENE": 0.986553041313207,
                    "HCL": 2.3096692703897768e-10,
                    "H2CO3": 0.0,
                    "NACL": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NA2CO3": 0.0,
                    "NA2O": 0.0,
                    "NA3HCO32": 0.0,
                    "NA5H3CO34": 0.0,
                    "NAHCO3": 0.0,
                    "NAOH.1H2O": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0
                }
            },
            "totalTrueMoles": {
                "value": 11.729939801929907,
                "unit": "mol"
            },
            "trueConcentration": {
                "unit": "mol/mol",
                "values": {
                    "H2O": 0.004579587008357855,
                    "CO2": 0.008867371447473326,
                    "BENZENE": 0.986553041313207,
                    "HCL": 2.3096692703897768e-10,
                    "NAHCO3": 0.0,
                    "OHION": 0.0,
                    "CO3ION": 0.0,
                    "HCO3ION": 0.0,
                    "HION": 0.0,
                    "NACO3ION": 0.0,
                    "NAION": 0.0,
                    "CLION": 0.0
                }
            },
            "properties": {
                "mass": {
                    "value": 909.5016870031311,
                    "unit": "g"
                },
                "enthalpy": {
                    "value": 553663.5010248525,
                    "unit": "J"
                },
                "ph": {
                    "value": 0.0,
                    "unit": ""
                },
                "ionicStrength": {
                    "value": 0.0,
                    "unit": ""
                },
                "volume": {
                    "value": 1.073309739643026,
                    "unit": "L"
                },
                "osmoticPressure": {
                    "value": 0.0,
                    "unit": "atm"
                },
                "heatCapacity": {
                    "value": 0.4050817317973504,
                    "unit": "cal/g K"
                },
                "orp": {
                    "value": 0.0,
                    "unit": ""
                },
                "specificElectricalConductivity": {
                    "value": 0.0,
                    "unit": "µmho/cm"
                },
                "molarElectricalConductivity": {
                    "value": 0.0,
                    "unit": "m2/ohm-mol"
                },
                "absoluteViscosity": {
                    "value": 0.0,
                    "unit": "cP"
                },
                "relativeViscosity": {
                    "value": 0.0,
                    "unit": "cP"
                },
                "thermalConductivity": {
                    "value": 0.0,
                    "unit": "cal/hr m °C"
                },
                "idealStandardLiquidVolume": {
                    "value": 1.0403738849073891,
                    "unit": "L"
                },
                "surfaceTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "interfacialTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "density": {
                    "value": 847.3804470512155,
                    "unit": "kg/m3"
                },
                "ionicStrengthMBased": {
                    "value": 0.0,
                    "unit": "mol/kg"
                },
                "ionicStrengthXBased": {
                    "value": 0.0,
                    "unit": "mol/mol"
                },
                "volumeStdConditions": {
                    "value": 1.0308257906614442,
                    "unit": "L"
                },
                "gibbsFreeEnergy": {
                    "value": 1333580.818159867,
                    "unit": "J"
                },
                "gibbsFreeEnergyStandardState": {
                    "value": 1366683.9390451827,
                    "unit": "J"
                },
                "entropy": {
                    "value": 517.8792962261166,
                    "unit": "cal/K"
                },
                "entropyStandardState": {
                    "value": 772.0781645553415,
                    "unit": "cal/K"
                }
            },
            "gibbsFreeEnergy": {
                "unit": "J/mol",
                "values": {
                    "H2O": -239764.1869673227,
                    "CO2": -399634.4361571407,
                    "BENZENE": 119944.9606846787,
                    "HCL": -149450.08593080062,
                    "NAHCO3": 0.0,
                    "OHION": 0.0,
                    "CO3ION": 0.0,
                    "HCO3ION": 0.0,
                    "HION": 0.0,
                    "NACO3ION": 0.0,
                    "NAION": 0.0,
                    "CLION": 0.0
                }
            },
            "gibbsFreeEnergyStandardStateXBased": {
                "unit": "J/mol",
                "values": {
                    "H2O": -233351.90735992635,
                    "CO2": -399741.5987011286,
                    "BENZENE": 122776.72892666652,
                    "HCL": -100524.45747929343,
                    "NAHCO3": 0.0,
                    "OHION": 0.0,
                    "CO3ION": 0.0,
                    "HCO3ION": 0.0,
                    "HION": 0.0,
                    "NACO3ION": 0.0,
                    "NAION": 0.0,
                    "CLION": 0.0
                }
            },
            "activityCoefficientsXBased": {
                "unit": "",
                "values": {
                    "H2O": 164.5440203497236,
                    "CO2": 0.04098456846403843,
                    "BENZENE": 0.00046388126020171296,
                    "HCL": 0.41073570603173115,
                    "NAHCO3": 0.0,
                    "OHION": 0.0,
                    "CO3ION": 0.0,
                    "HCO3ION": 0.0,
                    "HION": 0.0,
                    "NACO3ION": 0.0,
                    "NAION": 0.0,
                    "CLION": 0.0
                }
            },
            "fugacityCoefficients": {
                "unit": "",
                "values": {
                    "H2O": 13.38462487699624,
                    "CO2": 78.24120233959098,
                    "BENZENE": 0.23553927698318566,
                    "HCL": 35.64969901729978,
                    "NAHCO3": 0.0,
                    "OHION": 0.0,
                    "CO3ION": 0.0,
                    "HCO3ION": 0.0,
                    "HION": 0.0,
                    "NACO3ION": 0.0,
                    "NAION": 0.0,
                    "CLION": 0.0
                }
            },
            "totalMBGMoles": {
                "value": 12.0454038310511,
                "unit": "mol"
            },
            "MBGComposition": {
                "unit": "mol/mol",
                "values": {
                    "H(+1)": 0.008919299349993557,
                    "Na(+1)": 0.0,
                    "O(-2)": 0.021729927045818765,
                    "Cl(-1)": 2.249180009573439e-10,
                    "C(+4)": 0.008635138741640494,
                    "BENZENE": 0.9607156346376292
                }
            },
            "entropy": {
                "unit": "cal/mol K",
                "values": {
                    "H2O": 38.47298225737177,
                    "CO2": 44.45974865084281,
                    "BENZENE": 44.173780718119815,
                    "HCL": 71.54322687638341,
                    "NAHCO3": 0.0,
                    "OHION": 0.0,
                    "CO3ION": 0.0,
                    "HCO3ION": 0.0,
                    "HION": 0.0,
                    "NACO3ION": 0.0,
                    "NAION": 0.0,
                    "CLION": 0.0
                }
            },
            "entropyStandardStateXBased": {
                "unit": "cal/mol K",
                "values": {
                    "H2O": 45.742734461964574,
                    "CO2": 51.80255121376831,
                    "BENZENE": 66.04035986965755,
                    "HCL": 44.62224480594159,
                    "NAHCO3": 0.0,
                    "OHION": 0.0,
                    "CO3ION": 0.0,
                    "HCO3ION": 0.0,
                    "HION": 0.0,
                    "NACO3ION": 0.0,
                    "NAION": 0.0,
                    "CLION": 0.0
                }
            }
        }
    }
  }
}
```

{% endtab %}

{% tab title="solid" %}

```javascript
{
  "result": {
    "phases": {
        "solid": {
            "totalMolecularMoles": {
                "value": 2.841680156785605,
                "unit": "mol"
            },
            "molecularConcentration": {
                "unit": "mol/mol",
                "values": {
                    "H2O": 0.0,
                    "CO2": 0.0,
                    "BENZENE": 0.0,
                    "HCL": 0.0,
                    "H2CO3": 0.0,
                    "NACL": 1.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NA2CO3": 0.0,
                    "NA2O": 0.0,
                    "NA3HCO32": 0.0,
                    "NA5H3CO34": 0.0,
                    "NAHCO3": 0.0,
                    "NAOH.1H2O": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0
                }
            },
            "totalTrueMoles": {
                "value": 2.841680156785605,
                "unit": "mol"
            },
            "trueConcentration": {
                "unit": "mol/mol",
                "values": {
                    "NA2CO3": 0.0,
                    "NACL": 1.0,
                    "NAHCO3": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NAOH.1H2O": 0.0
                }
            },
            "properties": {
                "mass": {
                    "value": 166.07622815261644,
                    "unit": "g"
                },
                "enthalpy": {
                    "value": -1165070.5694128608,
                    "unit": "J"
                },
                "ph": {
                    "value": 0.0,
                    "unit": ""
                },
                "ionicStrength": {
                    "value": 0.0,
                    "unit": ""
                },
                "volume": {
                    "value": 0.0767537810347792,
                    "unit": "L"
                },
                "osmoticPressure": {
                    "value": 1.0,
                    "unit": "atm"
                },
                "heatCapacity": {
                    "value": 0.20782954293889175,
                    "unit": "cal/g K"
                },
                "orp": {
                    "value": 0.0,
                    "unit": ""
                },
                "specificElectricalConductivity": {
                    "value": 0.0,
                    "unit": "µmho/cm"
                },
                "molarElectricalConductivity": {
                    "value": 0.0,
                    "unit": "m2/ohm-mol"
                },
                "absoluteViscosity": {
                    "value": 0.0,
                    "unit": "cP"
                },
                "relativeViscosity": {
                    "value": 0.0,
                    "unit": "cP"
                },
                "thermalConductivity": {
                    "value": 0.0,
                    "unit": "cal/hr m °C"
                },
                "idealStandardLiquidVolume": {
                    "value": 0.10041020000398801,
                    "unit": "L"
                },
                "surfaceTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "interfacialTension": {
                    "value": 0.0,
                    "unit": "N/m"
                },
                "density": {
                    "value": 2163.7530544242873,
                    "unit": "kg/m3"
                },
                "gibbsFreeEnergy": {
                    "value": -1097771.7246946518,
                    "unit": "J"
                },
                "gibbsFreeEnergyStandardState": {
                    "value": -1097771.7246946518,
                    "unit": "J"
                },
                "entropy": {
                    "value": 56.398948738818866,
                    "unit": "cal/K"
                },
                "entropyStandardState": {
                    "value": 56.398948738818866,
                    "unit": "cal/K"
                }
            },
            "gibbsFreeEnergy": {
                "unit": "J/mol",
                "values": {
                    "NA2CO3": 0.0,
                    "NACL": -386310.7964748599,
                    "NAHCO3": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NAOH.1H2O": 0.0
                }
            },
            "gibbsFreeEnergyStandardStateXBased": {
                "unit": "J/mol",
                "values": {
                    "NA2CO3": 0.0,
                    "NACL": -386310.7964748599,
                    "NAHCO3": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NAOH.1H2O": 0.0
                }
            },
            "totalMBGMoles": {
                "value": 5.68336031357121,
                "unit": "mol"
            },
            "MBGComposition": {
                "unit": "mol/mol",
                "values": {
                    "H(+1)": 0.0,
                    "Na(+1)": 0.5,
                    "O(-2)": 0.0,
                    "Cl(-1)": 0.5,
                    "C(+4)": 0.0,
                    "BENZENE": 0.0
                }
            },
            "entropy": {
                "unit": "cal/mol K",
                "values": {
                    "NA2CO3": 0.0,
                    "NACL": 19.84704316710122,
                    "NAHCO3": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NAOH.1H2O": 0.0
                }
            },
            "entropyStandardStateXBased": {
                "unit": "cal/mol K",
                "values": {
                    "NA2CO3": 0.0,
                    "NACL": 19.84704316710122,
                    "NAHCO3": 0.0,
                    "NAOH": 0.0,
                    "TRONA": 0.0,
                    "WEGSCHEIDER": 0.0,
                    "NA2CO3.10H2O": 0.0,
                    "NA2CO3.1H2O": 0.0,
                    "NA2CO3.7H2O": 0.0,
                    "NAOH.1H2O": 0.0
                }
            }
        }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Phase properties

The following properties are available under the properties object of each phase. Sample output is available in example(s) above

| result.phases.phase\_name.properties | availability                  | phase(s)                              |
| ------------------------------------ | ----------------------------- | ------------------------------------- |
| mass                                 | always                        | all                                   |
| enthalpy                             | always                        | all                                   |
| ph                                   | always                        | liquid1, liquid2                      |
| ionicStrength                        | always                        | liquid1, liquid2                      |
| volume                               | always                        | all                                   |
| osmoticPressure                      | always                        | liquid1, liquid2                      |
| heatCapacity                         | [optional](/optional-inputs)  | all                                   |
| orp                                  | always                        | <p>liquid1, </p><p>liquid2</p>        |
| specificElectricalConductivity       | [optional ](/optional-inputs) | <p>liquid1,</p><p>liquid2</p>         |
| molarElectricalConductivity          | [optional](/optional-inputs)  | <p>liquid1, </p><p>liquid2</p>        |
| absoluteViscosity                    | [optional ](/optional-inputs) | <p>liquid1, </p><p>liquid2, vapor</p> |
| relativeViscosity                    | [optional](/optional-inputs)  | liquid1, liquid2,  vapor              |
| thermalConductivity                  | [optional](/optional-inputs)  | liquid1, liquid2, vapor               |
| idealStandardLiquidVolume            | always                        | liquid1, liquid2                      |
| surfaceTension                       | [optional](/optional-inputs)  | liquid1, liquid2                      |
| interfacialTension                   | [optional](/optional-inputs)  | liquid1, liquid2                      |
| density                              | always                        | all                                   |
| hardness                             | [optional](/optional-inputs)  | liquid1                               |
| ionicStrengthXBased                  | [optional](/optional-inputs)  | liquid1, liquid2                      |
| ionicStrengthMBased                  | [optional](/optional-inputs)  | liquid1, liquid2                      |
| volumeStdConditions                  | [optional](/optional-inputs)  | liquid1, liquid2, vapor               |
| gibbsFreeEnergy                      | [optional](/optional-inputs)  | all                                   |
| gibbsFreeEnergyStandardState         | [optional](/optional-inputs)  | all                                   |
| entropy                              | [optional](/optional-inputs)  | all                                   |

#### Additional species properties

Additional species properties present in each result.phase.phase\_name when such property calculation is [turned on from input](/optional-inputs)

| result.phases.phase\_name          | phases(s)               |
| ---------------------------------- | ----------------------- |
| mobilities                         | liquid1                 |
| selfDiffusivities                  | liquid1, liquid2, vapor |
| gibbsFreeEnergy                    | all                     |
| gibbsFreeEnergyStandardStateXBased | all                     |
| activityCoefficientsXBased         | liquid1, liquid2        |
| activityCoefficientsMBased         | liquid1, liquid2        |
| totalMBGMoles                      | all                     |
| MBGComposition                     | all                     |
| entropy                            | all                     |
| entropyStandardStateXBased         | all                     |
| vaporDiffusivityMatrix             | vapor                   |
| partialPressure                    | vapor                   |
| fugacityCoefficients               | liquid2, vapor          |
| fugacities                         | vapor                   |

### Additional properties

Optional properties present in **result.additionalProperties** when they do not belong to any particular phase

```javascript
{
    "result": {
        "additionalProperites": {
            "prescalingTendencies": {
                "unit": "",
                "values": {
                    "NA2CO3": 3.0823983392482883e-10,
                    "NACL": 7.04645888444708,
                    "NAHCO3": 0.00046319422279570457,
                    "NAOH": 5.727646460859379e-16,
                    "TRONA": 5.433452081252768e-13,
                    "WEGSCHEIDER": 1.2439714622633147e-19,
                    "NA2CO3.10H2O": 2.42323772574986e-13,
                    "NA2CO3.1H2O": 4.724326060804564e-10,
                    "NA2CO3.7H2O": 5.622390596860186e-12,
                    "NAOH.1H2O": 1.6334354600819453e-14
                }
            },
            "prescalingIndex": {
                "unit": "",
                "values": {
                    "NA2CO3": -9.511111237986588,
                    "NACL": 0.8479709221966109,
                    "NAHCO3": -3.3342368659982218,
                    "NAOH": -15.24202379671215,
                    "TRONA": -12.264924158720135,
                    "WEGSCHEIDER": -18.905189582606397,
                    "NA2CO3.10H2O": -12.615603978385396,
                    "NA2CO3.1H2O": -9.325660136138662,
                    "NA2CO3.7H2O": -11.250078986517886,
                    "NAOH.1H2O": -13.78689802059106
                }
            },
            "scalingIndex": {
                "unit": "",
                "values": {
                    "NA2CO3": -9.946251018459519,
                    "NACL": -1.9554246636221152e-11,
                    "NAHCO3": -3.4886794715296867,
                    "NAOH": -15.386294219715131,
                    "TRONA": -12.581673108800006,
                    "WEGSCHEIDER": -19.80365717967372,
                    "NA2CO3.10H2O": -11.686576579235705,
                    "NA2CO3.1H2O": -9.624383198649332,
                    "NA2CO3.7H2O": -10.730301741254978,
                    "NAOH.1H2O": -13.79476196292895
                }
            },
            "scalingTendencies": {
                "unit": "",
                "values": {
                    "NA2CO3": 1.1317460347225315e-10,
                    "NACL": 0.9999999999549747,
                    "NAHCO3": 0.0003245790826401726,
                    "NAOH": 4.10871275505647e-16,
                    "TRONA": 2.6201544428167713e-13,
                    "WEGSCHEIDER": 1.571602895671782e-20,
                    "NA2CO3.10H2O": 2.057895989322877e-12,
                    "NA2CO3.1H2O": 2.3747440125028744e-10,
                    "NA2CO3.7H2O": 1.8607938359436187e-11,
                    "NAOH.1H2O": 1.6041243713317784e-14
                }
            },
            "vaporToInflowMoleFraction": {
                "value": 28.404344849341634,
                "unit": "mole %"
            },
            "kValuesXBased": {
                "unit": "",
                "values": {
                    "KH2OVAP": 8.195673362128641,
                    "KCO2VAP": 0.00034921556450656036,
                    "KBENZENEVAP": 0.0013129622262103029,
                    "KHCLVAP": 0.007680956966516748,
                    "KCO2AQ": 9.712763616665181e-09,
                    "KHCLAQ": 6437.726437542827,
                    "KH2O": 1.7410660292199987e-17,
                    "KHCO3ION": 1.2208106353427793e-12,
                    "KNA2CO3.10H2O": 3.496774736505818e-05,
                    "KNA2CO3.1H2O": 3.868107224026778e-06,
                    "KNA2CO3.7H2O": 9.037900604837083e-06,
                    "KNA2CO3PPT": 1.0771046605242481e-05,
                    "KNACLPPT": 0.011832889555603935,
                    "KNACO3ION": 0.008488007914963163,
                    "KNAHCO3AQ": 0.02673682534381605,
                    "KNAHCO3PPT": 0.0001587786173616354,
                    "KNAOH.1H2O": 11.940983026389624,
                    "KNAOHPPT": 618.6769257173816,
                    "KTRONAPPT": 1.3614740802529445e-10,
                    "KWEGSCHEIDERPPT": 1.0616997108576684e-17
                }
            },
            "kValuesMBased": {
                "unit": "",
                "values": {
                    "KH2OVAP": 8.195673362128641,
                    "KCO2VAP": 0.01938434492530035,
                    "KBENZENEVAP": 0.07288023574411047,
                    "KHCLVAP": 0.4263564810054514,
                    "KCO2AQ": 5.391385128820872e-07,
                    "KHCLAQ": 357346.9297577968,
                    "KH2O": 5.3645131731839625e-14,
                    "KHCO3ION": 6.776506218271648e-11,
                    "KNA2CO3.10H2O": 5.980538177919528,
                    "KNA2CO3.1H2O": 0.6615628592848587,
                    "KNA2CO3.7H2O": 1.5457532637484566,
                    "KNA2CO3PPT": 1.842173439607153,
                    "KNACLPPT": 36.45909507883878,
                    "KNACO3ION": 0.47115446696888114,
                    "KNAHCO3AQ": 1.4841143905036516,
                    "KNAHCO3PPT": 0.4892232518246443,
                    "KNAOH.1H2O": 36792.148988474095,
                    "KNAOHPPT": 1906246.209078427,
                    "KTRONAPPT": 0.07174589592459862,
                    "KWEGSCHEIDERPPT": 0.05311528707354195
                }
            }
        }
    }
}
```

{% hint style="info" %}
**Properties in result.additionalProperties**: prescalingTendencies, prescalingIndex, scalingIndex,  scalingTendencies, vaporToInflowMoleFraction, kValuesXBased, kValuesMBased
{% endhint %}

### Phase summary

Provides a quick snapshot of possible phases (liquid1, vapor, liquid2, and solid) present in the system, this array has four JSON objects corresponding to each phase in the system. The table below describes the object in this array.

| result.phase.phaseSummary\[0->3] | type   | description                                               |
| -------------------------------- | ------ | --------------------------------------------------------- |
| phase                            | string | name of phase (same as **phase\_name** above)             |
| found                            | bool   | **true** => phase present, **false** => phase not present |

### Kinetic outputs

Kinetic calculation outputs will be shown if kinetic calculations are specified. Detailed kinetic outputs can be found [here](/kinetic-calculation-outputs).


# Error/Warning output

If a computation fails in the API, the JSON response will look like the one below. The **data.error** object contains any **errors (data.error.error)** or **warnings (data.error.warning)** caught during the computation.

```javascript
{
  "code": 200,
  "data": {
    "error": {
      "error": {
        "messages": [
          {
            "code": 1001,
            "message": [
              "the equilibrium calculation failed to converge"
            ]
          },
          {
            "code": 1001,
            "message": [
              "the T, P calculation did not converge"
            ]
          }
        ]
      },
      "warning": {
        "messages": [
          {
            "code": 1001,
            "message": [
              "the maximum number of iterations were exceeded"
            ]
          }
        ]
      }
    }
  },
  "message": "Results returned successfully",
  "status": "SUCCESS"
}
```

| error.\[error/warning].messages\[ { } ] | type      | description           |
| --------------------------------------- | --------- | --------------------- |
| code                                    | number    | simulation error code |
| message                                 | \[string] | error message lines   |

Sometimes its also possible that the computation will succeed and return with the **data.result** object. But inside this object we may have **data.result.error** and/or **data.result.warning** object.&#x20;

```javascript
{
  "code": 200,
  "data": {
    "result": {
      ...<snip>...
      "error": {
        "error": {
          "messages": [
            {
              "code": 1001,
              "message": [
                "the equilibrium calculation failed to converge"
              ]
            },
            {
              "code": 1001,
              "message": [
                "the T, P calculation did not converge"
              ]
            }
          ]
        },
        "warning": {
          "messages": [
            {
              "code": 1001,
              "message": [
                "the maximum number of iterations were exceeded"
              ]
            }
          ]
        }
      }
    }
  },
  "message": "Results returned successfully",
  "status": "SUCCESS"
}
```


# Definition of terms

### `...<snip>....`

JSON output that is not relevant to the example

### `[ { } ]`

Denotes an array of JSON objects

### `valueObject`

A JSON object that has two keys namely, **value** and **unit**. Used for representing properties that have units.

```javascript
{
    "value": 25.0,
    "unit": "°C"
}
```

### `valueObject with name`

Similar to **valueObject** but with an extra **name** key. Used for giving extra information about the property.

```javascript
{
    "name": "NAION",
    "value": 0.566,
    "unit": "mol"
}
```


# Uploading a Process API package

A process API package that is exported from OLI Flowsheet, and needs to be uploaded into the users account.

### Uploading a package using the API

## upload a Process API package

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/channel/upload/package?status=Published`

uploads the **process API package** to the OLI cloud as **multipart/form-data**

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |

#### Request Body

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| files<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="200 " %}

```
{
    "file": [
        {
            "filename": "OLIProcessAPI.pkg",
            "id": "6408237f-286c-402b-890a-e67f2453761b"
        }
    ],
    "status": "UPLOADED",
    "type": "package"
}

```

{% endtab %}

{% tab title="400: Bad Request Check returned "message" for details" %}

```javascript
{
    "message": "Authorization 'Bearer ' Token not found",
    "status": "FAILED"
}
```

{% endtab %}
{% endtabs %}

### Response description

| field         | type         | description                                       |
| ------------- | ------------ | ------------------------------------------------- |
| file          | array object | uploaded package information:                     |
| file.filename | string       | name of file with extension                       |
| file.id       | string       | unique identifier for the uploaded file ProcessId |
| status        | string       | **"UPLOADED"** or **"FAILED"**                    |
| type          | string       | type of file "**package**"                        |

###


# Creating a Process API package

The Process API package needed to run a process using the API is created using OLI Flowsheet :ESP, the following steps explain how to create the package file.

1. Launch OLI Flowsheet: ESP and open the desired case file
2. Ensure the case file runs and converges

   Note: Sensitivity Analysis and Optimizer are not currently supported using Process API, so ensure your case does not include these options.
3. From the "***File"*** menu select "***Export...***"&#x20;
4. Change the "Save as type" to "Process API pkg. Files (\*.pkg)

   ![](https://1307681981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MK1GD7JkzSzCRydAEH3%2Fuploads%2Fu1A5nxfr6caZ2KTCJZrr%2Fimage.png?alt=media\&token=03ff024f-8588-4399-87fd-130bbe9864f5)
5. Now located the desired folder to save the package in and supply a file name


# Get list of all uploaded ProcessAPI packages

## Retrieve all uploaded ProcessAPI packages

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/process/all`

method returns a paginated list of all process packages.

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |

**Parameters**

<table><thead><tr><th width="228">Name</th><th width="87">Type</th><th width="164">Description</th><th width="140">Default Value</th><th>Max Value</th></tr></thead><tbody><tr><td>page (optional)</td><td>Integer</td><td>Start page</td><td>1</td><td>100000</td></tr><tr><td>limit (optional)</td><td>Integer</td><td>Results per page</td><td>20</td><td>100</td></tr></tbody></table>

{% tabs %}
{% tab title="200 - data array containing paginated list" %}

```json
 {
    "data": [
        {
            "channelId": "aa76fabf-06d2-4c98-a8fa-4caad454b20f",
            "comments": "This is a comment",
            "createdAt": 1590122290.23704,
            "createdBy": "5e44bec6-1cfd-472f-8e85-eb7fe715f47d",
            "creatorName": "John Smith",
            "processId": "afd5a8c1-eec5-4bf7-bd39-13e6a3f38c4b",
            "processName": "case_1:pH nuetralization with tear",
            "processStatus": "PUBLISHED",
            "totalcount": 1184,
            "updatedAt": 1590122820.73076,
            "updatedBy": "5e44bec6-1cfd-472f-8e85-eb7fe715f47d",
            "updatorName": "John Smith"
        },
        {...},
        {...}
   ],
    "message": "Process list returned successfully",
    "metadata": {
        "count": 20,
        "page": 1,
        "totalCount": 1184
    },
    "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}


# Get input specs for Process API package

Each ProcessAPI package has a unique set of input requirements based on the user design. This function will return the JSON input specification for the Process as it was uploaded to the cloud.

The returned JSON input specification is described in  [Process API input specification](/process-api-input-specification)

The developer will update the required inputs and provide this input into the call to run the process.

## Get the input specifications for the supplied process\_id

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/process/inputspec/{{process_id}}`

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "data": {
        "flowsheet": {
            "chemical-info": {
                "H2O": {
                    "formula": "H2O",
                    "mol-wt": 18.015341,
                    "name": "Water"
                },
                "H3OION": {
                    "formula": "H3O+1",
                    "mol-wt": 19.02331,
                    "name": "Hydronium ion(+1)"
                },
	    ...
            },
            "general-info": {
                "blocks": {
                    "controller": {
                        "names": []
                    },
                    "energy-transfers": {
                        "names": []
                    },
                    "mapTruncatedNameToFullName": {
                        "Mix-1": "Mix-1"
                    },
                    "standard": {
                        "names": [
                            "Mix-1"
                        ]
                    }
                },
                "chemistry-info": [
                    {
                        "name": "Chemi~01",
                        "thermo-framework": "MSE (H3O+ ion)"
                    }
                ],
                "streams": {
                    "inflow": [
                        {
                            "chemistry": "Chemi~01",
                            "name": "S-1"
                        },
                        {
                            "chemistry": "Chemi~01",
                            "name": "S-2"
                        }
                    ],
                    "mapTruncatedNameToFullName": {
                        "S-1": "S-1",
                        "S-2": "S-2",
                        "S-3": "S-3"
                    },
                    "outflow": [
                        {
                            "chemistry": "Chemi~01",
                            "name": "S-3",
                            "tear": false
                        }
                    ],
                    "virtual": []
                },
                "water-analyses-info": []
            },
            "layout": { ... },
            "properties": {
                "input": {
                    "blocks": [
                        {
                            "disabled": false,
                            "name": "Mix-1",
                            "props": [
                                {
                                    "bin-unit": "cal/hr",
                                    "delta": false,
                                    "name": "Heat Duty",
                                    "propid": 3,
                                    "unit": "J/hr",
                                    "value": 0.0
                                }
                            ]
                        }
                    ],
                    "streams": [
                        {
                            "name": "S-1",
                            "props": [
                                {
                                    "group": "Properties",
                                    "name": "Temperature",
                                    "unit": "°C",
                                    "value": 25.0
                                },
                                {
                                    "group": "Properties",
                                    "name": "Pressure",
                                    "unit": "atm",
                                    "value": 1.0
                                },
                                {
                                    "group": "Properties",
                                    "name": "TotalFlow",
                                    "unit": "mol/hr",
                                    "value": 57.0
                                },
                                {
                                    "group": "Inflow",
                                    "name": "H2O",
                                    "unit": "mol/hr",
                                    "value": 55.0
                                },
                                ...
                            ]
                        },
                        {
                            "name": "S-2",
                            ...
                        }
                    ],
                    "water-analyses": []
                },
                "output": {
                    "blocks": [
                        {
                            "name": "Mix-1",
                            "units_set_id": "11"
                        }
                    ],
                    "streams": [
                        {
                            "name": "S-1",
                            "units_set_id": "11"
                        },
                        {
                            "name": "S-2",
                            "units_set_id": "11"
                        },
                        {
                            "name": "S-3",
                            "units_set_id": "11"
                        }
                    ]
                },
                "postCalc": {
                    "global": {
                        "activityCoefficientsMBased": false,
                        "activityCoefficientsXBased": true,
                        "alkalinity": false,
                        "electricalConductivity": false,
                        "entropySpecies": false,
                        "entropySpeciesStandardState": false,
                        "fugacityCoefficients": true,
                        "gibbsEnergySpecies": false,
                        "gibbsEnergySpeciesStandardState": false,
                        "hardness": true,
                        "heatCapacity": false,
                        "interfacialTension": false,
                        "ionicStrengthMBased": true,
                        "ionicStrengthXBased": true,
                        "kValuesMBased": true,
                        "kValuesXBased": false,
                        "materialBalanceGroup": true,
                        "pHAtStdTP": false,
                        "partialPressure": true,
                        "prescalingIndexEstimated": false,
                        "prescalingIndexRigorous": false,
                        "prescalingTendenciesEstimated": false,
                        "prescalingTendenciesRigorous": false,
                        "scalingIndex": false,
                        "scalingTendencies": true,
                        "selfDiffusivityAndMobility": false,
                        "surfaceTension": false,
                        "thermalConductivity": false,
                        "vaporDiffusivityMatrix": false,
                        "vaporFugacity": true,
                        "vaporToInflowMoleFraction": false,
                        "viscosity": false
                    },
                    "streams": [
                        {
                            "alkalinity": false,
                            "name": "S-1",
                            "phAtStdTP": false,
                            "preScalingTendencies": false,
                            "totalDissolvedSolidsEstimated": true
                        },
                        {
                            "alkalinity": false,
                            "name": "S-2",
                            "phAtStdTP": false,
                            "preScalingTendencies": false,
                            "totalDissolvedSolidsEstimated": true
                        },
                        {
                            "alkalinity": false,
                            "name": "S-3",
                            "phAtStdTP": false,
                            "preScalingTendencies": false,
                            "totalDissolvedSolidsEstimated": true
                        }
                    ]
                }
            },
            "units_set_info": {
                "11": {
                    "alkalinity": "mg HCO3/L",
                    "amount": "mol/hr",
                    "area": "sq-cm",
                    "combined_phs_comp": "mol/hr",
                    "concentration": "mol/L",
                    "corrosionrate": "mm/yr",
                    "corsiz": "mm",
                    "cp": "cal/g K",
                    "current": "µA",
                    "current_den": "A/sq-m",
                    "cv": "L/mol",
                    "cycle": "rev",
                    "density": "g/ml",
                    "dif": "m2/s",
                    "econd": "µmho/cm",
                    "econdm": "m2/ohm-mol",
                    "ecurrent": "A",
                    "enthalpy": "J/hr",
                    "entr": "cal/K hr",
                    "equivalents": "eq/hr",
                    "equivalentsconc": "eq/L",
                    "equivalentsfrac": "eq/mol",
                    "equivalentsmolality": "eq/kg",
                    "fug": "atm",
                    "gas_vol": "L/hr",
                    "hardness": "mg/L as CaCO3",
                    "heat_duty": "E6cal/hr",
                    "heat_exch_capacity": "cal/K hr",
                    "heat_transfer_coeff": "cal/hr sq-m °C",
                    "i": "mol/mol",
                    "im": "mol/kg",
                    "induction_time": "min",
                    "inflows": "mol/hr",
                    "interfacial_tension": "N/m",
                    "kinetics_extent": "mol/hr",
                    "kinetics_k": "mol/hr m3",
                    "kinetics_rate": "mol/hr hr",
                    "length": "cm",
                    "liq1_phs_comp": "mol/hr",
                    "liq2_phs_comp": "mol/hr",
                    "liq_holdup": "m3/m3",
                    "liquid2_vol": "L/hr",
                    "liquid_vol": "L/hr",
                    "mass": "g/hr",
                    "mass_concentration": "mg/L",
                    "mass_transfer_coeff": "mol/hr sq-m",
                    "massfrac": "mass %",
                    "mob": "m2/s-volt",
                    "mol_entr": "cal/mol K",
                    "mol_gfe": "J/mol",
                    "molality": "mol/kg",
                    "molefrac": "mole %",
                    "moles": "mol/hr",
                    "part_pressure": "atm",
                    "permeability": "m/hr",
                    "permeability_coeff": "g/hr sq-m atm",
                    "pit_depth": "µm",
                    "pot": "V (SHE)",
                    "power": "hp",
                    "pt": "atm",
                    "resistance": "ohm",
                    "revolutions": "cycle/min",
                    "service_life": "day",
                    "shear_stress": "Pa",
                    "solid_phs_comp": "mol/hr",
                    "solid_vol": "L/hr",
                    "specific_p_drop": "atm/m",
                    "stdvol_gas_oil_ratio": "m3/m3",
                    "stdvol_water_gas_ratio": "m3/m3",
                    "surface_tension": "N/m",
                    "t": "°C",
                    "tds": "mg/L",
                    "thermalcond": "cal/hr m °C",
                    "tic": "mol C/L",
                    "time": "hr",
                    "total": "mol/hr",
                    "vapor_phs_comp": "mol/hr",
                    "velocity": "m/s",
                    "visabs": "cP",
                    "vol": "L/hr",
                    "vol_frac": "vol %",
                    "vol_pipe_flow": "m3/s"
                }
            }
        },
        "version": "test-00"
    },
    "message": "Process input specification retrieved successfully"
}
```

{% endtab %}
{% endtabs %}


# Get output specs for ProcessAPI package

Each ProcessAPI package will have a unique set of output based on the user design. This function will return a JSON dummy output specification for the Process.

## Get the output specifications for the supplied process\_id, the actual results in the returned JSON are dummy values

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/process/outputspec/{{process_id}}`

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |

{% tabs %}
{% tab title="200: OK " %}

```json
{
	"data": {
		"context": "solution",
		"flowsheetConvergence": true,
		"metadata": {
			"executionTime": {
				"unit": "ms",
				"value": 41.0
			},
			"versionInfo": {
				"fullVersion": "11.5.1.7"
			}
		},
		"output": {
			"blockOutput": {
				"Mix-1": {
					...                    
				}
				...
			}
			"streamOutput": {
				"S-1": {
					...
				},
				...
			}
		}
	},
	"message": "Process output specification retrieved successfully",
	"status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}


# Run a Process API calculation

Note: The time to run a calculation using the OLI Process API cannot be predicted accurately and also some calculations may take longer to compute than others. Hence, a polling mechanism is required to retrieve the result of each calculation. The steps for this mechanism are described below.

1. Send a **POST** request to the run URL below
2. If the request was successful(status:200), the JSON response back will contain a link to the results and status of the computation. The status inside the ***"data"*** array will be **IN QUEUE/IN PROGRESS**
3. Keep polling the returned results link with a **GET** request until the status member of the response changes from **IN PROGRESS to PROCESSED/FAILED/ERROR or COMPLETED**
4. When the status is **COMPLETED**, then response will also contain the result of the computation

###

## Run the selected process

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/process/run/{process_id}`

The input to run the calculation is provided in the body of the message as JSON, the input is  the data.flowsheet.properties object retrieved using the [Get input specs for Process API package](/group2/get-input-specs-for-process-api-package) call.

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-Type  | string | application/json       |

#### Request Body

| Name                               | Type | Description                                         |
| ---------------------------------- | ---- | --------------------------------------------------- |
| <mark style="color:red;">\*</mark> | JSON | <p>{ "properties" : { "input" " { ...}}}</p><p></p> |

{% tabs %}
{% tab title="200 " %}

```
{
	"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 %}

### Response description

| field            | description                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------ |
| data.jobId       | the current request job identifier                                                         |
| data.processId   | the processId used for the job being run                                                   |
| data.resultsLink | the https endpoint to poll to get the final result                                         |
| data.status      | <p>current status of the job<br><strong>IN QUEUE</strong>/<strong>IN PROGRESS</strong></p> |
| message          | message describing the request                                                             |
| status           | status of the current request, can be **SUCCESS** or **FAILED**                            |

```json
// Response from process-run call
{
    "data": {
        "jobId": "20978bbb-5f88-4ecd-ae90-582953afdedf",
        "processId": "a5c645fe-578b-4a48-a541-3d818d4ef564",
        "resultsLink": "https://api.olisystems.com/result/20978bbb-5f88-4ecd-ae90-582953afdedf?flash=&count=20",
        "status": "IN QUEUE"
    },
    "message": "Process execution started Successfully",
    "status": "SUCCESS"
}
```


# Get calculation status and results

## Result of computation \[Using returned result link from process-run call]

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/result/{jobId}?final-solution=true`

URL contains the result of the computation if status is processed

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-Type  | string | application/json       |

{% tabs %}
{% tab title="200 " %}

```
{
    "code": 200, 
    "data": {
        "result": {
          ...
          }
    }, 
    "message": "Results returned successfully", 
    "resultsLink": "https://api.olisystems.com/result/flash/fbce59ee-f31e-447b-b450-ba5b0d0a1a99?context=engine", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
status can be **IN QUEUE**, **IN PROGRESS**, **PROCESSED, FAILED** or **ERROR**

if status = **IN QUEUE**/**IN PROGRESS**, keep polling the endpoint in resultsLink

if status = **PROCESSED**, result should be in **data.result**

if status = **FAILED**, computation failure. error will be be in **data.error**

if status = **ERROR**, a system error occurred
{% endhint %}

#### Example chain of request responses

```json
// 1st response on GET resultsLink
{
    "data": {
        "processInfo": [
            {"context": "currentBlockInfo",
             "data": {"blockName": "MIX-1"}},
            {"context": "currentBlockInfo",
             "data": {"blockName": "HX - AB"}},
            {"context": "currentBlockInfo",
             "data": {"blockName": "HX - CD"}}
        ]
    },
    "message": "Results returned successfully",
    "resultsLink": "https://api.olisystems.com/result/20978bbb-5555-4ecd-ae90-582953afdedf?context=process&start=3&count=21",
    "status": "IN PROGRESS"
}

// 2nd request on GET resultsLink 
"data": {
        "context": "solution",
        "flowsheetConvergence": true,
        "metadata": {"executionTime": {"unit": "ms","value": 7030.0},
            "versionInfo": {"fullVersion": "11.5.1.7"}
        },
        "output": {
        "blockOutput": { 
        ...
        }
        "streamOutput": {
        ...
        }
        }
    },
    "message": "Results returned successfully",
    "status": "COMPLETED"
}
```

{% hint style="warning" %}
If the **data.context = "solution"** and **data.flowsheetConvergence = true** signifies that results are available.&#x20;
{% endhint %}


# Deleting a process package

When a process is deleted, it is marked for deletion and will be permantley deleted based on account/system settings.

## Delete provided ProcessAPI package

<mark style="color:red;">`DELETE`</mark> `https://api.olisystems.com/process/{process_id}`

Delete the process package supplied as the last paramter {process\_id} of the URL

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |

{% tabs %}
{% tab title="200 data is an array containing information for each dbs file that was uploaded." %}

```json
 {
    "message": "Process is deleted Successfully",
    "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}


# Undelete a process package

If a process package was accidently deleted, it may be recovered (undeleted) until the system has permanently deleted it.

## Undelete provided ProcessAPI package&#x20;

<mark style="color:orange;">`PUT`</mark> `https://api.olisystems.com/process/{process_id}`

Delete the process package supplied as the last paramter {process\_id} of the URL

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |

{% tabs %}
{% tab title="200 data is an array containing information for each dbs file that was uploaded." %}

```json
{
    "message": "Process is moved to its previous state Successfully",
    "status": "SUCCESS"
}
```

{% endtab %}

{% tab title="403: Forbidden package was not recoverable" %}

```javascript
{
    "message": "User does not have required permissions",
    "status": "FAILED"
}
```

{% endtab %}
{% endtabs %}


# Process API input specification

This section descibes the returned input specification from the [Get input specs for Process API package](/group2/get-input-specs-for-process-api-package)


# "data" object

The "data" section contains the following 2 sub sections

* "flowsheet" - Contains all information for the flowsheet
* "version" - Version of Flowsheet used to export the package


# "flowsheet" object

* "chemical-info" - Chemistry model information for the process
* "general-info" - Information on Blocks/Streams/Chemistry models / Water Analysis&#x20;
* "layout" - Layout information of the process - Internal use only
* "properties" - Input information for the process (temp, press, composition, ...)
* "units\_set\_info" - Unit set definitions for the process


# "chemical-info" object


# "general-info" object


# "properties" object

This section is supplied as the input when running a process API calculation

This JSON "properties" object is provided to the run Process API call as the input for the calculation.


# "units\_set\_info" object


# Uploading chemistry model files for ScaleChem API

One or more chemistry model files (dbs files) need to are needed to process a scalechem API request. These files need to be zipped together and the zip file uploaded to the OLI cloud.

## Upload package

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/channel/upload/scalechem`

Upload zipped dbs files as a package

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | String | Bearer {access\_token} |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    'file': [
    {
        'filename': 'mixerAll.zip', 
        'id': '4b9cffb4-23ae-4541-8c98-3cb11f43a480'
    }
    ], 
    'status': 'UPLOADED', 
    'type': 'scalechem'
}
```

{% endtab %}
{% endtabs %}

### Response description

| field              | type            | description                             |
| ------------------ | --------------- | --------------------------------------- |
| file               | array of object | information of files uploaded:          |
| file\[  ].filename | string          | name of file with extension             |
| file\[  ].id       | string          | unique identifier for the uploaded file |
| status             | string          | **"UPLOADED"** or **"FAILED"**          |
| type               | string          | type of file                            |


# Get list of uploaded ScaleChem model files

method returns a paginated list of all ScaleChem model files.

## Get list of packages in a private channel

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/channel/scalechem`

| Name          | Type   | Description               |
| ------------- | ------ | ------------------------- |
| Authorization | String | Bearer {access\_tokentabl |

#### Parameters

<table><thead><tr><th width="173">Name</th><th>Type</th><th width="170">Description</th><th>Default Value</th><th>Max Value</th></tr></thead><tbody><tr><td>page (optional)</td><td>Integer</td><td>Start page</td><td>0</td><td>100000</td></tr><tr><td>count (optional)</td><td>Integer</td><td>Results per page</td><td>20</td><td>100</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "data": {
    "files": [
      {
        "createdAt": "Tue, 15 Mar 2022 17:28:01 GMT",
        "createdBy": "bbb27a13-bf4b-45c3-af76-a8a4ea8fd27d",
        "creatorName": "creater name",
        "fileId": "6d73c011-8eaf-4a1c-9ced-27aa1e27e614",
        "name": "mixerAll.zip",
        "path": "OLI_APP_FILES/00130000000JsxhAAC/scalechem/bbb27a13-bf4b-45c3-af76-a8a4ea8fd27d/6d73c011-8eaf-4a1c-9ced-27aa1e27e614/mixerAll.zip",
        "status": "ACTIVE",
        "updatedAt": "Tue, 15 Mar 2022 17:28:01 GMT",
        "updatedBy": "bbb27a13-bf4b-45c3-af76-a8a4ea8fd27d",
        "updatorName": "update name"
      },
      {
        "createdAt": "Tue, 15 Mar 2022 17:30:10 GMT",
        "createdBy": "bbb27a13-bf4b-45c3-af76-a8a4ea8fd27d",
        "creatorName": "creater name",
        "fileId": "3a078037-2bd8-4e75-91d0-c10ba322d3b0",
        "name": "mixerAll2.zip",
        "path": "OLI_APP_FILES/00130000000JsxhAAC/scalechem/bbb27a13-bf4b-45c3-af76-a8a4ea8fd27d/3a078037-2bd8-4e75-91d0-c10ba322d3b0/mixerAll.zip",
        "status": "ACTIVE",
        "updatedAt": "Tue, 15 Mar 2022 17:30:10 GMT",
        "updatedBy": "bbb27a13-bf4b-45c3-af76-a8a4ea8fd27d",
        "updatorName": "update name"
      }]
    },
  "message": "Channel file and package list returned successfully",
  "status": "SUCCESS"
  }
}
```

{% endtab %}
{% endtabs %}

## Download package by file id

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/channel/download/file/{fileId}`

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | String | Bearer {access\_token} |

## Delete uploaded package by file id

<mark style="color:red;">`DELETE`</mark> `https://api.olisystems.com/channel/file/{fileId}`

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | String | Bearer {access\_token} |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "message": "File deleted successfully",
  "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}


# Main methods

This page summarizes all the methods supported by the OLI ScaleChem API and explains the basic input schema.

## Run scalechem calculation

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/scalechem/{fileId}`

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |
| Content-Type                                    | String | application/json       |

{% tabs %}
{% tab title="200: OK Please look at "API call blueprint" page " %}

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

```json
{
    "method": "scalechem.brineAnalysis",
    "params": {
        "chemistryModel": "chem",
        ...<snip>...
        }
}
```

### Methods

| method                       | description                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------- |
| "scalechem.brineAnalysis"    | [Brine analysis](/oli-scalechem-api/main-methods/brine-analysis)             |
| "scalechem.oilAnalysis"      | [Oil analysis](/oli-scalechem-api/main-methods/oil-analysis)                 |
| "scalechem.gasAnalysis"      | [Gas analysis](/oli-scalechem-api/main-methods/gas-analysis)                 |
| "scalechem.mixerCalculation" | [Mixer calculation](/oli-scalechem-api/main-methods/mixer-calculation)       |
| "scalechem.scaleScenario"    | [Calculate scaling scenario](/oli-scalechem-api/main-methods/scale-scenario) |

### Chemistry model

**params.chemistryModel** specifies the name of the chemistry model file with ".dbs" extension, that is uploaded in the package.


# Brine analysis

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

### Request payload

```json
{
    "method": "scalechem.brineAnalysis",
    "params": {
        "chemistryModel": "chem",
        "waterAnalysisInputs": [
            ...<snip>...
        ]
    }
}
```

<table data-header-hidden><thead><tr><th width="223.33333333333334">params</th><th>type</th><th>description</th></tr></thead><tbody><tr><td><strong>params</strong></td><td>type</td><td>description</td></tr><tr><td>chemistryModel</td><td>string</td><td><a href="/oli-scalechem-api/main-methods#chemistry-model">chemistry model name</a></td></tr><tr><td>waterAnalysisInputs</td><td>array of objects</td><td><a href="/group1/api-functions/wateranalysis">water analysis inputs</a></td></tr></tbody></table>

Brine analysis uses the same input options as the water analysis in OLI Engine API. Please refer to [water analysis](/group1/api-functions/wateranalysis) for the specifications of **params.waterAnalysisInputs**.

{% hint style="info" %}
In addition to the inputs shown above, some optional properties may also be specified. They can be viewed at [Optional Inputs](/optional-inputs).
{% endhint %}

### Response (status = PROCESSED)

Please refer to the [response ](/group1/api-functions/wateranalysis#response-status-processed)of water analysis in OLI Engine API.


# Gas analysis

### Request payload

```json
{
    "method": "scalechem.gasAnalysis",
    "params": {
        "chemistryModel": "chem",
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 2.0,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mole %",
            "values": {
                "H2O": 10.0,
                "CO2": 10.0,
                "CH4": 40.0,
                "C4H10": 20.0
            }
        },
        "saturateWithH2O": true
    }
}
```

| **param**       | type                                         | description                                                               |
| --------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| chemistryModel  | string                                       | [chemistry model name](/oli-scalechem-api/main-methods#chemistry-model)   |
| temperature     | [valueObject](/terms-definition#valueobject) | specified temperature with [unit](/input-unit-set)                        |
| pressure        | [valueObject](/terms-definition#valueobject) | specified pressure with [unit](/input-unit-set)                           |
| inflows         | object                                       | specified inflow species composition, see [Inflows Input](/inflows-input) |
| saturateWithH2O | boolean                                      | option to add H2O to saturate the vapor phase.                            |

{% hint style="info" %}
**params.saturateWithH2O** input is optional. By default, it's set to false.
{% endhint %}

{% hint style="info" %}
In addition to the inputs shown above, some optional properties may also be specified. They can be viewed at [Optional Inputs](/optional-inputs).
{% endhint %}

### Response (status = PROCESSED)

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output).

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |
| "/params/inflows/values/*\<InflowName>*"     |


# Oil analysis

### Request payload

```json
{
    "method": "scalechem.oilAnalysis",
    "params": {
        "chemistryModel": "chem",
        "temperature": {
            "value": 30.0,
            "unit": "°C"
        },
        "pressure": {
            "value": 2.0,
            "unit": "atm"
        },
        "inflows": {
            "unit": "mole %",
            "values": {
                "H2O": 10.0,
                "CO2": 10.0,
                "CH4": 40.0,
                "C4H10": 20.0
            }
        },
        "saturateWithH2O": true
    }
}
```

| **param**       | type                                         | description                                                               |
| --------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| chemistryModel  | string                                       | [chemistry model name](/oli-scalechem-api/main-methods#chemistry-model)   |
| temperature     | [valueObject](/terms-definition#valueobject) | specified temperature with [unit](/input-unit-set)                        |
| pressure        | [valueObject](/terms-definition#valueobject) | specified pressure with [unit](/input-unit-set)                           |
| inflows         | object                                       | specified inflow species composition, see [Inflows Input](/inflows-input) |
| saturateWithH2O | boolean                                      | option to add H2O to saturate the organic liquid phase.                   |

{% hint style="info" %}
**params.saturateWithH2O** input is optional. By default, it's set to false.
{% endhint %}

{% hint style="info" %}
In addition to the inputs shown above, some optional properties may also be specified. They can be viewed at [Optional Inputs](/optional-inputs).
{% endhint %}

### Response (status = PROCESSED)

The output of this calculation is the [stream output ](/stream-output-json)which is common result output for all OLI's flash calculations or an [error](/error-output).

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field** |
| -------------------------------------------- |
| "/params/temperature/value"                  |
| "/params/pressure/value"                     |
| "/params/inflows/values/*\<InflowName>*"     |


# Mixer calculation

This function performs a mixer calculation to combine external streams and flash at an isothermal condition.

### Request payload

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        "name": "mixer",
        "chemistryModel": "mixerChemistry",
        "externalStreams": [...<snip>...],
        "inletInputs": [...<snip>...],
        "temperature": {
            "unit": "°C",
            "value": 50
        },
        "pressure": {
            "unit": "bar",
            "value": 1.1
        }
    }
}
```

| **params**      | type                             | description                                                                                                                                                                                              |
| --------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name            | string                           | name of output stream                                                                                                                                                                                    |
| chemistryModel  | string                           | [chemistry model file (dbs) name](/oli-scalechem-api/main-methods#chemistry-model) for mixer calculation                                                                                                 |
| externalStreams | array of objects                 | [inputs for external streams](#external-streams)                                                                                                                                                         |
| inletInputs     | array of objects                 | [flow rate specifications for mixer inlet streams](#undefined)                                                                                                                                           |
| temperature     | [valueObject](/terms-definition) | specified temperature with [unit](/input-unit-set)                                                                                                                                                       |
| pressure        | [valueObject](/terms-definition) | specified pressure with [unit](/input-unit-set)                                                                                                                                                          |
| inheritOptions  | boolean                          | Optional, option to apply "[optionalProperties](/optional-inputs#optional-properties)"  and "[unitSetInfo](/optional-inputs#output-units)" to calculation objects in "externalStreams". Default is false |

### External streams

External streams can be calculated by three types of inputs at isothermal conditions: 1) ionic species composition, 2) inflow species composition, 3) mixer calculation to combine calculated external stream.&#x20;

{% tabs %}
{% tab title="ionic input stream" %}

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        ...<snip>...
        "externalStreams": [
            {
                "name": "brine example",
                "chemistryModel": "brineChemistry",
                "waterAnalysisInputs": [...<snip>...]
            },
            {
                "name": "another stream",
                ...<snip>...
            },
            ...<snip>...
        ]
    }
}
```

{% endtab %}

{% tab title="inflow input stream" %}

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        ...<snip>...
        "externalStreams": [
            {
                "name": "inflow example",
                "chemistryModel": "inflowChemistry",
                "inflows": {...<snip>...},
                "temperature": {
                    "value": 50.0,
                    "unit": "°C"
                },
                "pressure": {
                    "value": 1.5,
                    "unit": "atm"
                },
                "saturateWithH2O": "gas"
            },
            {
                "name": "another stream",
                ...<snip>...
            },
            ...<snip>...
        ]
    }
}
```

{% endtab %}

{% tab title="mixer calculation stream" %}

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        ...<snip>...
        "externalStreams": [
            {
                "name": "example stream 1",
                ...<snip>...
            },
            {
                "name": "example stream 2",
                ...<snip>...
            },
            {
                "name": "mixer example",
                "chemistryModel": "externalMixerChemistry",
                "inletInputs": [
                    {
                        "streamName": "example stream 1",
                        "streamType": "brine",
                        "totalAmount": {
                            "value": 1,
                            "unit": "bbl/day"
                        }
                    },
                    {
                        "streamName": "example stream 2",
                        ...<snip>...
                    }
                ],
                "temperature": {
                    "value": 50.0,
                    "unit": "°C"
                },
                "pressure": {
                    "value": 1.5,
                    "unit": "atm"
                }
            },
            {
                "name": "another stream",
                ...<snip>...
            },
            ...<snip>...
        ]
    }
}
```

{% endtab %}
{% endtabs %}

#### Common external stream inputs

| **params.externalStreams\[{}]** | type   | description                                                   |
| ------------------------------- | ------ | ------------------------------------------------------------- |
| name                            | string | external stream name                                          |
| chemistryModel                  | string | optional, chemistry model file (dbs) name for external stream |

{% hint style="success" %}
"chemistryModel" input is optional. The chemistry model file of the mixer calculation will be used if this input is missing.
{% endhint %}

#### External stream from ionic input

All inputs are specified as an array of objects in "waterAnalysisInputs", which are explained in[ water analysis ](/group1/api-functions/wateranalysis#water-analysis)calculation.

#### External stream from inflow input

| **params.externalStreams\[{}]** | type                             | description                                                                                                                     |
| ------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| inflows                         | object                           | [inflow input](/inflows-input)                                                                                                  |
| temperature                     | [valueObject](/terms-definition) | specified temperature with [unit](/input-unit-set)                                                                              |
| pressure                        | [valueObject](/terms-definition) | specified pressure with [unit](/input-unit-set)                                                                                 |
| saturateWithH2O                 | string                           | optional, could be specified as "gas" or "oil", which will add H2O to the system to saturate the corresponding phase with water |

#### External stream from mixer calculation

|                                 |                                  |                                                                                                             |
| ------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **params.externalStreams\[{}]** | type                             | description                                                                                                 |
| inletInputs                     | array of objects                 | name, type, and flow rate for combining stream, as explained in [inlet specification](#inlet-specification) |
| temperature                     | [valueObject](/terms-definition) | specified temperature with [unit](/input-unit-set)                                                          |
| pressure                        | [valueObject](/terms-definition) | specified pressure with [unit](/input-unit-set)                                                             |

{% hint style="warning" %}
External streams are calculated in the order of the input array. Any mixer calculation specified in external streams can combine external streams that are already calculated.
{% endhint %}

{% hint style="info" %}
Any mixer calculation in external streams can be treated as an inlet for followed mixer calculations. In other words, mixer calculations can be specified cascadingly in external streams.
{% endhint %}

### Inlet specification

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        ...<snip>...
        "inletInputs": [
            {
                "streamName": "external stream 1",
                "streamType": "brine",
                "totalAmount": {
                    "value": 1.0, 
                    "unit": "bbl/day"
                }
            },
            {
                "streamName": "external stream 2",
                ...<snip>...
            },
            ...<snip>...
        ]
    }
}
```

|                             |                                  |                                                                                                                                    |
| --------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **params.inletInputs\[{}]** | type                             | description                                                                                                                        |
| streamName                  | string                           | name of the [external stream](#external-streams) to be combined in mixer                                                           |
| streamType                  | string                           | stream type, this determines target phases to be combined in mixer                                                                 |
| totalAmount                 | [valueObject](/terms-definition) | inlet stream flow rate with unit explained below                                                                                   |
| automaticFlowRate           | boolean                          | optional, when speciefied as true, total flow rate specified in the external stream will be used, then "totalAmount" is not needed |

{% hint style="warning" %}
"automaticFlowRate" can only be specified true when the corresponding external stream is calculated in [flowing system](/inflows-input#units-in-flowing-systems).
{% endhint %}

#### Inlet stream types

| **params.inletInputs\[{}].streamType** | phases to be combined     | phase property to be used in calculating flow rate |
| -------------------------------------- | ------------------------- | -------------------------------------------------- |
| brine                                  | liquid-1                  | liquid-1                                           |
| oil                                    | vapor, liquid-2           | liquid-2                                           |
| gas                                    | vapor, liquid-2           | vapor                                              |
| whole fluid                            | liquid-1, liquid-2, vapor | all phases                                         |

<table data-header-hidden><thead><tr><th width="221.79121149644584"></th><th></th></tr></thead><tbody><tr><td><strong>params.inletInputs[{}].streamType</strong></td><td><strong>params.inletInputs[{}].totalAmount.unit</strong> numerators</td></tr><tr><td>brine, whole fluid</td><td>bbl, L, ml, cm3, m3, E3m3, E6m3, ft3, Mft3, MMft3, gal, MMgal</td></tr><tr><td>oil</td><td>std bbl, std m3, std L, bbl, m3, L</td></tr><tr><td>gas</td><td>std MMft3, std Mft3, std ft3, std E3m3, std m3, std L, MMft3, Mft3, ft3, E3m3, m3, L</td></tr></tbody></table>

{% hint style="info" %}
**params.inletInputs\[{}].totalAmount.unit** is flow rate unit with volumetric units as shown above divide by a time unit, i.e. bbl/day. Available time units are s, min, hr, day, yr.
{% endhint %}

### Saturator option (optional)

This option can be specified to saturate one or more solid species by varying the inflow species.

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        ...<snip>...
        "saturatorOptions": [
            {
                "mineralToSaturate": "BASO4PPT",
                "inflowToVary": "BASO4"
            },
            ...<snip>...
        ]
    }
}
```

|                                  |        |                                                                                                                                                   |
| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **params.saturatorOptions\[{}]** | type   | description                                                                                                                                       |
| mineralToSaturate                | string | solid species to be saturated, using "trueName"  for species with solid phase. See [chemistry information](/group1/api-functions/chemistry-info). |
| inflowToVary                     | string | varying inflow species, using "baseName"  for inflows. See [chemistry information](/group1/api-functions/chemistry-info).                         |

### Additional input

{% hint style="info" %}
In addition to the inputs shown above, some optional properties may also be specified. They can be viewed [here](/optional-inputs).
{% endhint %}

### Response (status = PROCESSED)

```json
{
    "code": 200,
    "result": {
       "external stream 1": {...<snip>...},
       "external stream 2": {...<snip>...},
       ...<snip>...,
       "mixer outlet stream": {...<snip>...}
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

The "result" contains all [stream outputs ](/stream-output-json)for each external stream and the final mixer outlet stream by their names specified in the input.

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field**                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------- |
| "/params/temperature/value"                                                                                                         |
| "/params/pressure/value"                                                                                                            |
| "/params/inletInputs/***i***/totalAmount/value" where ***i*** is the index (0 based) of the **params.inletInputs** array of objects |


# Scale scenario

This calculation combines several streams and calculate the scale scenario at a series of locations of different conditions.

### Request payload

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        "name": "mixer",
        "chemistryModel": "mixerChemistry",
        "externalStreams": [...<snip>...],
        "inletInputs": [...<snip>...],
        "scenarios": [...<snip>...]
    }
}
```

| **params**      | type             | description                                                                                                        |
| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| name            | string           | name of output stream                                                                                              |
| chemistryModel  | string           | [chemistry model file (dbs) name](/oli-scalechem-api/main-methods#chemistry-model) for scale scenario calculations |
| externalStreams | array of objects | [inputs for external streams](#external-streams)                                                                   |
| inletInputs     | array of objects | [flow rate specifications for mixer inlet streams](#undefined)                                                     |
| scenarios       | array of objects | [scale scenario specification](#undefined)                                                                         |

After combining all inlet streams, this calculation performs a series of calculations in the locations specified as below, where the outlet of each location is passed as the inlet to the next location.

### Scale scenario inputs

```json
{
    "method": "scalechem.mixerCalculation",
    "params": {
        ...<snip>...,
        "scenarios": [
        {
            "location": "Stock tank",
            "temperature": {
                "unit": "°C",
                "value": 20
            },
            "pressure": {
                "unit": "bar",
                "value": 2
            }
        },
        {
            "location": "Stock tank",
            "temperature": {
                "unit": "°C",
                "value": 15
            },
            "pressure": {
                "unit": "bar",
                "value": 1.5
            },
            "dropSolids": true
        },
        ...<snip>...
        ]
    }
}
```

|                           |                                  |                                                                                                                                |
| ------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **params.scenarios\[{}]** | type                             | description                                                                                                                    |
| location                  | string                           | location name                                                                                                                  |
| temperature               | [valueObject](/terms-definition) | specified temperature with [unit](/input-unit-set)                                                                             |
| pressure                  | [valueObject](/terms-definition) | specified pressure with [unit](/input-unit-set)                                                                                |
| dropSolids                | boolean                          | optional. If specified as true, all solids in the outlet are removed when passing as inlet to next location. Default is false. |

### Additional input

{% hint style="info" %}
In addition to the inputs shown above, some optional properties may also be specified. They can be viewed [here](/optional-inputs).
{% endhint %}

### Response (status = PROCESSED)

```json
{
    "code": 200,
    "result": {
       "external stream 1": {...<snip>...},
       "external stream 2": {...<snip>...},
       ...<snip>...,
       "scenarioOutputs": [
       {
          "location": "Stock tank", 
          "result": {...<snip>...}
       },
       ...<snip>...
       ]
    },
    "message": "Results returned successfully", 
    "status": "PROCESSED"
}
```

The "result" contains all [stream outputs ](/stream-output-json)for each external stream. Results of each location are listed as an array of objects in **result.scenarioOutputs**, with location and result of corresponding [stream output](/stream-output-json).

by their names specified in the input.

### Survey Calculation

Survey calculation is supported for the variables below. Please refer to [Survey calculation](/survey-calculation) for explained input schema.

| supported **params.surveyInputs\[{}].field**                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------- |
| "/params/temperature/value"                                                                                                         |
| "/params/pressure/value"                                                                                                            |
| "/params/inletInputs/***i***/totalAmount/value" where ***i*** is the index (0 based) of the **params.inletInputs** array of objects |
| "/params/scenarios/***i***/temperature/value" where ***i*** is the index (0 based) of the **params.scenarios** array of objects     |
| "/params/scenarios/***i***/pressure/value" where ***i*** is the index (0 based) of the **params.scenarios** array of objects        |