General Information

Attention

Windows and Mac users may find it helpful to first read the Getting Started guides for scripting: scripting with Windows | scripting with MacOS

It is recommended to use the version of python that is shipped with AMS. This version ensures that all the necessary libraries (e.g., PLAMS) are properly imported and are mutually compatible. The best way to do this is to run the amspython program. That can be executed from the command line as follows:

$AMSBIN/amspython <your_program.py>

Furthermore, interactive usage of the amsipython program can be beneficial. To do so, execute the following command in your terminal:

$AMSBIN/amsipython     # in terminal

run <your_program.py>  # in interactive python

where <your_program.py> should of course be replaced by the name of your program.

Overview

The pyCRS Python library offers a convenient wrapper for various thermodynamic calculations, providing the following utilities:

Modules	API	Description
Database	API	Provides an interface to a SQL database for managing COSKF files with conformers.
CRSManager	API	It’s a python wrapper based on PLAMS library for facilitating the COSMO-RS calculation. It is designed to be used in conjunction with Database.
PropPred	API	Predicts physical properties based on QSPR descriptors derived from SMILES.
FastSigma	API	Predicts sigma profiles based on QSPR descriptors derived from SMILES.

Future releases will incorporate more functionality.

In addition to introducing the Database and CRSManager in the following section, the examples section contains various template scripts and helpful examples. Exploring the example section is one of the simplest ways to get started with the module.

Database

Introduction

The sql database contains the following tables.

Table name	Description
Compound	contains unique compounds along with their COSKF file based on either CAS number or any preferred identifier
Conformer	contains multiple conformers along with their COSKF file
PhysicalProperty	contains the physical properties input by user
PropPred	contains the estimated physical properties using QSPR methods based on SMILES

These tables can be visualized using open-source tools like DB Browser or accessed directly through methods within the COSKFDatabase class.

Attention

This module currently does not support charged species, polymers, or multiple-species with dissociation and association. While it’s feasible to add these compounds to the database, it’s worth noting that the SMILES generated from the coordinates using OpenBabel might be inaccurate. Additionally, the PropPred tool should not be utilized for charged species and polymers.

Note

Currently, the .coskf files themselves are stored as raw .coskf files in a directory called SCM_PYCRS_COSKF_DB, which will be created in the parent directory of the path variable. This database will not be overwritten or deleted by this COSKFDatabase class. This directory exists for the convenience of the user, but it is best to access all files via the API below as the exact format of the database may evolve over time.

Basic Usage

In this brief example, we’ll demonstrate how to interact with the database. This includes adding a compound, searching for a compound, specifying experimental physical properties, and utilizing PropPred to estimate physical properties.

There are a few important points to note when using the add_compound method:

1. If the coskf_path parameter is not provided by the user, the method will attempt to locate the ADFCRS-2018 database path if it’s available. Please ensure to install the ADFCRS-2018 database via amspackages (SCM->Packages) before running the below script.

2. If the cas parameter is not provided by the user, the method will attempt to use the value stored in the ‘Compound Data’ section within the .coskf file if it’s available.

3. If the name parameter is not provided by the user, the method will prioritize using the IUPAC name, CAS number, identifier, or the name of the .coskf file. The IUPAC name will be attempted to be retrieved from the ‘Compound Data’ section within the .coskf file.

from pyCRS.Database import COSKFDatabase

#Please ensure to install the ADFCRS-2018 database via amspackages (SCM->Packages) before running the below script  #

db = COSKFDatabase("my_coskf_db.db")
db.add_compound("Water.coskf", name="Water", cas="7732-18-5")
db.add_compound("Methanol.coskf")
db.add_compound("Ethanol.coskf")
db.add_compound("Benzene.coskf")
db.add_compound("Ibuprofen.coskf")

rows = db.get_compounds(["7732-18-5","Ibuprofen"])
for r in rows:
    print(r)

