Database¶

The submodule contain several class for providing an interface to a sql database for managing COSKF files and physical properties.

class pyCRS.Database.COSKFDatabase(path: str)¶

A class provide an interface to a sql database containing the following tables.

Table name	Description
Compound	Unique compounds with COSKF files by CAS number or identifier.
Conformer	Multiple conformers with corresponding COSKF files.
PhysicalProperty	User-defined physical properties.
PropPred	Estimated properties using QSPR methods from SMILES.

Parameters:: path (str) – Path to the database file. Created if it doesn’t exist.

Example:

db = COSKFDatabase("my_coskf_db.db")
db.add_compound("Water.coskf")
db.add_compound("Benzene.coskf",cas="71-43-2")
db.add_physical_property("Benzene", "meltingpoint", 278.7)
db.add_physical_property("Benzene", "hfusion", 9.91, unit="kJ/mol")
db.estimate_physical_property("Benzene")

Adds a new .coskf file to the database.

Parameters:

coskf_file (str) – a path to the .coskf file, or alternatively, the file name of the .coskf file if the coskf_path is provided.

Keyword Arguments:

name (str, optional) – Compound name. Default to IUPAC name, CAS number, identifier, or .coskf file name if not specified. Can be set via keyword argument or read from the .coskf file.
cas (str, optional) – CAS number. If not provided, it will attempt to use the value from the .coskf file if available.
identifier (str, optional) – Chemical identifier of the compound.
coskf_path (str, optional) – Directory containing the .coskf file. Defaults to ADFCRS-2018 database path.
smiles (str, optional) – SMILES string. Defaults to the value in the .coskf file if available.
nring (int, optional) – Numbr of ring atoms. Defaults to the value from the .coskf file.
ignore_smiles_check (bool, optional) – If True, skips identity check via SMILES generation. Defaults to Fasle.
ignore_duplicates (bool, optional) – If True, skips duplicate recognition using UniqueConformersCrest in AMSConformer tool. Default to False.

Note

Each compound must have an unique CAS number or identifier.
During add_compound, CAS and identifier are checked for uniqueness in the database.
An error is raised if multiple compounds share the same CAS number and identifier.
The example below is invalid because both compounds use the same identifier, CRS0001.

db.add_compound("Benzene.coskf",cas="71-43-2",identifier="CRS0001")
db.add_compound("Ethanol.coskf",cas="64-17-5",identifier="CRS0001")

add_physical_property(identifier: str, attribute: str, value: float | str, unit: str | None = None)¶

Add a value of a physical property to the PhysicalProperty TABLE in the database using compound’s identifier

Parameters:

identifier (str) – CAS number, identifier or compound name.
attribute (str) – Name of the physical property (eg. meltingpoint or hfusion).
value (float or str) – Value of the physical property.
unit (str, optional) – the unit of the input value. The default units are K, kcal/mol and kcal/mol-K. The following units are accepted and will be automatically converted to the default units: - Temperature: K, C - Enthalpy: kcal/mol, kJ/mol, cal/g, J/g - Heat capacity: kcal/mol-K, kJ/mol-K, cal/g-K, J/g-K - pvap: bar, atm, Pa, mmHg

Note

The vp_equation accepts only parameters for pressure in bar and temperature in Kelvin.

db.add_physical_property("Benzene", "meltingpoint", 278.7)
db.add_physical_property("Benzene", "hfusion", 9.91, unit="kJ/mol")
db.add_physical_property("Benzene", "vp_equation", "Antoine")
db.add_physical_property("Benzene", "vp_params", "4.72583, 1660.652, -1.461")
db.add_physical_property("Benzene", "flashpoint", -11.63, unit="C")
#Vapor pressure at 353.25K is 1.01325 bar
db.add_physical_property("Benzene", "tvap", 353.25)
db.add_physical_property("Benzene", "pvap", 1.01325)

clear_physical_property(identifier: str | List[str] | None = None, attribute: str | List[str] | None = None)¶

Clears the value of a physical property in PhysicalProperty TABLE in the database by compound’s identifier

Parameters:

identifier (str or List[str], optional) – CAS number, chemical identifier or compound name as a string or a list of strings. If None, all compound are selected.
attribute (str or List[str], optional) – Specific property to clear as a string or a list of strings. If None, all properties are cleared.

db.clear_physical_property(["water", "benzene"])

del_row(dbrow: CompoundRow | Dict[str, List[CompoundRow]])¶

Remove a compound from the database and delete the corresponding .coskf file.

