Objective
This article provides an overview of the OLI EngineAPI, detailing supported calculations, steps to initiate a simple calculation, and links to developers' documentation.
Overview of OLI EngineAPI
The OLI EngineAPI is a robust tool equivalent to the OLI Stream Analyzer, enabling users to perform a wide range of calculations. These include water analysis, flash calculations, equilibrium analyses across multiple phases, advanced mechanisms like redox and kinetics, property calculations, and specific conditions such as pH-controlled experiments. This guide offers a detailed walkthrough on utilizing these APIs effectively.
List of calculations supported by OLI EngineAPI.
Calculation | DevDocs URL |
---|---|
Isothermal flash | Click Here |
Isenthalpic flash | Click Here |
Bubble point flash | Click Here |
Dew point flash | Click Here |
Vapor amount flash | Click Here |
Vapor fraction flash | Click Here |
Isochoric flash | Click Here |
Set pH flash | Click Here |
Precipitation point flash | Click Here |
Autoclave | Click Here |
Custom flash | Click Here |
Water analysis | Click Here |
Calculation Workflow
This guide provides a detailed walkthrough of the necessary steps to run calculations using the OLI EngineAPI.
1. Prerequisites
Ensure the following prerequisites are met:
- An active OLI Portal account
- A chemistry model (
.dbs
) file or instructions to create one using ChemBuilder
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. Managing Chemistry Files
The EngineAPI requests require a chemistry file, which can be created using one of the following methods:
-
Upload Chemistry Model File: Upload the
.dbs
chemistry model file to the upload dbs endpoint. A unique file ID is returned, which is required for future calculations. -
Create .dbs using ChemBuilder API: Refer to the ChemBuilder documentation to create a
.dbs
file using the APIs.
Chemistry File Reusability: Once the chemistry file ID is obtained, there is no need to re-upload the file for similar calculations using the same framework, inflow species, phases, and other chemical properties. This file ID can be reused.
4. Running Calculations
Once the chemistry .dbs
file ID is available, users can initiate calculation requests:
- Initiate Calculation Request: Send a request to a specific calculation endpoint. The request should include the required JSON input in the body payload and the chemistry model file ID as part of the endpoint URL.
- Result Retrieval: After the calculation request, users receive a resultsLink. Poll this link until the calculation is processed. The results are provided in JSON format and are ready for analysis.
Note: Valid OLI account token (JWT) is required with each API request and must be included in the authorization header.
5. Concurrent Requests and Polling for Results
The system supports concurrent calculations, enabling users to manage multiple calculation requests simultaneously. The number of parallel calculation requests allowed depends on the user's license type. Each results URL can be polled independently by the user. There are two main approaches to retrieve the results:
- Polling: Users can periodically poll the results URL to check the simulation status and retrieve data once available. This involves making repeated requests until the simulation is complete.
- Asynchronous Calls: Users can utilize asynchronous HTTP libraries like aiohttp to make non-blocking requests to the results URL. This allows initiating multiple concurrent requests without waiting for each to complete, optimizing performance and resource usage for simultaneous simulations.
Once the simulation is complete and the results are ready, users can analyze and process the retrieved data according to their specific requirements.
Example Isothermal Flash Calculation
1. Flash Calculation Setup
Prepare your JSON input to specify the flash calculation's parameters, including temperature, pressure, component inflows, and optional properties such as viscosity and electrical conductivity.
Here’s an example of how to structure your JSON input for a flash calculation:
{
"params": {
"temperature": {
"value": 40.0,
"unit": "°F"
},
"pressure": {
"value": 100.0,
"unit": "psig"
},
"inflows": {
"unit": "mol",
"values": {
"H2O": 54.9215,
"NACL": 0.434972,
"HCL": 0.017595,
"CO2": 0.0039111,
"MGO": 0.00411438,
"CAO": 0.00249513,
"K2O": 0.00127883
}
},
"optionalProperties": {
"electricalConductivity": true,
"totalDissolvedSolids": true,
"viscosity": true,
"thermalConductivity": true,
"prescalingTendencies": true,
"prescalingTendenciesRigorous": true,
"hardness": true
},
"unitSetInfo": {
"liq1_phs_comp": "mg",
"solid_phs_comp": "mg",
"vapor_phs_comp": "mg",
"liq2_phs_comp": "mg",
"combined_phs_comp": "mg",
"pt": "psig",
"t": "°F",
"enthalpy": "J",
"density": "g/m3",
"mass": "g",
"vol": "L"
}
}
}
2. Send the Calculation Request:
With the file ID, send a POST request to the API’s isothermal flash calculation endpoint along with the prepared JSON input. This returns a response containing a resultsLink
, among other details:
{
"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"
}
3. Poll for Results:
Regularly poll the resultsLink
endpoint until the calculation's status changes from "IN QUEUE" or "IN PROGRESS" to "PROCESSED", "FAILED", or "ERROR". Once the "PROCESSED" status is reached, the results will be available in JSON format.
-
Poll for Results:
- IN QUEUE / IN PROGRESS: Continue polling the endpoint as the calculation is still being processed.
-
PROCESSED: The results are complete and can be found in
data.result
of the response. -
FAILED: Indicates a computation failure; details will be in
data.error
. - ERROR: A system error occurred, requiring further investigation or support intervention.
Example of a PROCESSED Status Response:
{
"code": 200,
"data": {
"result": {
...
}
},
"message": "Results returned successfully",
"status": "PROCESSED"
}
A successful isothermal flash calculation will return a JSON payload that resembles the following structure:
{
"data": {
"metaData": {
"executionTime": {
"unit": "ms",
"value": 5231.0
},
"totalTime": {
"unit": "ms",
"value": 0.0
},
"versionInfo": {
"fullVersion": "11.5.1.9"
}
},
"result": {
"additionalProperties": {
"prescalingTendencies": "..."
},
"phaseSummary": "...",
"phases": "...",
"total": {
"molecularConcentration": "...",
"properties": "...",
"totalMolecularMoles": "...",
"totalTrueMoles": "...",
"trueConcentration": "..."
}
}
},
"message": "Results returned successfully",
"status": "PROCESSED"
}
By following these steps, you will be able to perform isothermal flash calculations. If you have any questions or need the Python starter kit for EngineAPI, please contact OLI Customer Support.