ThermoFun

https://thermohub.org/thermofun/
Admin
ThermoFun is an open-source C++ and Python library for calculating thermodynamic properties of...
Tokens:6,196
Snippets:31
Trust Score:5.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### C++ example: batch calculations and CSV export

Source: https://thermohub.org/thermofun/thermofun

Uses the ThermoFun::Batch class to load a dataset, set temperature and pressure increments, calculate properties for multiple substances, and write results to a CSV file.

```cpp
#include "Thermofun/ThermoFun.h"
using namespace std;

int main()
{
    ThermoFun::Batch batch("aq17-thermofun.json");

    batch.setPropertiesUnits({"temperature", "pressure"},{"degC","bar"});
    batch.setTemperatureIncrement(0, 200, 25);
    batch.setPressureIncrement(100, 1000, 50);

    batch.thermoPropertiesSubstance({"Al+3", "OH-", "SiO2@"},
                                    {"gibbs_energy","entropy", "volume", "enthalpy"},
                                   ).toCSV("results.csv");
    return 0;
}
```

--------------------------------

### Python example: calculate substance and reaction properties

Source: https://thermohub.org/thermofun/thermofun

Initializes a ThermoEngine with a JSON dataset, calculates thermodynamic properties for a substance at 473 K and 2000e5 Pa, and for a reaction at 298.15 K and 1e5 Pa. Access properties like gibbs_energy, entropy, and log_equilibrium_constant.

```python
import thermofun as fun

engine = fun.ThermoEngine('slop98-thermofun.json')

substance_properties = engine.thermoPropertiesSubstance(473, 2000e5, "Ca+2")

G = properties.gibbs_energy.val
A = properties.helmholtz_energy.val
U = properties.internal_energy.val
H = properties.enthalpy.val
S = properties.entropy.val
V = properties.volume.val
Cp= properties.heat_capacity_cp.val

reaction_properties = engine.thermoPropertiesReaction(298.15, 1e5, "Cal = Ca+2 + CO3-2")

logK = reaction_properties.log_equilibrium_constant.val
Gr = reaction_properties.reaction_gibbs_energy.val
Ar = reaction_properties.reaction_helmholtz_energy.val
Ur = reaction_properties.reaction_internal_energy.val
Hr = reaction_properties.reaction_enthalpy.val
Sr = reaction_properties.reaction_entropy.val
Vr = reaction_properties.reaction_volume.val
Cpr= reaction_properties.reaction_heat_capacity_cp.val
```

--------------------------------

### Install ThermoFun with conda

Source: https://thermohub.org/thermofun/thermofun

Install the ThermoFun library on Windows, Mac, or Linux using Conda/Miniconda from the conda-forge channel.

```bash
conda install -c conda-forge thermofun
```

--------------------------------

### Compute reaction properties with ThermoFun Engine

Source: https://thermohub.org/thermofun/interface

Compute thermodynamic properties of a reaction using the ThermoFun Engine. The example shows how to obtain the log equilibrium constant and the reaction Gibbs energy for the given reaction at specified temperature and pressure.

```cpp
reaction_properties = engine.thermoPropertiesReaction(298.15, 1e5, "Cal = Ca+2 + CO3-2");
logK = reaction_properties.log_equilibrium_constant.val;
drG0 = reaction_properties.reaction_gibbs_energy.val;

```

--------------------------------

### Compute substance properties with ThermoFun Engine

Source: https://thermohub.org/thermofun/interface

Create a ThermoFun Engine object using a JSON database file and compute thermodynamic properties of a substance (Al+3) at given temperature and pressure. The example shows how to extract the Gibbs energy value, its derivative with respect to temperature, and the propagated error.

```cpp
#include "Thermofun/ThermoFun.h"
using namespace std;

int main()
{
  // Create the engine object using a database file in JSON format
  // Examples of such files can be found in /Resources/databases/ folder or can be
  // retrieved from ThermoHub database using ThermoHubClient
  ThermoFun::Engine engine("aq17-thermofun.json");

  double T       = 398.15; double P = 1e7; // in K and Pa

  auto propAl    = engine.thermoPropertiesSubstance(T, P, "Al+3");

  // extracting values from results for the Gibbs energy
  double G0      = propAl.gibbs_energy.val; // value
  double G0dT    = propAl.gibbs_energy.ddt; // derivative with T = -S0
  double G0error = propAl.gibbs_energy.err; // propagated error

  return 0;
}

```

--------------------------------

### Retrieve ThermoHub database and run batch calculations