Parameters:: dbrow (CompoundRow or Dict[str, List[CompoundRow]]) – the row to remove from the database

del_row_by_conformer_id(conformer_id: int)¶

Remove the conformer from the database.

Parameters:: conformer_id (int) – A integer of intergers representing the conformer in the CONFORMER TABLE.

db.del_row_by_conformer_id(1)

del_rows(dbrows: List[CompoundRow] | Dict[str, List[CompoundRow]])¶

Remove multiple compounds from the database and delete the corresponding .coskf files.

Parameters:: dbrows (List[CompoundRow] or Dict[str, List[CompoundRow]]]) – the rows to remove from the database.

db.del_rows(db.get_compounds('benzene'))

estimate_physical_property(identifier: str | List[str] | None = None, compound_id: int | List[int] | None = None)¶

Estimate the physical properties using the property prediction tool and add the values to the PropPred TABLE in the database

Keyword Arguments:

identifier (str or List[str], optioanl) – CAS number, chemical identifier or compound name as a string or a list of strings.
compound_id (int or List[int], optional) – an integer or a list representing the compound ID(s).

Note

The QSPR descriptor used in the property prediction tool is determined from the SMILES string. The selection priority of SMILES is as follows: (1) User-provided SMILES via the add_compound() method. (2) SMILES read from the .coskf file. (3) SMILES generated by OpenBabel using the compound’s coordinates in the .coskf file. Please note that the automatically resolved SMILES may be incorrect for some molecules, for instance when bond orders cannot be automatically determined and species with charges.

db.estimate_physical_property("Benzene")

get_all_compounds() → List[CompoundRow]¶

Retrive all compounds in the database

Returns:: The full list of CompoundRow instances in the database
Return type:: List[CompoundRow]

get_all_conformers() → List[ConformerRow]¶

Retrives all conformers in the database

Returns:: The full list of ConformerRow instances in the database.
Return type:: List[ConformerRow]

get_all_physical_properties(source: str = 'PhysicalProperty') → List[PhysicalPropertyRow] | List[PropPredRow]¶

Retrive all physical properties in the database

Parameters:: source (str, optional) – Source of the properties. - ‘PhysicalProperty’ (default): Returns properties from the PhysicalProperty table. - ‘PropPred’: Returns estimated properties from the PropPred table.
Returns:: A list of PhysicalPropertyRow instances or PropPredRow instances in the database.
Return type:: List(PhysicalPropertyRow) or List(PropPredRow)

get_attribute_by_compound_id(attributes: str | List[str], compound_id: int | List[int], source: str | List[str] | None = None)¶

Retrieve the list of values for compounds with specified compound_id(s) in the database

Parameters:

attributes (str or List[str]) – Attribute(s) to be retrieved.
compound_id (int or List[int]) – A integer or a list of intergers used to search for compounds in the COMPOUND TABLE.
source (str or List[str], optional) – The table used in the search. Default is COMPOUND TABLE and PhysicalProperty TABLE

Returns:

A list of tuples containing the values of the specified attributes for the compounds.

Return type:

list of attributes

db.get_attribute_by_compound_id("name", 1)
db.get_attribute_by_compound_id(["name", "cas", "hfusion"] 1)
db.get_attribute_by_compound_id(["name", "hfusion"], 1, source=["COMPOUND","PropPred"])

get_compounds(identifier: str | List[str]) → Dict[str, CompoundRow]¶

Retrieves compounds from the COMPOUND TABLE in the database by matching CAS number, chemical identifier, or name.

Parameters:: identifier (str or List[str]) – CAS number, chemical identifier or compound name as a string or a list of strings.
Returns:: A dictionary where each key is an input identifier and its corresponding value is the CompoundRow instances.
Return type:: Dict[str, CompoundRow]

get_compounds_id(identifier: str | List[str]) → List[int | None]¶

Retrieves compound id from the COMPOUND TABLE in the database by matching CAS number, chemical identifier, or name.

Parameters:: identifier (str or List[str]) – CAS number, chemical identifier or compound name as a string or a list of strings.
Returns:: A list of compound IDs corresponding to the input identifier. If a name is not found, None is returned at the corresponding position.
Return type:: List[Optional[int]]

get_conformers(identifier: str | List[str]) → Dict[str, ConformerRow]¶

Retrieves conformers from the CONFORMER TABLE in the database by matching CAS number, chemical identifier, or name.

Parameters:: identifier (str or list) – CAS number, chemical identifier or compound name as a string or a list of strings.
Returns:: A list of ConformerRow instances that match the search criteria.
Return type:: Dict[str, ConformerRow]

