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.