Source: https://thermohub.org/thermofun/interface

Connects to ThermoHub, saves a database as a JSON file, initializes a ThermoFun::Batch object, sets preferences, units, and digits, then calculates reaction properties for multiple T-P pairs and writes results to CSV files.

```C++
#include "Thermofun/ThermoFun.h"
#include "ThermoHubClient/ThermoHubClient.h"
using namespace std;

int main()
{
    // database connection  (local or remote) using a configuration file
    // ThermoHubClient::DatabaseClient dbc("hub-connection-config.json");

    // default connection (remote) to db.thermohub.net
    ThermoHubClient::DatabaseClient dbc;

    // retrieve a database from ThermoHub server as a JSON file
    dbc.saveDatabase("psinagra-12-07") // this will save the database file psinagra-12-07-thermofun.json

    // Initialize an batch object using the database file
    ThermoFun::Batch batch("psinagra-12-07-thermofun.json");

    // Optional: set the solvent symbol used for calculating properties of aqueous species
    batch.setSolventSymbol("H2O@");

    // Optional set calculation and output preferences
    ThermoFun::BatchPreferences op;
    op.isFixed = true;
    op.reactionPropertiesFromReactants   = false;
    op.substancePropertiesFromReaction   = false;
    batch.setBatchPreferences(op);

    // Optional set units and significant digits
    batch.setPropertiesUnits({"temperature", "pressure"},{"degC","bar"});
    batch.setPropertiesDigits({ "reaction_gibbs_energy","reaction_entropy", "reaction_volume",
                                "reaction_enthalpy","logKr", "temperature", "pressure"}, {0, 4, 4, 4, 4, 0, 0});

    batch.thermoPropertiesReaction({{25,1}}, {"AmSO4+", "MgSiO3@"}, {"reaction_gibbs_energy", "reaction_entropy",
                                    "reaction_volume", "reaction_enthalpy", "logKr"}).toCSV("results.csv");

    batch.thermoPropertiesReaction({0,20,50,75},{0,0,0,0},{"AmSO4+", "MgSiO3@"}, {"reaction_gibbs_energy", "reaction_entropy",
                                    "reaction_volume", "reaction_enthalpy", "logKr"}).toCSV("results.csv");
}

```

--------------------------------

### Create and use ThermoFun Batch object

Source: https://thermohub.org/thermofun/interface

Initializes a ThermoFun::Batch object from a JSON database file, sets optional solvent symbol, units, and digits, then retrieves thermodynamic properties for a substance and writes results to a CSV file.

```C++
#include "Thermofun/ThermoFun.h"
using namespace std;

int main()
{
    // Create the batch object using a database file in JSON
    ThermoFun::Batch batch("aq17.json");

    // Optional: set the solvent symbol used for calculating properties of aqueous species
    batch.setSolventSymbol("H2O@");

    // Optional: change default units
    batch.setPropertiesUnits({"temperature", "pressure"},{"degC","bar"});

    // Optional: change default digits
    batch.setPropertiesDigits({"gibbs_energy","entropy", "volume", "enthalpy", "temperature", "pressure"}, {0, 1, 2, 0, 0, 0});

    // Retrieve the entropy of H2O
    double H2Oentropy = batch.thermoPropertiesSubstance( 300, 2000, "H2O@", "entropy").toDouble();

    // Retrieve the derivative of G with respect to T
    double H2OdGdT = batch.thermoPropertiesSubstance( 300, 2000, "H2O", "entropy").toThermoScalar().ddt;

    // Write results to a comma separate files for a list of T-P pairs, substances, and properties
    batch.thermoPropertiesSubstance({{25, 1},{40, 1},{70, 100},{90, 100},{100, 100}}, // list of T-P pairs
                                    {"Al+3", "OH-", "SiO2@"},                         // list of substance symbols
                                    {"gibbs_energy","entropy", "volume", "enthalpy"}  // list of properties
                                  ).toCSV("results.csv");                            // output
    return 0;
}

```

--------------------------------

### Python interface: ThermoFun ThermoBatch with ThermoHubClient

Source: https://thermohub.org/thermofun/interface

Shows the Python interface for ThermoFun and ThermoHubClient. It initializes a database client, retrieves the cemdata18 database, creates a ThermoBatch, sets optional preferences, units, and significant digits, then calculates substance properties and writes them to CSV. The final lines compute reaction properties and print the logK value, but note the code uses 'engine' without importing it, which would cause a NameError.