Retrive physical properties in the database by matching CAS number, chemical identifier, name or compound id.

Parameters:

identifier (str or List[str], optional) – CAS number, chemical identifier or compound name as a string or a list of strings. If None, compound_id must be provided.
compound_id (int or List[int], optional) – Compound ID as an integer or a list of integers. If None, identifier must be provided.
source (str, optional) – Source of the properties. - ‘PhysicalProperty’ (default): Returns properties from the PhysicalProperty table. - ‘PropPred’: Returns estimated properties from the PropPred table.

Returns:

A list of PhysicalPropertyRow or PropPredRow instances, depending on the source.

Return type:

List[PhysicalPropertyRow] or List[PropPredRow]

modify_attribute_by_compound_id(attribute: str, value: str | int, compound_id: int)¶

Modifies the value of a specified attribute for a given compound ID.

Parameters:

attribute (str) – Attribute to modify. It can be one of the following: ‘name’, ‘cas’, ‘identifier’, ‘smiles’, ‘nring’.
value (str or int) – the new value of the specified attribute.
compound_id (int) – an integer representing the compound ID.

db.modify_attribute_by_compound_id("identifier","InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H", 0)

update_compound_by_conformer_id(compound_id: int, conformer_id: int)¶

Update the data for a compound ID row in the COMPOUND TABLE using the data from a conformer ID row in the CONFORMER TABLE.

Parameters:

compound_id (int) – A integer representing compound id corresponding to a specific row in the COMPOUND TABLE of the database
conformer_id (int) – A integer representing conformer id corresponding to a specific row in the CONFORMER TABLE of the database

update_compound_by_lowestE(compound_id: int | List[int] | None = None)¶

Update the data for a compound ID row in the COMPOUND TABLE using the data from a conformer ID row with the lowest energy having the same compound ID in the CONFORMER TABLE.

Keyword Arguments:: compound_id (int or List[int], optional) – Compound ID as an integer or a list of integers. If None, updates all compounds in the database.

visualize_conformers(compound_id: int | None = None, identifier: str | None = None)¶

Visualize conformers in ascending order of conformers IDs.

Parameters:

compound_id (int, optional) – Compound ID for which conformers are visualized.
identifier (str, optional) – CAS number, chemical identifier or compound name.

class pyCRS.Database.CompoundRow(compound_id: int, conformer_id: int, name: str, cas: str, identifier: str, smiles: str, resolved_smiles: str, coskf: str, Egas: float, Ecosmo: float, nring: int)¶

A data class to represent the contents of a row in a COMPOUND TABLE in COSKFDatabase

compound_id¶

A unique identifer for a specific row in the COMPOUND TABLE of the database

Type:: int

conformer_id¶

A unique identifer for a specific row in the CONFORMER TABLE of the database

Type:: int

name¶

The name associated with the row in the COMPOUND TABLE

Type:: str

cas¶

The CAS number associated with the row, i.e., the compound

Type:: str

identifier¶

The chemical identifier associated with the row, i.e., the compound

Type:: str

smiles¶

The SMILES string provided by user

Type:: str

resolved_smiles¶

The derived SMILES string obtained using OpenBabel from the coordinates in the COSKF file.

Type:: str

coskf¶

The filename of the .coskf file stored in the local SCM_PYCRS_COSKF_DB directory

Type:: str

Egas¶

The gas phase bond energy rounded to 3 decimal places in kcal/mol

Type:: float

Ecosmo¶

The bond energy in a perfect conductor rounded to 3 decimal places in kcal/mol

Type:: float

nring¶

The number of ring atoms

Type:: int

db_path¶

The path to the .coskf file directory

Type:: str

get_full_coskf_path()¶: Returns the full path of the corresponding .coskf file

read_coskf()¶: Opens the .coskf file corresponding to the database entry and returns a scm.plams.KFFile instance

class pyCRS.Database.ConformerRow(conformer_id: int, compound_id: int, name: str, cas: str, identifier: str, smiles: str, resolved_smiles: str, coskf: str, Egas: float, Ecosmo: float, nring: int)¶

A data class to represent the contents of a row in a CONFORMER TABLE in COSKFDatabase

conformer_id¶

A unique identifer for a specific row in the CONFORMER TABLE of the database

Type:: int

compound_id¶

A unique identifer for a specific row in the COMPOUND TABLE of the database

Type:: int

name¶

The name associated with the row in the CONFORMER TABLE

Type:: str

cas¶

