💧
OLI API
  • Welcome to the OLI API documentation
  • Basic workflow
  • Authentication
    • Bearer Token
    • API Keys
      • Generate a Key
      • List All Keys
      • Delete a Key
  • Generating chemistry model files
    • ChemBuilder API
      • Getting Started with ChemBuilder
        • Set Thermodynamic Framework
        • Include Private Databanks
        • Include Inflows
          • Include Assays
          • Include Pseudocomponent
        • Choose Phases
        • Specify Model Name
        • Choose Redox
        • Choose Solids
        • Add Kinetics
      • ChemBuilder Query
        • Species Query
        • Redox Query
        • Solid Phase Query
        • Databank Query
        • Kinetics Query
        • Query Output Results
      • Supporting Information for ChemBuilder
        • Add Comment
        • "enabled" Keyword
        • ChemBuilder Errors
    • Chemistry Wizard
  • Uploading chemistry model files
  • Get list of uploaded files
  • Quickstart example: Python
  • Known issues and Limitations
  • OLI ENGINE API
    • Main methods
      • API call blueprint
      • Chemistry information
      • Isothermal flash
      • Isenthalpic flash
      • Bubble point flash
      • Dew point flash
      • Vapor amount flash
      • Vapor fraction flash
      • Isochoric flash
      • set pH flash
      • Precipitation point flash
      • Autoclave
      • Custom flash
      • Corrosion contact surfaces
      • Corrosion rates
      • Water analysis
  • Additional methods
    • Flash history - Chemistry model
    • Result - by jobId
    • delete file
    • cancel run
  • Inflows input
  • Optional inputs
  • Kinetic calculation inputs
  • Kinetic calculation outputs
  • Input units
  • User defined output unit set
  • Survey calculation
  • Stream output
  • Error/Warning output
  • Definition of terms
  • OLI Process API
    • Uploading a Process API package
      • Creating a Process API package
    • Get list of all uploaded ProcessAPI packages
    • Get input specs for Process API package
    • Get output specs for ProcessAPI package
    • Run a Process API calculation
    • Get calculation status and results
  • Deleting a process package
  • Undelete a process package
  • Process API input specification
    • "data" object
      • "flowsheet" object
        • "chemical-info" object
        • "general-info" object
        • "properties" object
        • "units_set_info" object
  • OLI ScaleChem API
    • Uploading chemistry model files for ScaleChem API
    • Get list of uploaded ScaleChem model files
    • Main methods
      • Brine analysis
      • Gas analysis
      • Oil analysis
      • Mixer calculation
      • Scale scenario
Powered by GitBook
On this page
  • The "metaData" field
  • The "result" field

Was this helpful?

  1. Generating chemistry model files
  2. ChemBuilder API
  3. ChemBuilder Query

Query Output Results

This page offers an overview of the output file generated by a query method. A typical output from the query method includes "data" and "result" sections if no errors occur during execution. The "data" and "result" sections contain the following information:

{
    "data": {
        "metaData": {
            "executionTime": {
                "unit": "ms",
                "value": 344.0
            }
        },
        "result": {  
            // Either one of the type will be shown below
            // Type 1: species query
            "species": [
                { 
                    // species information
                } 
            ]
            // Type 2: Databank query 
            "publicDataBankInfo": [ 
                {
                } 
            ], 
            "privateDataBankInfo": [
                {
                }
            ]          
            // Type 3: redox query 
            "redox": { 
                // redox selection 
            }
            // Type 4: kinetics query
            "species": [
                // species name 
                // species phases
            ],
            "equilibriumReactions": [
                // equilibruim reactions
             ]         
        }
     }, 
    "message": "Chemistry generated successfully",
    "status": "SUCCESS"       
} 

The "metaData" field

This section contains metadata, which provides runtime system information. Currently, the version number of the running software is included in the "metaData".

The "result" field

This section presents all the contents produced by query methods.

This method will return both the public and private databank information to users.

    "publicDataBankInfo": [
            {
                "code": "MSE",
                "fullName": "MSE (H3O+ ion)",
                "framework": "H3OION",
                "description": "",
                "versions": {
                    "major": 11,
                    "minor": 0,
                    "revision": 1
                }
            }
        ],
        "privateDataBankInfo": [
            {
                "code": "AMI",
                "fullName": "AMINEHCL Databank",
                "framework": "H3OION",
                "description": "",
                "versions": {
                    "major": 9,
                    "minor": 2,
                    "revision": 1
                    }
            },
            {
                "code": "XSC",
                "fullName": "Surface Complexation Double Layer Model (MSE)",
                "framework": "H3OION",
                "description": "",
                "versions": {
                    "major": 11,
                    "minor": 0,
                    "revision": 1
                    }
            }
        ]

