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

POST https://api.olisystems.com/channel/dbs

Run .dbs file generation

Headers

Name	Type	Description
Authorization*	String	Bearer {{access_token}}
Content-Type*	String	application/json

200: OK

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

JSON Request Payload Format:

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

Field description

params	required	type	description
thermodynamicFramework	✔️	String	OLI Thermodynamic Framework. Options: Aqueous (H+ ion) MSE-SRK (H3O+ ion) MSE (H3O+ ion)
privateDatabanks	❌	Array of String	Array of Private Data Bank Codes. e.g. ["COR","CER"]
modelName	✔️	String	Name of the Generated DBS File in OLI Cloud.
phases	✔️	Array of String	Array of Strings Defining Included Phases: "liquid1" "solid" "vapor" "liquid2"
inflows	✔️	Array of Object	The Array of JSON Objects Containing Valid Species Identities: {"name": "CO2"} {"name": "HSION"}

The 'liquid1' phase must always be included in the 'phases' array.

Example Program Demonstrating DBS Generation Process

Incorporate the following example in conjunction with the OLIAPI class provided in the Quickstart example.

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)

{
    "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.

A chemistry model file can be reused in calculations as long as the chemistry remains unchanged.

Delete Chemistry File

You can delete your DBS files by providing the file ID. For more information, please refer to the 'delete-file' documentation.