db.add_physical_property("Ibuprofen","meltingpoint",347.6)
db.add_physical_property("Ibuprofen","hfusion",27.94,unit="kJ/mol")
db.estimate_physical_property("Ibuprofen")

EXP = db.get_physical_properties("Ibuprofen")[0]
QSPR = db.get_physical_properties("Ibuprofen",source="PropPred")[0]

print("experimental value = ", EXP.hfusion, " estimated value = ",QSPR.hfusion)

The output produced is the following:

CompoundRow(compound_id=1, conformer_id=1, name='water', cas='7732-18-5', identifier=None, smiles='O', resolved_smiles='O', coskf='Water_1.coskf', Egas=-323.935, Ecosmo=-330.386, nring=0)
CompoundRow(compound_id=4, conformer_id=4, name='ibuprofen', cas='15687-27-1', identifier=None, smiles='CC(Cc1ccc(cc1)[C@@H](C(=O)O)C)C', resolved_smiles='CC(Cc1ccc(cc1)[C@@H](C(=O)O)C)C', coskf='Ibuprofen_1.coskf', Egas=-4486.784, Ecosmo=-4494.859, nring=6)
experimental value =  6.678  estimated value =  5.744

Adding multiple conformers

When adding multiple conformers (i.e. multiple COSKF files) of a compound to the database using add_compound method, three confirmation steps are attempted:

1. Initially, the set of conformers in the database is retrieved by matching the CAS numner or identifier. If it’s not found the compound will be added to the database as a new compound.

2. Subsequently, it attempts to generate the canonical SMILES from its coordinates to confirm that the compound matches the one in the database. If this resolution fails, one can bypass this check by setting ignore_smiles_check=True.

3. Lastly, it conducts duplicate recognition using UniqueConformersCrest in AMSConformer tool to ensure that it’s not a duplicate in the database. If this recognition fails, one can skip this step by setting ignore_duplicates=True.

By default, the conformer with the lowest gas phase bond energy is stored in the COMPOUND TABLE. However, a specific conformer can be chosen using its conformer ID through the update_compound_by_conformer_id method.

For detailed information on these methods, please refer to the Database API documentation.

CRSManager

Introduction

The module provides a user-friendly approach for configuring standard crsJob setups via Python scripting.

For instance, here is an example how we set up the solid solubility calculation using CRSManager once the database has been set up in advance. This approach provides a more convenient method for conducting high-throughput calculations without the need for specific handling, such as solubility screening.

Python code using pyCRS

[show/hide code]

from pyCRS.CRSManager import CRSSystem
System = CRSSystem()
mixture = {}
mixture["Water"] = 1.0
mixture["Ibuprofen"] = 0
System.add_Mixture( mixture,
                    database="my_coskf_db.db",
                    temperature=298.15,
                    problem_type="solubility",
                    solute="solid")
print(System.get_input(0))

Alternatively, the same calculation can be set up through PLAMS, as demonstrated below. This approach requires users to input correct settings but provides greater flexibility in managing complex workflows. For example, the advanced scripting example section demonstrates various tasks, such as eutectic and ionic liquid calculations, and more.

Python code using PLAMS

[show/hide code]

from scm.plams import Settings, init, finish, CRSJob
import os

########  Note: Please ensure to install the ADFCRS-2018 database via amspackages (SCM->Packages) before running the below script  ########

coskf_path = os.path.join(os.environ["SCM_PKG_ADFCRSDIR"] , "ADFCRS-2018")

settings = Settings()
settings.input.property._h = "SOLUBILITY"
settings.input.method = "COSMORS"

num_compounds = 2
compounds = [Settings() for i in range(num_compounds)]
compounds[0]._h = os.path.join(coskf_path, "Water.coskf" )
compounds[0].frac1 = 1.0
compounds[1]._h = os.path.join(coskf_path, "Ibuprofen.coskf" )
compounds[1].frac1 = 0.0
compounds[1].nring = 6
compounds[1].hfusion = 27.94/4.184
compounds[1].meltingpoint = 347.6