result
always shown
type

publicDataBankInfo

Array of JSON Object

privateDataBankInfo

Array of JSON Object

The keyword "code" in "privateDataBankInfo" can be used as an input in "privateDatabank", which is an array of strings.

Both public and private databanks contain information in an identical format.

This method will return every species in the databank used in the query.

        "species": [
            {
                "baseTag": "ABIETICAC",
                "synonyms": [
                    "Abietic acid",
                    "1-Phenanthrenecarboxylic acid, 1,2,3,4,4a,4b,5,6,10,10a-decahydro-1,4a-dime",
                    "7,13-Abietadien-18-oic acid",
                    "l-Abietic acid",
                    "Podocarpa-7,13-dien-15-oic acid, 13-isopropyl-",
                    "Sylvic acid",
                    "13-Isopropylpodocarpa-7,13-dien-15-oic acid"
                ],
                "chemicalFormula": "C20H30O2",
                "IUPAC": "Abietic acid",
                "CASNO": "514-10-3"
            },
            {
                "baseTag": "ACENAPHTHN",
                "synonyms": [
                    "Naphthyleneethylene",
                    "Periethylenenaphthalene",
                    "1,2-Dihydroacenaphthylene",
                    "Acenaphthylene, 1,2-dihydro-",
                    "1,8-Ethylenenaphthalene",
                    "Acenaphthene"
                ],
                "chemicalFormula": "C12H10",
                "IUPAC": "1,8-Ethylenenaphthalene",
                "CASNO": "83-32-9"
            },
            {
                "baseTag": "ZRSO42.1H2O",
                "synonyms": [
                    "Zirconium sulfate monohydrate"
                ],
                "chemicalFormula": "ZrSO42.1H2O",
                "IUPAC": "Zirconium sulfate monohydrate",
                "CASNO": ""
            },
            {
                "baseTag": "ZRSO42.4H2O",
                "synonyms": [
                    "Zirconium sulfate tetrahydrate"
                ],
                "chemicalFormula": "Zr(SO4)2.4H2O",
                "IUPAC": "Zirconium sulfate tetrahydrate",
                "CASNO": ""
            }
        ]

Each element of "species" is a JSON object that contains a variety of valid representations of a species used by OLI software.

species info
always shown
type
inflow ready

baseTag

String

synonyms

String

chemicalFormula

String

IUPAC

String

CASNO

String

The fourth column in the table, "Inflow Ready", indicates if this output section can be directly used with the subsequent calculations input, i.e., the inflow section of the Chemistry Builder input JSON file.

"synonyms" and "CASNO" can be empty in the output.

This method displays all available valence states for the elements of species in the inflow. By default, valence states of Iron (Fe) are enabled, while all valence states of Chlorine (Cl) are disabled.

        "redox": {
            "enabled": false,
            "subSystems": [
                {
                    "name": "Chlorine",
                    "enabled": false,
                    "valenceStates": [
                        {
                            "name": "Cl(-1)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+1)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+3)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+5)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+7)",
                            "enabled": false
                        },
                        {
                            "name": "Cl(+4)",
                            "enabled": false
                        }
                    ]
                },
                {
                    "name": "Iron",
                    "enabled": true,
                    "valenceStates": [
                        {
                            "name": "Fe(0)",
                            "enabled": true
                        },
                        {
                            "name": "Fe(+2)",
                            "enabled": true
                        },
                        {
                            "name": "Fe(+3)",
                            "enabled": true
                        },
                        {
                            "name": "Fe(+6)",
                            "enabled": true
                        }
                    ]
                }
            ]
        }

The JSON object "redox" can be directly inserted into an input JSON file to enable or disable redox for .dbs file generation.

This method displays all available solid phases given the inflow species and selections of phases.


        "includedSolids": {
            "enabled": true,
            "solids": [
                "FECL3",
                "FECL3.2.5H2O",
                "FECL3.2H2O",
                "FECL3.6H2O",
                "FEIII2O3",
                "FEIIIOH3",
                "FEOOH",
                "NACL",
                "NAFEO2",
                "NAOH",
                "NAOH.1H2O"
            ]
        }

The JSON object "includedSolids" can be directly inserted into the input JSON file to enable the solid phase of a particular species.

The "Solids" accessed by this query method include "solid", "hydrate", and "surface species".