```python
import ThermoHubClient as client
Import ThermoFun as fun

print("\n# Initialize a database client object\n")
dbc = client.DatabaseClient()

print("\n# Retrieve a JSON database given a ThermoDataSet symbol\n")
db = dbc.getDatabase("cemdata18")

print("\n# Initialize an interface object using the database\n")
batch = fun.ThermoBatch(db)

print("\n# Optional: set the solvent symbol used for calculating properties of aqueous species\n")
batch.setSolventSymbol("H2O@")

print("\n# Optional set calculation and output preferences\n")
op = fun.BatchPreferences()
op.isFixed = True
op.reactionPropertiesFromReactants   = False
op.substancePropertiesFromReaction   = False
batch.setBatchPreferences(op)

print("\n# Optional set units and significant digits\n")
batch.setPropertiesUnits(["temperature", "pressure"],["degC","bar"])

batch.setPropertiesDigits(["gibbs_energy","entropy", "volume",
                            "enthalpy","logKr", "temperature", "pressure"], [0, 4, 4, 4, 4, 0, 0])

print("\n# Do calculations and write output\n")
batch.thermoPropertiesSubstance([[25,1]], ["Na(CO3)-", "Mg+2"], ["gibbs_energy", "entropy",
                                "volume", "enthalpy"]).toCSV("results_dbc.csv")

reaction_properties = engine.thermoPropertiesReaction(298.15, 1e5, "Cal = Ca+2 + CO3-2")
logK = reaction_properties.log_equilibrium_constant
f'logK (Cal = Ca+2 + CO3-2) is {logK.val}'
```

--------------------------------

### thermoPropertiesSubstance

Source: https://thermohub.org/thermofun/interface

Calculates thermodynamic properties of a substance at a given temperature and pressure. Returns an object with properties such as Gibbs energy, including value, derivatives, and error.

```APIDOC
## thermoPropertiesSubstance

### Description
Calculates thermodynamic properties of a substance at a given temperature and pressure. Returns an object with properties such as Gibbs energy, including value, derivatives, and error.

### Method
C++ function call

### Endpoint
`engine.thermoPropertiesSubstance(T, P, substance)`

### Parameters
- **T** (double) - Required - Temperature in Kelvin (K)
- **P** (double) - Required - Pressure in Pascal (Pa)
- **substance** (string) - Required - Substance identifier (e.g., "Al+3")

### Request Example
```cpp
#include "Thermofun/ThermoFun.h"
using namespace std;

int main()
{
  ThermoFun::Engine engine("aq17-thermofun.json");
  double T = 398.15; double P = 1e7; // in K and Pa
  auto propAl = engine.thermoPropertiesSubstance(T, P, "Al+3");
  return 0;
}
```

### Response
#### Success Response
- **gibbs_energy.val** (double) - Value of Gibbs energy
- **gibbs_energy.ddt** (double) - Derivative with respect to temperature (equals -S0)
- **gibbs_energy.err** (double) - Propagated error

#### Response Example
```cpp
double G0 = propAl.gibbs_energy.val;
double G0dT = propAl.gibbs_energy.ddt;
double G0error = propAl.gibbs_energy.err;
```
```

--------------------------------

### thermoPropertiesReaction

Source: https://thermohub.org/thermofun/interface

Calculates thermodynamic properties of a chemical reaction at a given temperature and pressure. Returns reaction properties including log equilibrium constant and reaction Gibbs energy.

```APIDOC
## thermoPropertiesReaction

### Description
Calculates thermodynamic properties of a chemical reaction at a given temperature and pressure. Returns reaction properties including log equilibrium constant and reaction Gibbs energy.

### Method
C++ function call (also available in Python via Pybind11)

### Endpoint
`engine.thermoPropertiesReaction(T, P, reaction)`

### Parameters
- **T** (double) - Required - Temperature in Kelvin (K)
- **P** (double) - Required - Pressure in Pascal (Pa)
- **reaction** (string) - Required - Chemical reaction equation (e.g., "Cal = Ca+2 + CO3-2")

### Request Example
```cpp
reaction_properties = engine.thermoPropertiesReaction(298.15, 1e5, "Cal = Ca+2 + CO3-2");
```

### Response
#### Success Response
- **log_equilibrium_constant.val** (double) - Logarithm of the equilibrium constant
- **reaction_gibbs_energy.val** (double) - Gibbs energy of reaction

#### Response Example
```cpp
logK = reaction_properties.log_equilibrium_constant.val;
drG0 = reaction_properties.reaction_gibbs_energy.val;
```
```
Tokens:
Raw