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

NameTypeDescription

Authorization*

String

Bearer {{access_token}}

Content-Type*

String

application/json

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

paramsrequiredtypedescription

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.

Last updated