settings.input.temperature = 298.15

# specify the compounds as the compounds to be used in the calculation
settings.input.compound = compounds
# create a job that can be run by COSMO-RS
my_job = CRSJob(settings=settings)
print(my_job.get_input())

Attention

This module currently does not support charged species, polymers, or multiple-species with dissociation and association.

Basic Usage

In this example, we’ll create a database containing ethanol and benzene from the ADFCRS-2018 database. Then, we’ll instantiate a CRSSystem and generate several CRSMixture instances using the add_Mixture method. After executing the calculation with the runCRSJob method, the corresponding CRSResults instances will be generated and stored in the outputs attribute. Finally, we can retrieve the .crskf file and the activity coefficient using methods provided by CRSResults.

[show/hide code]

from scm.plams import Settings, init, finish, CRSJob, config
from pyCRS.CRSManager import CRSSystem
from pyCRS.Database import COSKFDatabase
import numpy as np
import os, sys

init()
config.log.stdout = 0  # suppress plams output default=3

#create a database containing ethanol and benzene. please ensure install the ADFCRS-2018 database first via amspackages (SCM -> Packages)
db = COSKFDatabase("my_coskf_db.db")
db.add_compound("Ethanol.coskf")
db.add_compound("Benzene.coskf",cas="71-43-2")

#create a CRSSystem instance
System = CRSSystem()

#generate several CRSMixture instance
for i, x in enumerate(np.linspace(0, 1, 11)):
    mixture = {}
    mixture["ethanol"] = x
    mixture["71-43-2"] = 1-x
    System.add_Mixture(mixture,database="my_coskf_db.db",temperature=298.15,problem_type="ACTIVITYCOEF",method="COSMORS")

#print out the first calculation setting in the CRSSystem class
#print(System.get_input(0))

#execution calculation for all CRSMixture
System.runCRSJob()

gamma_ethanol = []
gamma_benzene = []
#retrieve result using methods provided by CRSResults
for out in System.outputs:
    crskf = out.kfpath()
    res = out.get_results()
    gamma_ethanol.append(res["gamma"][0][0])
    gamma_benzene.append(res["gamma"][1][0])

print(f"the last crskf file = {os.path.basename(crskf)}")
print(f"activity coefficient of ethanol = {gamma_ethanol}")
print(f"activity coefficient of benzene = {gamma_benzene}")


finish()

This generates the following output:

the last crskf file = crsJob_10.crskf
activity coefficient of ethanol = [41.59625151549539, 3.539543443573337, 2.234237060852824, 1.712495443157569, 1.4321494593043322, 1.2612087014707123, 1.1507589807729406, 1.0784886266786704, 1.0329501218595156, 1.0079137778145097, 1.0]
activity coefficient of benzene = [1.0, 1.0632078891234995, 1.1497425466225775, 1.2547602114699132, 1.3804970769948137, 1.5309168719748845, 1.7115353244885652, 1.9297200775482874, 2.1952374886461046, 2.521062652267439, 2.9247536001030006]

Additional Keywords

Additional keywords can be used in conjunction with certain problem types:

Keywords name	Description
vp_corr	When set to True, it attempts to use the vapor pressure of pure compounds to adjust the gas phase chemical potential, potentially increasing vapor pressures in a mixture. The default value is False.
density_corr	When set to True, it attempts to utilize the volume of a pure compound derived from its density instead of the cavity volume used in the COSMO calculation. The default value is False.
solute	This parameter allows you to specify ‘solid’, ‘gas’, or ‘liquid,’ applicable to SOLUBILITY and PURESOLUBILITY problem types. The default value is ‘solid’.
iso	This parameter offers the choice between ‘isotherm’, ‘isobar’ or ‘flashpoint’, applicable to BINMIXCOEF, TERNARYMIX, and COMPOSITIONLINE. The default value is ‘isotherm’.
additional_sett	This parameter provides the PLAMS approach to set up various parameters such as the VolumeQuotient in LOP, DensitySolvent in SOLUBILITY, Nfrac in BINMIXCOEF/TERNARYMIX/COMPOSITIONLINE, Nprofile/SigmaMax in SIGMAPROFILE/SIGMAPOTENTIAL.