The CAS number associated with the row, i.e., the compound

Type:: str

identifier¶

The chemical identifier associated with the row, i.e., the compound

Type:: str

smiles¶

The SMILES string provided by user

Type:: str

resolved_smiles¶

The derived SMILES string obtained using OpenBabel from the coordinates in the COSKF file

Type:: str

coskf¶

The filename of the .coskf file stored in the local SCM_PYCRS_COSKF_DB directory

Type:: str

Egas¶

The gas phase bond energy rounded to 3 decimal places in kcal/mol

Type:: float

Ecosmo¶

The bond energy in a perfect conductor rounded to 3 decimal places in kcal/mol

Type:: float

nring¶

The number of ring atoms

Type:: int

db_path¶

The path to the .coskf file directory

Type:: str

get_full_coskf_path()¶: Returns the full path of the corresponding .coskf file

read_coskf()¶: Opens the .coskf file corresponding to the database entry and returns a scm.plams.KFFile instance

class pyCRS.Database.PhysicalPropertyRow(compound_id: int, meltingpoint: float, hfusion: float, cpfusion: float, boilingpoint: float, density: float, flashpoint: float, dielectricconstant: float, vp_equation: str, vp_params: str, tvap: float, pvap: float, Mn: float)¶

A data class to represent the contents of a row in a PhysicalProperty TABLE in COSKFDatabase

compound_id¶

A unique identifer for a specific row in the COMPOUND TABLE of the database

Type:: int

meltingpoint¶

melting temperature (K)

Type:: float

hfusion¶

enthalpy of husion (kcal/mol)

Type:: float

cpfusion¶

heat capacity of fusion (kcal/mol-K) calculated as the difference between the heat capacity in the liquid state and the heat capacity in the solid state.

Type:: float

boilingpoint¶

boiling pointK (K)

Type:: float

density¶

liquid density (kg/L)

Type:: float

flashpoint¶

flash point (K)

Type:: float

dielectricconstant¶

dielectric constant

Type:: flash

vp_equation¶

The vapor pressure equation to use. Unit in bar. Options include: ANTOINE, VPM1 and DIPPR101

Type:: str

vp_params¶

Parameters for the vp_equation, expressed as “A, B, C, D, E”

Type:: str

tvap¶

Temperature(K) at pvap

Type:: float

pvap¶

Pressure(bar) at tvap

Type:: float

Mn¶

polymer average molecular weight (g/mol)

Type:: float

Vapor Pressure Equations:

ANTOINE:: log10(P) = A - B/(C+T)
DIPPR101:: ln(P) = A + B/T + C*ln(T) + D*T**E
VPM1:: ln(P) = A/T + B*ln(T) + C*T + D

class pyCRS.Database.PropPredRow(compound_id: int, adopt_smiles: str, meltingpoint: float, hfusion: float, boilingpoint: float, density: float, flashpoint: float, dielectricconstant: float, vp_equation: str, vp_params: str)¶

A data class to represent the contents of a row in a PropPred TABLE in COSKFDatabase

compound_id¶

A unique identifer for a specific row in the COMPOUND TABLE of the database

Type:: int

adopt_smiles¶

The SMILES used for QSPR method

Type:: str

meltingpoint¶

melting temperature (K)

Type:: float

hfusion¶

enthalpy of husion (kcal/mol)

Type:: float

boilingpoint¶

boiling pointK (K)

Type:: float

density¶

liquid density (kg/L)

Type:: float

flashpoint¶

flash point (K)

Type:: float

dielectricconstant¶

dielectric constant

Type:: flash

vp_equation¶

The vapor pressure equation to use. Unit in bar. VPM1

Type:: str

vp_params¶

Parameters for the vp_equation, expressed as “A, B, C, D, E”

Type:: str

Electronic Structure

ADF

Periodic DFT

DFTB & MOPAC

Interatomic Potentials

ReaxFF

Machine Learning Potentials

Force Fields

kMC and Microkinetics

Bumblebee: OLED stacks

Fluid Thermodynamics

COSMO-RS

Workflows and Utilities

OLED workflows

ChemTraYzer2

Conformers

Reactions Discovery

AMS Driver

Properties

PES Exploration

Molecular Dynamics

Monte Carlo

Interfaces

ParAMS

PLAMS

GUI

VASP

Downloads

Windows

Mac

Linux

Documentation

Overview

Tutorials

Installation Manual

Brochures

Other Resources

Changelog

Webinars

Workshops

Knowledgebank

FAQ

Pricing and licensing

Database¶