Articles in this section

Getting Started with OLI ChemBuilder API

Objective

The objective of this article is to provide details on using the ChemBuilder API to create chemistry files. It outlines steps to construct a JSON input file with essential components such as framework, phases, inflows, solids, redox, and kinetics, culminating in the generation of a DBS file.

Overview of OLI ChemBuilder API

The OLI ChemBuilder API is designed to simplify the creation of .dbs chemistry files, essential for other OLI cloud API services such as EngineAPI, CorrosionAPI, and ScaleChemAPI. This API streamlines workflows by enabling the generation of chemistry model files directly within the cloud, thus eliminating the need for manual creation and upload of .dbs files via OLI's desktop applications.

To generate a .dbs file using the ChemBuilder Cloud API, a JSON file with the necessary fields is required. These fields can include:

Params Required? Details Link
thermodynamicFramework Yes Unique thermodynamic framework identifier that matches the official names used in OLI Studio. Click Here
privateDatabanks Optional Databanks allow users to include a variety of species not found in the default OLI databases. Click Here
inflows Yes This field selects all species needed to build a chemistry model file. Click Here
phases Yes Used to select the phases expected to form in the system. Click Here
modelName Yes Specifies the output file name. Click Here
redox Optional Specifies all oxidation states for a chemical element. Click Here
includedSolids Optional Includes only user-specified solid phases of species, excluding all others by default. Click Here
excludedSolids Optional Excludes the user-specified solid phases. Click Here
kinetics Optional Add kinetic reactions and rate constants to the chemistry file using this field. Click Here

Here is an example of a simple JSON payload to create a Chemistry model (.dbs) file is:

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

Note: If you have the JSON input ready, you can skip to the ChemBuilder Workflow section.

Users can also leverage the Chemistry Builder Query APIs to gather information on inflows, kinetics, or redox, which can then be compiled into a single JSON file for creating the chemistry file. For more details on the query APIs, refer to these sections:

ChemBuilder Query Details Link
Species Query Species query method can be used to verify the existence and validity of species names within a thermodynamic framework. Click Here
Redox Query The Redox query displays each element's available valence states for user reference. Click Here
Solid Phase Query Using provided inflow species and their oxidation states, identify all solid phases via the solid query method. Click Here
Databank Query The databank query can be used to verify if the species is supported by the linked private thermodynamic databank. Click Here
Kinetics Query Retrieve kinetics equations for complex calculations. When all components are correctly specified, equilibrium equations for resulting species are accessible through the kinetics query. Click Here

 

ChemBuilder API Workflow

This section provides a detailed walkthrough of the steps required to run calculations using the OLI ChemBuilder API.

1. Prerequisites

Ensure the following prerequisites are met:

  • An active OLI Portal account
  • Permissions to create chemistry models.

2. Authentication Process

Begin by authenticating to the OLI Cloud:

  • Login Request: Authenticate at the OLI Cloud authentication endpoint using OLI account credentials. Obtain a JSON Web Token (JWT) during this step, which is essential for subsequent API requests and must be included in the authorization header for security.

3. Preparing the JSON Input File

Preparing the JSON input file involves defining the unique thermodynamic framework identifier, specifying all species needed for the chemistry model, identifying the phases expected to form in the system, setting a specific name for the output file, and optionally including additional fields such as privateDatabanks, redox conditions, includedSolids and excludedSolids, and kinetics.

4. Chemistry Model Generation Request

  • POST Request: Send a POST request to the DBS endpoint with the prepared JSON input in the body payload and the JWT token in the authorization header. This request initiates the creation of the chemistry model.

    Example Chemistry Creation Request (Python):

    import requests
    import json
    url = "https://api.olisystems.com/channel/dbs"
    payload = json.dumps({
    "method": "chemistrybuilder.generateDBS",
    "params": {
      "thermodynamicFramework": "MSE-SRK (H3O+ ion)",
      "privateDatabanks": ["GEM"],
      "modelName": "testModel",
      "phases": [
        "liquid1",
        "vapor",
        "solid",
        "liquid2"
      ],
      "inflows": [
        {
          "name": "H2O"
        },
        {
          "name": "NACL"
        },
        {
          "name": "ND2MOO43"
        }
      ]
    }
    })
    headers = {
    'Authorization': 'Bearer your_jwt_token',
    'Content-Type': 'application.json'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    print(response.text)

  • Request Response: After submitting the create request, the user receives a JSON response containing the request status and additional data. If the status is “SUCCESS,” the data section will include the ID of the newly created chemistry file, which can now be used in OLI calculations.
    • Success Response: If the status is "SUCCESS", the response includes the ID of the generated chemistry file, which can be used in subsequent calculations.
    • Delayed Response: If the file creation process takes longer, the system returns a resultsLink. Submit a GET request to this URL to obtain the chemistry file ID once ready.
    • Failed Response: If the request fails, the response includes an error status and message. Refer to the Error Response Documentation for more information.

Example Success Response

{
"data": {
"fileName": "testModel",
"id": "d73b2b2a-bf25-4630-8e22-0f97006ed6b3",
"metadata": {}
},
"message": "DBS file generated successfully",
"status": "SUCCESS"
}

Example Failed Response

{
"data": {
"error": {
"error": {
"messages": [
{
"code": 0...
}
]
}
},
"metaData": {...}
},
"message": "Chemistry could not be generated",
"status": "FAILED"
}

The .dbs chemistry file created through this method can be used with EngineAPI, CorrosionAPI, and ScaleChemAPI for brine, gas, or oil analysis. However, this .dbs file is not compatible with ProcessAPI calculations or Mixer and scenario calculations using ScaleChemAPI.

After creating the chemistry file, users can utilize the chemistry-information function along with the file ID to query specific details related to the chemistry file. This function can also be used to verify the accessibility and validity of the generated chemistry file, ensuring that it is ready for use in subsequent calculations.

Once the chemistry file ID is generated, there is no need to regenerate the file for similar calculations unless the required variables—such as the measured inflow species list, enabled phases, thermodynamic framework, and optional properties like solid list configurations, databanks, redox conditions, and kinetics—change.

By following these steps, users can effectively initiate requests and create chemistry models using the ChemBuilder API, streamlining their workflows and enhancing their ability to conduct detailed chemical analyses. If you have any questions or require the Python starter kit for ChemBuilder API, please contact OLI Customer Support.

Was this article helpful?
0 out of 0 found this helpful