For certain problem types, necessary physical properties are retrieved from the PhysicalProperty TABLE and PropPred TABLE in the database. The value from the PhysicalProperty TABLE is prioritized; if unavailable, the system attempts to use the value from the PropPred TABLE instead. Failure to obtain either value may result in calculation failure.

For instance, you can find the following examples.

# Solid solubility calculation
db.add_physical_property("Benzene","hfusion",2.37,unit="kcal/mol")
db.add_physical_property("Benzene","meltingpoint",278.7)
mixture = {}
mixture["Water"]   = 1
mixture["Benzene"] = 0
System.add_Mixture( mixture,
                    database="my_coskf_db.db",
                    temperature="273.15 373.15 10",
                    problem_type="SOLUBILITY",
                    solute="solid")

# Binary isobar VLE using the vapor pressure from PropPred
mixture = {}
mixture["methanol"] = 0.5
mixture["ethanol"] = 0.5
db.estimate_physical_property(["methanol","ethanol"])
additional_sett = Settings()
additional_sett.input.property.Nfrac = 10
System.add_Mixture( mixture,
                    database="my_coskf_db.db",
                    pressure=1.01325,
                    problem_type="BINMIXCOEF",
                    iso="isobar",
                    additional_sett=additional_sett,
                    vp_corr=True)

# Partition Coefficient for benzene/water
mixture = {}
mixture["benzene"] = [1, 0]  #[mole fraction in phase1, mole fraction in phase2]
mixture["water"]   = [0, 1]  #[mole fraction in phase1, mole fraction in phase2]
mixture["ethanol"] = [0, 0]  #[0, 0] for solute
additional_sett = Settings()
additional_sett.input.property.VolumeQuotient = 4.93
System.add_Mixture( mixture,
                    database="my_coskf_db.db",
                    problem_type="LOGP",
                    additional_sett=additional_sett)

# Sigma profile
mixture = {}
mixture["benzene"] = 1
additional_sett = Settings()
additional_sett.input.property.Nprofile = 100
additional_sett.input.property.SigmaMax = 0.05
System.add_Mixture( mixture,
                    database = "my_coskf_db.db",
                    problem_type="PURESIGMAPROFILE",
                    method="COSMORS",
                    additional_sett=additional_sett)

The available problem types is listed below.

problem_type value	Problem type
ACTIVITYCOEF	Activity Coefficient
BINMIXCOEF	Binary mixture LLE/VLE
TERNARYMIX	Ternary mixture LLE/VLE
COMPOSITIONLINE	Solvent composition line interpolation
SOLUBILITY	Solubility calculation in a mixed solvent
PURESOLUBILITY	Solubility calculation in a pure solvent
LOGP	Partition coefficient calculation
VAPORPRESSURE	Vapor pressure calculation for a mixed solvent
PUREVAPORPRESSURE	Vapor pressure calculation for a pure solvent
BOILINGPOINT	Boiling point calculation for a mixture
PUREBOILINGPOINT	Boiling point calculation for a pure solvent(s)
FLASHPOINT	Flashpoint calculation for a mixture
SIGMAPROFILE	Sigma profile calculation for a mixture
PURESIGMAPROFILE	Sigma profile calculation for a pure component(s)
SIGMAPOTENTIAL	Sigma potential calculation for a mixture
PURESIGMAPOTENTIAL	Sigma potential calculation for a pure component(s)

For detailed information on these methods, please refer to the CRSManager API documentation.