Articles in this section

Getting Started with OLI Engine API

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.

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