This method presents all equilibrium reactions available based on users' selections of inflow species, phases, redox, and solid phases.

        "species": [
            {
                "trueName": "H2O",
                "phase": "liquid"
            },
            {
                "trueName": "FECL3AQ",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOH3AQ",
                "phase": "liquid"
            },
            {
                "trueName": "H2AQ",
                "phase": "liquid"
            },
            {
                "trueName": "HCLAQ",
                "phase": "liquid"
            },
            {
                "trueName": "O2AQ",
                "phase": "liquid"
            },
            {
                "trueName": "CLION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIII2OH2ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIICL2ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIICL4ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIICLION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOH2ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOH4ION",
                "phase": "liquid"
            },
            {
                "trueName": "FEIIIOHION",
                "phase": "liquid"
            },
            {
                "trueName": "HION",
                "phase": "liquid"
            },
            {
                "trueName": "NAION",
                "phase": "liquid"
            },
            {
                "trueName": "OHION",
                "phase": "liquid"
            },
            {
                "trueName": "FECL3PPT",
                "phase": "solid"
            },
            {
                "trueName": "FECL3.2.5H2O",
                "phase": "solid"
            },
            {
                "trueName": "FECL3.2H2O",
                "phase": "solid"
            },
            {
                "trueName": "FECL3.6H2O",
                "phase": "solid"
            },
            {
                "trueName": "FEIII2O3PPT",
                "phase": "solid"
            },
            {
                "trueName": "FEIIIOH3PPT",
                "phase": "solid"
            },
            {
                "trueName": "FEOOHPPT",
                "phase": "solid"
            },
            {
                "trueName": "NACLPPT",
                "phase": "solid"
            },
            {
                "trueName": "NAFEO2PPT",
                "phase": "solid"
            },
            {
                "trueName": "NAOHPPT",
                "phase": "solid"
            },
            {
                "trueName": "NAOH.1H2O",
                "phase": "solid"
            },
            {
                "trueName": "H2OVAP",
                "phase": "vapor"
            },
            {
                "trueName": "H2VAP",
                "phase": "vapor"
            },
            {
                "trueName": "HCLVAP",
                "phase": "vapor"
            },
            {
                "trueName": "O2VAP",
                "phase": "vapor"
            }
        ],
        "equilibriumReactions": [
            "FECL3.2.5H2O=FEIIIION+3CLION+2.5H2O",
            "FECL3.2H2O=FEIIIION+3CLION+2H2O",
            "FECL3.6H2O=FEIIIION+3CLION+6H2O",
            "FECL3AQ=FEIIICL2ION+CLION",
            "FECL3PPT=FEIIIION+3CLION",
            "FEIII2O3PPT+6HION=2FEIIIION+3H2O",
            "FEIII2OH2ION=2FEIIIION+2OHION",
            "FEIIICL2ION=FEIIICLION+CLION",
            "FEIIICL4ION=FECL3AQ+CLION",
            "FEIIICLION=FEIIIION+CLION",
            "FEIIIOH2ION=FEIIIOHION+OHION",
            "FEIIIOH3AQ=FEIIIOH2ION+OHION",
            "FEIIIOH3PPT=FEIIIION+3OHION",
            "FEIIIOH4ION=FEIIIOH3AQ+OHION",
            "FEIIIOHION=FEIIIION+OHION",
            "FEOOHPPT+H2O=FEIIIION+3OHION",
            "H2O=HION+OHION",
            "H2OVAP=H2O",
            "H2VAP=H2AQ",
            "HCLAQ=HION+CLION",
            "HCLVAP=HCLAQ",
            "NACLPPT=NAION+CLION",
            "NAFEO2PPT+2H2O=NAION+FEIIIION+4OHION",
            "NAOH.1H2O=NAION+OHION+H2O",
            "NAOHPPT=NAION+OHION",
            "O2VAP=O2AQ"
        ]

The output consists of two sections. The first section includes all species participating in equilibrium reactions. Each participating species has its true name and phase status. Internally, "trueName" is used by the engine and contains a suffix indicating its phase. The second section includes all equilibrium equations to be considered. These generated equations use the true name of species.

The "liquid" phase for a species could apply to either aqueous or organic phase.

PreviousKinetics QueryNextSupporting Information for ChemBuilder

Last updated 11 months ago

Was this helpful?

If each element in the "subSystems" is enabled, then all of its valence states in "valenceStates" will be enabled by default. You can also refer to "" section for more details.

Redox Example 5
✔️
✔️
✔️
✔️
✔️
❌
✔️
❌
✔️
❌
✔️
❌