Gears

Interface

class scine_chemoton.gears.Gear

The base class for all Gears.

A Gear in Chemoton is a continuous loop that alters, analyzes or interacts in any other way with a reaction network stored in a SCINE Database. Each Gear has to be attached to an Engine(scine_chemoton.engine.Engine) and will then help in driving the exploration of chemical reaction networks forward.

Extending the features of Chemoton can be done by add new Gears or altering existing ones.

__call__(credentials, single=False)

Starts the main loop of the Gear, then acting on the database referenced by the given credentials.

Parameters

• : (single) – db.Credentials (Scine::Database::Credentials): The credentials to a database storing a reaction network.

• : – bool: If true, runs only a single iteration of the actual loop. Default: false, meaning endless repetition of the loop.

Implementations

Compound Sorting

class scine_chemoton.gears.compound.BasicAggregateHousekeeping

This Gear updates all relevant Structures stored in the database with bond orders and graph representations. This data is then used to sort each Structure into existing Compounds/Flasks or to create a new Compound/Flask if no appropriate one exists.

options

The options for the BasicAggregateHousekeeping Gear.

Type

BasicAggregateHousekeeping.Options

Notes

Checks for all ‘user_optimized’, ‘minimum_optimized’, and ‘complex_optimized’ Structures that do not have an Aggregate assigned. The Gear then generates bond orders and molecular graphs (‘masm_cbor_graph’, and ‘masm_decision_list’) if they are not yet present. Using the molecular graphs the Structures are then sorted into Compounds/Flasks.

class Options

The options for the BasicAggregateHouseKeeping Gear.

bond_order_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for the bond order calculations. The default is: the ‘scine_bond_orders’ order on a single core.

bond_order_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to the bond order calculations. Empty by default.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

exclude_misguided_conformer_optimizations: bool

bool If true, no additional aggregate is created if the structure was generated only by geometry optimization.

graph_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for the graph calculations. The default is: the ‘graph’ order on a single core.

graph_settings: scine_utilities.ValueCollection

Dict[str, str] Additional settings passed to the graph calculations. Empty by default.

model: scine_database.Model

db.Model (Scine::Database::Model) The Model used for the bond order calculations. The default is: PM6 using Sparrow.

static get_n_atoms(structure)

Return type

List[int]

Conformer Generation

class scine_chemoton.gears.conformers.brute_force.BruteForceConformers

This Gear generates all possible conformers as a guess based on the centroid of each Compound. The guesses are then optimized. Deduplication of optimized Structures happens when sorting them into compounds.

options :: BruteForceConformers.Options

The options for the BruteForceConformers Gear.

Notes

Checks if any existing Compound does not have conformer guesses generated. Conformer guesses are supposed to be the only ‘minimum_guess’ structures assigned to compounds as they are the only ones where the correct graph assignment should be possible. If no conformer guesses are present they are generated and the associated geometry optimizations are scheduled.

class Options

The options for the BruteForceConformers Gear.

conformer_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for the generation of new conformer guesses. The default is: the ‘conformers’ order on a single core.

conformer_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to the conformer generation calculations. Empty by default.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

minimization_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used to optimize the geometries of the generated conformer guesses. The default is: the ‘scine_geometry_optimization’ order on a single core.

minimization_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to the geometry optimization calculations. Empty by default.

model: scine_database.Model

db.Model (Scine::Database::Model) The Model used for the conformer generation. The default is: PM6 using Sparrow.

temperature

Elementary Steps Exploration

class scine_chemoton.gears.elementary_steps.ElementaryStepGear

Base class for elementary step reaction generators

class Options

The options for an ElementarySteps Gear.

cycle_time

int Sleep time between cycles, in seconds.

enable_bimolecular_trials

bool If True, enables the exploration of bimolecular reactions.

enable_unimolecular_trials

bool If True, enables the exploration of unimolecular reactions.

class scine_chemoton.gears.elementary_steps.brute_force.BruteForceElementarySteps

This Gear probes Reactions by trying to react all Structures of each Compound with all Structures of each other Compound. For each Structure–Structure combination multiple arrangements (possible Elementary Steps) will be tested.

This Gear does not consider Flasks/Complexes as reactive, they are not probed for elementary steps.

options :: BruteForceElementarySteps.Options

The options for the BruteForceElementarySteps Gear.

filter :: scine_chemoton.gears.elementary_steps.compound_filter.CompoundFilter

A filter for allowed reaction combinations, per default everything is permitted, no filter is applied.

Notes

This function assumes maximum spin when adding two Structures into one reactive complex. The need for elementary step guesses is tested by:

1. for bimolecular reactions: checking whether there is already a

   calculation to search for a bimolecular reaction of the same structures with the same job order

2. for unimolecular reactions: checking whether there is already a

   calculation to search for an intramolecular reaction of the same structure with the same job order

class scine_chemoton.gears.elementary_steps.minimal.MinimalElementarySteps

This Gear probes Reactions by trying to react

1. one Structure of each compound with one Structure of each other compound (intermolecular reactions)

2. one Structure with itself intramoleculary for each compound.

For each combination multiple arrangements (possible Elementary Steps) will be tested.

This Gear does not consider Flasks/Complexes as reactive, they are not probed for elementary steps.

options :: MinimalElementarySteps.Options

The options for the MinimalElementarySteps Gear.

compound_filter :: scine_chemoton.gears.elementary_steps.compound_filters.CompoundFilter

A filter for allowed reaction combinations, per default everything is permitted, no filter is applied.

trial_generator :: TrialGenerator

The generator to set up elementary step trial calculations by enumerating reactive complexes and trial reaction coordinates

Notes

This function assumes maximum spin when adding two Structures into one reactive complex. The need for elementary step guesses is tested by:

1. for bimolecular reactions: checking whether there is already a

   calculation to search for a bimolecular reaction of the same structures with the same job order

2. for unimolecular reactions: checking whether there is already a

   calculation to search for an intramolecular reaction of the same structure with the same job order

class scine_chemoton.gears.elementary_steps.trial_generator.TrialGenerator

Base class for elementary step trial generators

abstract bimolecular_reactions(structure_list)

Return type

None

abstract unimolecular_reactions(structure)

Return type

None

class scine_chemoton.gears.elementary_steps.trial_generator.bond_based.BondBased

Class to generate reactive complex calculations via bond-based approaches.

options

The options for generating reactive complex calculations.

Type

BondBased.Options

reactive_site_filter

The filter applied to determine reactive sites, reactive pairs and trial reaction coordinates.

Type

ReactiveSiteFilter

class Options

The options for bond-based reactive complex enumeration.

class BimolOptions

The options for the generation and exploration of bimolecular reactions.

NOTE: The minimum and maximum bounds regarding the number of bonds to be modified/formed/broken have to be understood as strict limitations. If different options are in conflict with each other the stricter limit is applied. For example, if you set max_bond_dissociations to 2 but max_bond_modifications to 1 you will never get a trial reaction coordinate containing two dissociations.

complex_generator

InterReactiveComplexes The generator used for the composition of reactive complexes.

job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used to evaluate the elementary step trial calculations. The default is: the scine_react_complex_nt2 order on a single core.

job_settings: scine_utilities.ValueCollection

Dict[str, Union[bool, int, float]] Additional settings added to the elementary step trial calculation. Empty by default.

max_bond_dissociations

int The maximum number of bond dissociations to be encouraged simultaneously during an elementary step trial calculation. By default 1.

max_bond_modifications

int The maximum number of bond modifications (formation or dissociation) to be encouraged simultaneously during an elementary step trial calculation. By default 1.

max_inter_bond_formations

int The maximum number of bond formations between the two reactants to be encouraged simultaneously during an elementary step trial calculation. More than two intermolecular bond formations are currently not supported. By default 1.

max_intra_bond_formations

int The maximum number of bond formations to be encouraged simultaneously during an elementary step trial calculation. By default 0.

min_bond_dissociations

int The minimum number of intramolecular bond dissociations to be encouraged simultaneously during an elementary step trial calculation. By default 0.

min_bond_modifications

int The minimum number of bond modifications (formation or dissociation) to be encouraged simultaneously during an elementary step trial calculation. By default 1.

min_inter_bond_formations

int The minimum number of bond formations between the two reactants to be encouraged simultaneously during an elementary step trial calculation. Has to be equal or greater than 1. By default 1.

min_intra_bond_formations

int The minimum number of intramolecular bond formations to be encouraged simultaneously during an elementary step trial calculation. By default 0.

minimal_spin_multiplicity

bool Whether to assume max spin recombination, thus assuming minimal resulting spin, or take combination of input spin multiplicities. (default: False) True: | multiplicity1 - multiplicity2 | - 1 False: sum(multiplicities) - 1

class UnimolOptions

The options for the generation and exploration of unimolecular reactions.

job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used to evaluate the possible reactions. Jobs with the order scine_react_complex_nt2 are supported. The default is: the scine_react_complex_nt2 order on a single core.

job_settings_associative: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to Calculation evaluating the possible reactions. These settings are passed to all calculations that are expected to result in the formations of at least one bond, i.e., that at least one of the reactive atom pairs is not bound in the start structure. Empty by default.

job_settings_disconnective: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to Calculation evaluating the possible reactions. These settings are passed to all calculations for which all of the reactive atom pairs are bound in the start structure and cutting them apart would result into at least two separate molecules. Empty by default.

job_settings_dissociative: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to Calculation evaluating the possible reactions. These settings are passed to all calculations for which all of the reactive atom pairs are bound in the start structure but cutting them apart would not result into two separate molecules. Empty by default.

max_bond_dissociations

int The maximum number of bond dissociations to be encouraged simultaneously during an elementary steps trial calculation. By default 1.

max_bond_formations

int The maximum number of bond formations to be encouraged simultaneously during an elementary step trial calculation. By default 1.

max_bond_modifications

int The maximum number of bond modifications (formation or dissociation) to be encouraged simultaneously during an elementary step trial calculation. By default 1.

min_bond_dissociations

int The minimum number of bond dissociations to be encouraged simultaneously during an elementary steps trial calculation. By default 1.

min_bond_formations

int The minimum number of bond formations to be encouraged simultaneously during an elementary step trial calculation. By default 1.

min_bond_modifications

int The minimum number of bond modifications (formation or dissociation) to be encouraged simultaneously during an elementary step trial calculation. By default 1.

bimolecular

BimolOptions The options for reactions involving two molecules, that are set up to be associative in nature.

model: scine_database.Model

db.Model (Scine::Database::Model) The Model used to evaluate the possible reactions. The default is: PM6 using Sparrow.

unimolecular

UnimolOptions The options for reactions involving a single molecule.

bimolecular_reactions(structure_list)

Creates reactive complex calculations corresponding to the bimolecular reactions between the structures if there is not already a calculation to search for a reaction of the same structures with the same job order.

Parameters

: (structure_list) – List[db.Structure]: List of the two structures to be considered. The Structures have to be linked to a database.

estimate_n_bimolecular_trials(structure_file1, structure_file2, attack_points_per_site=3, n_inter_reactive_pairs=-1, n_reactive_bound_pairs1=-1, n_reactive_unbound_pairs1=-1, n_reactive_bound_pairs2=-1, n_reactive_unbound_pairs2=-1)

Estimates the number of bimolecular reactive coordinate trials expected to arise directly (i.e. as single step elementary reaction trials) from the given structures without taking reactive site filters into account. If the number of reactive pairs shall be limited for this estimate, specify n_inter_reactive_pairs, n_reactive_bound_pairs and/or n_reactive_unbound_pairs. Note that this method only estimates the number of trials but is not necessarily resulting in the exact number that would be generated by the trial generator: The structures connectivities are perceived from interatomic distances. Multiple attack points are not calculated from the structure’s geometry but only included based on a fixed input value (attack_points_per_site). The number of rotamers is not accounted for correctly for intermolecular coordinates involving two reactive pairs with one monoatomic fragment.

Note: The number of trials increases quickly with the number of allowed

bond modifications. Be aware!

Parameters

• structure_file1 (str) – An xyz or mol file with the structure of interest.

• structure_file2 (str) – An xyz or mol file with the structure of interest.

• attack_points_per_site (int) – The number of attack points per intermolecular reactive site to consider if multiple attack points are enabled in the reactive complex generator. Note that these will not be calculated from the structures’ geometries in this estimator. By default 3.

• n_inter_reactive_pairs (int, optional) – The number of intermolecular reactive pairs to consider. If smaller than zero, all interstructural atom pairs are included. By default -1.

• n_reactive_bound_pairs1 (int, optional) – The number of bound reactive pairs in the first structure to consider. If smaller than zero, all bound atom pairs of structure 1 are included. By default -1.

• n_reactive_bound_pairs2 (int, optional) – The number of bound reactive pairs in the second structure to consider. If smaller than zero, all bound atom pairs of structure 2 are included. By default -1.

• n_reactive_unbound_pairs1 (int, optional) – The number of unbound reactive pairs in the first structure to consider. If smaller than zero, all unbound atom pairs are included. By default -1.

• n_reactive_unbound_pairs2 (int, optional) – The number of unbound reactive pairs in the second structure to consider. If smaller than zero, all unbound atom pairs are included. By default -1.

Returns

The number of reactive trial coordinates expected to arise from this structure.

Return type

int

estimate_n_unimolecular_trials(structure_file, n_reactive_bound_pairs=-1, n_reactive_unbound_pairs=-1)

Estimates the number of unimolecular reactive coordinate trials expected to arise directly (i.e. as single step elementary reaction trials) from the given structure without taking reactive site filters into account. If the number of reactive pairs shall be limited for this estimate, specify n_reactive_bound_pairs and/or n_reactive_unbound_pairs. The structure’s connectivity is perceived from interatomic distances.

Note: The number of trials increases quickly with the number of allowed

bond modifications. Be aware!

Parameters

• structure_file (str) – An xyz or mol file with the structure of interest.

• n_reactive_bound_pairs (int, optional) – The number of bound reactive pairs to consider. If smaller than zero, all bound atom pairs are included. By default -1.

• n_reactive_unbound_pairs (int, optional) – The number of unbound reactive pairs to consider. If smaller than zero, all unbound atom pairs are included. By default -1.

Returns

The number of reactive trial coordinates expected to arise from this structure.

Return type

int

unimolecular_reactions(structure)

Creates reactive complex calculations corresponding to the unimolecular reactions of the structure if there is not already a calculation to search for a reaction of the same structure with the same job order.

Parameters

: (structure) – db.Structure: The structure to be considered. The Structure has to be linked to a database.

class scine_chemoton.gears.elementary_steps.trial_generator.fragment_based.FragmentBased

Class to generate reactive complex calculations via fragment-based approaches.

options

The options for generating reactive complex calculations.

Type

FragmentBased.Options

reactive_site_filter

The filter applied to determine reactive sites. NOTE: Reactive pairs/coordinates for the application of the filter_atom_pairs and filter_reaction_coordinates methods are generated by probing all possible across-fragment combinations for unimolecular reactions (i.e. each pair has to consist of atoms belonging to two different fragments). If any of the combinations belonging to a certain fragment composition is allowed, the fragment composition is considered. For bimolecular reactions with two diatomic fragments the reactive pairs correspond to the atoms facing each other in the (unrotated) reactive complex.

Type

ReactiveSiteFilter

class Options

The options for the fragment-based reactive complex enumeration.

class BimolAssociationOptions

The options for the exploration of bimolecular reactions.

complex_generator

InterReactiveComplexes The generator used for the composition of reactive complexes from given interstructural components of reactive coordinates.

consider_diatomic_fragments

bool Whether to also generate reactive complexes with diatomic reactive fragments (i.e., reactive complex calculations with the lhs and/or rhs lists containing two atoms). (default: False)

job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used to do reactive complex calculations/trial elementary step calculations. scine_react_complex_nt and scine_react_complex_afir jobs are supported. The default is: the scine_react_complex_nt order on a single core.

job_settings: scine_utilities.ValueCollection

Additional settings added to the elementary step trial calculation. Empty by default.

max_within_fragment_graph_distance

int Maximum number of bonds between two atoms forming a reactive fragment. This option is only effective if consider_diatomic_fragments is True. (default: 1)

minimal_spin_multiplicity

bool Whether to assume max spin recombination, thus assuming minimal resulting spin, or take combination of input spin multiplicities. (default: False) True: | multiplicity1 - multiplicity2 | - 1 False: sum(multiplicities) - 1

class UnimolAssociationOptions

The options for the generation of associative unimolecular elementary step trial calculations.

consider_diatomic_fragments

bool Whether to also set up unimolecular reactions where the individual reactive fragments are composed of two atoms. (default: False) Note: Pairs are only made subject to an elementary step trial/reactive complex calculations if none of the atoms of the one fragment is directly bound to any of the atoms in the other fragment.

enabled

bool If True, enables the exploration of these types of reactions.

job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used to evaluate the possible reactions. The default is: the scine_react_complex_afir order on a single core.

job_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to Calculation evaluating the possible reactions. Empty by default.

max_inter_fragment_graph_distance

int The maximum distance between atoms (bond count) to be considered for association reactions. If the fragments are diatomic all possible atom pairs arising from forming the cartesian product of the fragments have to have a distance that is not larger than this value.

max_within_fragment_graph_distance

int Maximum number of bonds between two atoms forming a reactive fragment. This option is only effective if consider_diatomic_fragments is True. (default: 1)

min_inter_fragment_graph_distance

int The minimum graph distance between fragments (bond count) to be considered for association reactions. If the fragments are diatomic all possible atom pairs arising from forming the cartesian product of the fragments have to have a distance of at least this value.

class UnimolDissociationOptions

The options for the generation of dissociative and disconnective unimolecular trial elementary step calculations.

enabled: bool

bool If True, enables the exploration of these types of reactions.

job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used to evaluate the possible reactions. The default is: the scine_react_complex_nt order on a single core.

job_settings_disconnective: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to Calculation evaluating the possible reactions. These settings are passed to all calculations that are expected to result in disconnection of the molecule generating two new molecules in the process. Empty by default.

job_settings_dissociative: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to Calculation evaluating the possible reactions. These settings are passed to all calculations that are expected to result in dissociations of the tested atoms only, retaining a single molecule. Empty by default.

max_graph_distance

bimolecular_association

BimolAssociationOptions The settings for reactions involving two molecules, that are set up to be associative in nature.

model: scine_database.Model

db.Model (Scine::Database::Model) The Model used to evaluate the possible reactions. The default is: PM6 using Sparrow.

unimolecular_association

UnimolAssociationOptions The settings for reactions involving a single molecule, that are set up to be associative in nature.

unimolecular_dissociation

UnimolDissociationOptions The settings for reactions involving a single molecule, that are set up to be dissociative in nature.

bimolecular_reactions(structure_list)

Creates reactive complex calculations corresponding to the bimolecular reactions between the structures if there is not already a calculation to search for a reaction of the same structures with the same job order.

Parameters

: (structure_list) – List[db.Structure]: List of the two structures to be considered. The Structures have to be linked to a database.

unimolecular_reactions(structure)

Creates reactive complex calculations corresponding to the unimolecular reactions of the structure if there is not already a calculation to search for a reaction of the same structure with the same job order.

Parameters

: (structure) – db.Structure: The structure to be considered. The Structure has to be linked to a database.

class scine_chemoton.gears.elementary_steps.trial_generator.connectivity_analyzer.ConnectivityAnalyzer(structure)

A class holding the molecule representation of a structure allowing to retrieve information about its bonding situation and the connectivity effect of trial reaction coordinates.

structure :: db.Structure

The structure of interest. It has to be connected to a database and has to have a graph attached.

get_adjacency_matrix()

Gets the adjacency matrix for the structure with the indices ordered as in the structure.

Returns

The adjacency matrix which is True if there is a direct bond and False otherwise.

Return type

lil_matrix

get_graph_distance(atom1, atom2)

Calculates the graph distance between the atoms with indices atom1 and atom2.

Parameters

• atom1 (int) – The index of the first atom of interest.

• atom2 (int) – The index of the second atom of interest.

Returns

The graph distance between atoms 1 and 2.

Return type

int

Raises

RuntimeError – Raises an error if the two atoms belong to different molecules.

get_reaction_type(reactive_pair_list)

Determines what kind of intrastructural reaction (associative, dissociative, disconnective) a reactive complex guess describes.

Parameters

: (reactive_pair_list) – List[Tuple[int]]: List of reacting atom index pairs

Returns

What kind of reaction is initiated by this reactive complex.

Return type

reaction_type :: ElementaryStepGear.ElementaryStepType

pair_is_bound(atom1, atom2)

Check whether two atoms are bound in a structure according to its graph.

Parameters

• atom1 (int) – Index of the first atom.

• atom2 (int) – Index of the second atom.

Returns

True if the two atoms are bound and False if not.

Return type

bool

class scine_chemoton.gears.elementary_steps.trial_generator.connectivity_analyzer.ReactionType(value)

Different types of reactions to be distinguished here.

• Mixed: Neither purely associative nor dissociative

• Associative: Only new bonds are generated

• Dissociative: Only bond breaking but the molecule is not split

• Disconnective: Only bond breaking and the molecule is split

Associative = 0

Disconnective = 2

Dissociative = 1

Mixed = None

Compound Filter

class scine_chemoton.gears.elementary_steps.compound_filters.AtomNumberFilter(max_n_atoms, structures)

Filters out all compounds with a total number of atoms larger than the given value. For multiple compounds the total number of atoms has to be equal or smaller than the given value.

max_n_atoms :: int

The maximum number of allowed atoms.

structures :: db.Collection

The collection of structures to be used for the counting of elements.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.CatalystFilter(atom_type_count, structures, restrict_unimolecular_to_catalyst=False)

Filters by defining an important structural motive. A user defined set of atoms present in a structure identify it to be the, or a version of the catalyst. This simple check should work great for common transition metal catalysts.

Only specific reactions revolving around a catalytic cycle are then allowed: i) reactions that feature the catalyst and one other compound that is not the catalyst. ii) reactions that only involve a single compound (not restricted to the catalyst, unless specified otherwise with flag (see parameters))

atom_type_count :: Dict[str,int]

A dictionary giving the number (values) of atoms that are expected to be only present in - and thus defining - the catalyst. Atom type (atom symbol strings) are given as keys. Atom symbols not given are considered to be irrelevant to the check and may be present in the catalyst. In order to ban atoms, set their count to zero.

structures :: db.Collection

The collection of structures to be used for the counting of elements.

restrict_unimolecular_to_catalyst :: bool

Whether unimolecular reactions should also be limited to the catalyst.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.CompoundFilter

The base and default class for all filters. The default is to allow/pass all given checks.

CompoundFilters are optional barriers in Chemoton that allow the user to cut down the exponential growth of the combinatorial explosion. The different subclasses of this main CompoundFilter allow for a tailored choice of which additional branches of the network to allow.

There are some predefined filters that will be given in Chemoton, however, it should be simple to extend as needed even on a per-project basis. The key element when sub-classing this interface is to override the filter functions as defined here. When sub-classing please be aware that these filters are expected to be called often. Having each call do loops over entire collections is not wise.

For the latter reason, user defined subclasses are intended to be more complex, allowing for non-database stored/cached data across a run. This can be a significant speed-up and allow for more intricate filtering.

filter(_, __=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.CompoundFilterAndArray(filters=None)

An array of logically ‘and’ connected filters.

filters :: List[CompoundFilter]

A list of filters to be combined.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.CompoundFilterOrArray(filters=None)

An array of logically ‘or’ connected filters.

filters :: List[CompoundFilter]

A list of filters to be combined.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.ElementCountFilter(atom_type_count, structures)

Filters by atom counts. All given compounds must resolve to structures that separately fall below the given threshold. No assumptions about atom counts of possible combinations/products are made in this filter.

atom_type_count :: Dict[str,int]

A dictionary giving the number (values) of allowed occurrences of each atom type (atom symbol string given as keys). Atom symbols not given as keys are interpreted as forbidden.

structures :: db.Collection

The collection of structures to be used for the counting of elements.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.ElementSumCountFilter(atom_type_count, structures)

Filters by atom counts. All given compounds must resolve to structures that together fall below the given threshold.

atom_type_count :: Dict[str,int]

A dictionary giving the number (values) of allowed occurrences of each atom type (atom symbol string given as keys). Atom symbols not given as keys are interpreted as forbidden.

structures :: db.Collection

The collection of structures to be used for the counting of elements.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.IDFilter(ids)

Filters by compound id. Returns true only for the specified compounds. Used for testing purposes.

reactive_ids :: List[db.ID]

The IDs of the compounds to be considered as reactive.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.MolecularWeightFilter(max_weight, structures)

Filters by molecular weight. All given compounds must resolve to structures that separately fall below the given threshold. No assumptions about weights of possible combinations/products are made in this filter.

max_weight :: float

The maximum weight to be allowed, given in unified atomic mass units (u). For example, dinitrogen has a weight of about 28 u.

structures :: db.Collection

The collection of structures to be used for the molecular weight calculations.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.OneCompoundIDFilter(ids)

Filters all compounds that are not present on a given “white list” of IDs. In the case of multiple compounds, at least one has to be present in the list. Note that this is identical to the IDFilter in the case of only one compound.

reactive_ids :: List[db.ID]

The IDs of the compounds to be considered as reactive.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.SelectedCompoundIDFilter(reactive_ids, selected_ids)

Filters all compounds for which one needs to be one a given “white list” of reactive compounds and the other has to be either on a list of compounds of interest or on the list of reactive compounds.

reactive_ids :: List[db.ID]

The IDs of the compounds to be considered as reactive.

selected_ids :: List[db.ID]

The IDs of the compounds to be of interest.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.SelfReactionFilter

Filters out bimolecular reactions of compounds with themselves.

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

class scine_chemoton.gears.elementary_steps.compound_filters.TrueMinimumFilter(structures, properties, imaginary_frequency_threshold=0.0)

Filters by checking if compound fulfills requirement to be considered a true minimum. This includes having frequencies and all of them are above a given threshold. All given compounds must resolve to structures that separately only have frequencies above the given threshold. Single atoms or ions are considered as minima automatically. Frequencies must be calculated with the ThermoGear during an exploration, otherwise all compounds and combinations of them are filtered out.

structures :: db.Collection

The collection of structures to be used to be checked for being a true minimum.

properties :: db.Collection

The collection of properties to be used to look up frequencies of structures.

imaginary_frequency_threshold :: float

The frequency in atomic units above which a structure is considered a minimum structure. For example, a molecule with one imaginary frequency of -1e-4 (-138 cm^-1) can be considered a minimum by setting the threshold to -1.1e-4 (-152 cm^-1)

filter(compound_one, compound_two=None)

The blueprint for a filter function, checking if both of the compounds are allowed to be used in an exploration (logical and). If only one compound is given a check using only that one compound is performed. This default CompoundFilter accepts all compounds.

_ :: db.Compound

The compound to be checked.

_ :: db.Compound

The other compound to be checked in the case of bimolecular reactions.

Returns

True if the compound passed the check/filter, False if the compound did not pass the check and should not be used.

Return type

result :: bool

Reactive Site Filter

class scine_chemoton.gears.elementary_steps.reactive_site_filters.AtomRuleBasedFilter(rules)

A filter that only classifies atoms as reactive if they correspond to a given rule. The rules are given for each element. They may be a maximum required distance to another atom/element or they may label an atom as generally reactive or not reactive. If not rules are given for an element. All atoms of this type will be considered as non-reactive.

Example rules: reactive_site_rules = { ‘H’: [ReactiveRuleFilterOrArray([(‘O’, 3), (‘N’, 1)])], ‘C’: [ReactiveRuleFilterOrArray([(‘O’, 2), (‘N’, 2)])], ‘O’: True, ‘N’: True } Allow reactions for all O and N, for all H that are at most in a distance of 3 bonds to O or one bond to N, and for all C that are at most two bonds away from O or N.

rules

The dictionary containing the rules (vide supra).

Type

dict

class FunctionalGroupRule(distance, hetero_atoms, central_atom='C', n_bonds=3, n_hetero_atoms=1)

A rule that encodes a distance criterion to a very general functional group. The functional group is encoded in terms of a central atom type, a list of hetero atoms, the number of bonds to the central atom and the number of hetero atoms bonded to the central atom.

carbonyle_group_d2 = FunctionalGroupRule(2, [‘O’], ‘C’, 3, 1) imine_group_d0 = FunctionalGroupRule(0, [‘N’], ‘C’, 3, 1) acetal_group_d1 = FunctionalGroupRule(0, [‘O’], ‘C’, 4, 2) acetal_like_group_d1 = FunctionalGroupRule(0, [‘O, N’], ‘C’, 4, 2)

distance

The bond distance to the functional group that must be matched.

Type

int

hetero_atoms

The list of atoms that are considered hetero atoms for this group.

Type

List[str]

central_atom

The central atom element symbol (default ‘C’)

Type

str

n_bonds

The number of bonds to the central atom.

Type

int

n_hetero_atoms

The number of hetero atoms that must bond to the central atom to constitute the group.

Type

int

filter_by_rule(molecules, idx_map, elements, atom_index)

Return type

bool

class ReactiveRuleFilterAndArray(primitive_rules=None)

An array of logically ‘and’ connected rules.

primitive_rules

A list of bond distance based rules that have all to be fulfilled. Syntax example: (‘O’, 2) -> An oxygen atom has to be within two bonds distance of the current atom for it to be allowed to react.

Type

List[Tuple[str, int]]

filter_by_rule(molecules, idx_map, elements, atom_index)

Return type

bool

class ReactiveRuleFilterOrArray(primitive_rules=None)

An array of logically ‘or’ connected rules.

primitive_rules

A list of bond distance based rules of which at least one has to be fulfilled. Syntax example: (‘O’, 2) -> An oxygen atom has to be at a distance of two bonds of the current atom for it to be allowed to react.

Type

List[Tuple[str, int]]

filter_by_rule(molecules, idx_map, elements, atom_index)

Return type

bool

filter_atoms(structure_list, atom_indices)

The blueprint for a filter function, checking a list of atoms regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this function.

• atom_indices ([List[int]]) – The list of atoms to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

result – The list of all relevant atom indices after applying the filter.

Return type

List[int]

class scine_chemoton.gears.elementary_steps.reactive_site_filters.ElementWiseReactionCoordinateFilter(rules, reactive_if_rules_apply=False)

A filter that can restrict the combination of atoms with a specific element. The filter can be operated in two modes: Allow all reaction coordinates for the element combinations encoded in the rules or forbid all of them.

Example rules: reaction_coordinate_rules = { ‘H’: [‘H’, ‘C’] } In the default “forbid-mode” these rules mean that no reaction coordinates between two H-atoms and H and C are allowed.

rules

The dictionary containing the rules (vide supra).

Type

dict

reactive_if_rules_apply

The mode to operate the filter in. If true, only reaction coordinates in the given rule set pass. If false, no reaction coordinate in the given rule set pass. By default, false.

Type

bool

filter_reaction_coordinates(structure_list, coordinates)

The blueprint for a filter function, checking a list of trial reaction coordinates each given as a tuple of reactive atom pairs for their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• coordinates (List[List[Tuple[int, int]]]) – The list of trial reaction coordinates to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reaction coordinates given as tuples of reactive atom pairs after applying the filter.

Return type

result :: List[List[Tuple[int, int]]]

class scine_chemoton.gears.elementary_steps.reactive_site_filters.HeuristicPolarizationReactionCoordinateFilter(rules)

A filter that assigns polarizations (+, -, or +-) to each atom. Reaction coordinates are only allowed that combine + and - or +- with either + or -. Example rules: rules = { ‘H’: [PaulingElectronegativityRule(), FunctionalGroupRule(“+”, 2, [‘N’, ‘O’], ‘C’, 3, 1)], ‘C’: [PaulingElectronegativityRule()], ‘N’: [PaulingElectronegativityRule()], ‘O’: [PaulingElectronegativityRule()] }

rules

The dictionary containing the rules. The rule object must implement a function called string_from_rule(…).

Type

dict

class FunctionalGroupRule(character, distance, hetero_atoms, central_atom='C', n_bonds=3, n_hetero_atoms=1)

Polarization rule for functional groups. The functional group is encoded in terms of a central atom type, a list of hetero atoms, the number of bonds to the central atom and the number of hetero atoms bonded to the central atom.

carbonyle_group_d2 = FunctionalGroupRule(‘+’ ,2, [‘O’], ‘C’, 3, 1) imine_group_d0 = FunctionalGroupRule(‘+’ ,0, [‘N’], ‘C’, 3, 1) acetal_group_d1 = FunctionalGroupRule(‘+’, 0, [‘O’], ‘C’, 4, 2) acetal_like_group_d1 = FunctionalGroupRule(‘+’, 0, [‘O, N’], ‘C’, 4, 2)

character

The polarization character (+ or -) to assign if the rule applies.

Type

str

distance

The bond distance to the functional group that must be matched.

Type

int

hetero_atoms

The list of atoms that are considered hetero atoms for this group.

Type

List[str]

central_atom

The central atom element symbol (default ‘C’)

Type

str

n_bonds

The number of bonds to the central atom.

Type

int

n_hetero_atoms

The number of hetero atoms that must bond to the central atom to constitute the group.

Type

int

string_from_rule(molecules, idx_map, elements, atom_index)

Return type

str

class PaulingElectronegativityRule(min_difference=0.4)

Polarization rule for the Pauli electronegativity scalar.

min_difference

The minimum difference in electronegativities to assign a polarization.

Type

dict

string_from_rule(molecules, idx_map, elements, atom_index)

Return ‘+’ if the atom is electron poor, ‘-’ if it is electron rich, some combination thereof if the atom is neighbouring elements with significantly higher and lower electronegativity, and ‘’ if it is neighbouring neither.

Return type

str

filter_reaction_coordinates(structure_list, coordinates)

The blueprint for a filter function, checking a list of trial reaction coordinates each given as a tuple of reactive atom pairs for their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• coordinates (List[List[Tuple[int, int]]]) – The list of trial reaction coordinates to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reaction coordinates given as tuples of reactive atom pairs after applying the filter.

Return type

result :: List[List[Tuple[int, int]]]

class scine_chemoton.gears.elementary_steps.reactive_site_filters.MasmChemicalRankingFilter(prune='None')

Filters atoms by chemical ranking as determined by the Molassembler graph representation. NOTE: Only atoms that pass the atom filtering are considered for the generation of reactive pairs and trial reaction coordinates. Pairs/trial coordinates built from different atoms of the same molecule that are regarded as alike based on the Molassembler graph representation, can, however, be distinct/valid. However, these will not be generated when this filter is applied. Use with care! NOTE: This filter does not have any specific filter methods for pairs and reaction coordinates. The methods of the ReactiveSiteFilter base class will be applied.

prune

Whether to prune by molassembler’s ranking distinct atoms descriptor. Allowed values: ‘None’, ‘Hydrogen’, ‘All’

Type

str

filter_atoms(structure_list, atom_indices)

The blueprint for a filter function, checking a list of atoms regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this function.

• atom_indices ([List[int]]) – The list of atoms to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

result – The list of all relevant atom indices after applying the filter.

Return type

List[int]

class scine_chemoton.gears.elementary_steps.reactive_site_filters.ReactiveSiteFilter

The base and default class for all reactive site filters. The default is to allow/pass all given checks.

ReactiveSiteFilter are optional barriers in Chemoton that allow the user to cut down the exponential growth of the combinatorial explosion. The different subclasses of this main ReactiveSiteFilter allow for a tailored choice of which parts of a molecule to deem reactive.

There are some predefined filters that will be given in Chemoton, however, it should be simple to extend as needed even on a per-project basis. The key element when sub-classing this interface is to override the filter functions as defined here. When sub-classing please be aware that these filters are expected to be called often. Having each call do loops over entire collections is not wise.

For the latter reason, user defined subclasses are intended to be more complex, allowing for non-database stored/cached data across a run. This can be a significant speed-up and allow for more intricate filtering.

The different filter methods are applied in a subsequent matter, i.e., only the atoms that pass the atom filter will be used to construct atom pairs, and only those of the atom pairs that pass the pair filter will be used to construct trial reaction coordinates in the TrialGenerators.

NOTE: Although there is the possibility to apply a filter to many sites / trial coordinates simultaneously, there is no guarantee that all possible sites / coordinates with the specified settings are passed at the same time.

filter_atom_pairs(_, pairs)

The blueprint for a filter function, checking a list of atom pairs regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• pairs (List[Tuple[int, int]]) – The list of atom pairs to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reactive atom pairs (given as atom index pairs) after applying the filter.

Return type

result :: List[Tuple[int, int]]

filter_atoms(_, atom_indices)

The blueprint for a filter function, checking a list of atoms regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this function.

• atom_indices ([List[int]]) – The list of atoms to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

result – The list of all relevant atom indices after applying the filter.

Return type

List[int]

filter_reaction_coordinates(_, coordinates)

The blueprint for a filter function, checking a list of trial reaction coordinates each given as a tuple of reactive atom pairs for their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• coordinates (List[List[Tuple[int, int]]]) – The list of trial reaction coordinates to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reaction coordinates given as tuples of reactive atom pairs after applying the filter.

Return type

result :: List[List[Tuple[int, int]]]

class scine_chemoton.gears.elementary_steps.reactive_site_filters.ReactiveSiteFilterAndArray(filters=None)

An array of logically ‘and’ connected filters.

filters

A list of filters to be combined.

Type

List[ReactiveSiteFilter]

filter_atom_pairs(structure_list, pairs)

The blueprint for a filter function, checking a list of atom pairs regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• pairs (List[Tuple[int, int]]) – The list of atom pairs to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reactive atom pairs (given as atom index pairs) after applying the filter.

Return type

result :: List[Tuple[int, int]]

filter_atoms(structure_list, atom_indices)

The blueprint for a filter function, checking a list of atoms regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this function.

• atom_indices ([List[int]]) – The list of atoms to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

result – The list of all relevant atom indices after applying the filter.

Return type

List[int]

filter_reaction_coordinates(structure_list, coordinates)

The blueprint for a filter function, checking a list of trial reaction coordinates each given as a tuple of reactive atom pairs for their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• coordinates (List[List[Tuple[int, int]]]) – The list of trial reaction coordinates to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reaction coordinates given as tuples of reactive atom pairs after applying the filter.

Return type

result :: List[List[Tuple[int, int]]]

class scine_chemoton.gears.elementary_steps.reactive_site_filters.ReactiveSiteFilterOrArray(filters=None)

An array of logically ‘or’ connected filters.

filters

A list of filters to be combined.

Type

List[ReactiveSiteFilter]

filter_atom_pairs(structure_list, pairs)

The blueprint for a filter function, checking a list of atom pairs regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• pairs (List[Tuple[int, int]]) – The list of atom pairs to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reactive atom pairs (given as atom index pairs) after applying the filter.

Return type

result :: List[Tuple[int, int]]

filter_atoms(structure_list, atom_indices)

The blueprint for a filter function, checking a list of atoms regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this function.

• atom_indices ([List[int]]) – The list of atoms to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

result – The list of all relevant atom indices after applying the filter.

Return type

List[int]

filter_reaction_coordinates(structure_list, coordinates)

The blueprint for a filter function, checking a list of trial reaction coordinates each given as a tuple of reactive atom pairs for their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• coordinates (List[List[Tuple[int, int]]]) – The list of trial reaction coordinates to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reaction coordinates given as tuples of reactive atom pairs after applying the filter.

Return type

result :: List[List[Tuple[int, int]]]

class scine_chemoton.gears.elementary_steps.reactive_site_filters.SimpleRankingFilter(atom_threshold=0, pair_threshold=0, coordinate_threshold=0)

Filters atoms and bonds by a simple ranking algorithm. All atom types are assigned a basic rank/importance, with H being rank 0, C being rank 1, ['N', 'O', 'S', 'P', 'Si'] being rank 2 and all other elements being rank 3. Based on these initial rankings an importance of atoms and bonds is calculated.

For atoms the base rank of them self and all bonded atoms is added to give the final importance. Hence a carbon in CH_4 would rank as 1 and one in CH3OH would rank as 3. The protons in this example would rank 1 and 1, 2.

For atom pairs and coordinates, the ranking of the atoms in the bond is simply added.

atom_threshold

The threshold for the importance of atoms. All atoms ranking above the threshold will be considered for reactions.

Type

int

pair_threshold

The threshold for the importance of atom pairs, All pairs ranking above the threshold will be considered for reactions.

Type

int

coordinate_threshold

The threshold for the importance of trial reaction coordinates, All reaction coordinates ranking above the threshold will be considered for reactions.

Type

int

filter_atom_pairs(structure_list, pairs)

The blueprint for a filter function, checking a list of atom pairs regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• pairs (List[Tuple[int, int]]) – The list of atom pairs to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reactive atom pairs (given as atom index pairs) after applying the filter.

Return type

result :: List[Tuple[int, int]]

filter_atoms(structure_list, atom_indices)

The blueprint for a filter function, checking a list of atoms regarding their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this function.

• atom_indices ([List[int]]) – The list of atoms to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

result – The list of all relevant atom indices after applying the filter.

Return type

List[int]

filter_reaction_coordinates(structure_list, coordinates)

The blueprint for a filter function, checking a list of trial reaction coordinates each given as a tuple of reactive atom pairs for their reactivity as defined by the filter.

Parameters

• _ (List[db.Structure]) – The structures to be checked. Unused in this implementation.

• coordinates (List[List[Tuple[int, int]]]) – The list of trial reaction coordinates to consider. If several structures are listed atom indices are expected to refer to the entity of all structure in the order they are given in the structure list. For example, the first atom of the second structure has the index equalling the number of atoms of the first structure.

Returns

The list of all relevant reaction coordinates given as tuples of reactive atom pairs after applying the filter.

Return type

result :: List[List[Tuple[int, int]]]

Kinetics

class scine_chemoton.gears.kinetics.BasicBarrierHeightKinetics

This Gear enables the exploration of aggregates if they were inserted by the user or created by a reaction that requires only explorable aggregates and has a forward reaction barrier below a given threshold.

options :: BasicBarrierHeightKinetics.Options

The options for the BasicBarrierHeightKinetics Gear.

Notes

Checks for all aggregates that are accessed via a ‘reaction’. Manually inserted Compounds/Flasks are always activated by this gear.

class Options

The options for the BasicBarrierHeightKinetics Gear.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

enforce_free_energies

bool Whether the gear should only enable aggregates based on free energy barriers or can also enable based on electronic energies alone. Make sure to run a Thermo gear if you set this to True.

max_allowed_barrier

float The maximum barrier height of the reaction resulting in the aggregate in kJ/mol to allow the aggregate to be further explored.

model: scine_database.Model

db.Model (Scine::Database::Model) The Model determining the energies for the barrier determination.

restart

bool Option to restart the filtering of the network, by disabling each aggregate again. Set this to True if you want to reevaluate a network with different settings

class scine_chemoton.gears.kinetics.KineticsBase

Base class for kinetics gears.

class Options

The options for the MinimalConnectivityKinetics Gear.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

restart

bool Option to restart the filtering of the network, by disabling all aggregates again. Set this to True if you want to reevaluate a network with different settings.

class scine_chemoton.gears.kinetics.MaximumFluxKinetics

This Gear enables the exploration of compounds if they were inserted by the user, created by a reaction that requires only compounds with a concentration flux larger than a given threshold, has a forward reaction barrier below a given maximum, and has reached a minimum concentration larger than a given threshold during kinetic modeling.

options :: MaximumFluxKinetics.Options

The options for the MaximumFluxKinetics Gear.

Notes

Checks for all compounds that are accessed via a ‘reaction’. Manually inserted Compounds are always activated by this gear.

class Options

The options for the MaximumPopulationKinetics Gear.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

enforce_free_energies

bool Whether the gear should only enable compounds based on free energy barriers or can also enable based on electronic energies alone. Make sure to run a Thermo gear if you set this to True

flux_property_label

str The property label for the concentration flux.

max_allowed_barrier

float The maximum barrier height of the reaction resulting in the compound in kJ/mol to allow the compound to be further explored.

min_allowed_concentration

float The minimum allowed concentration flux to be considered for further exploration.

min_concentration_flux

float The minimum concentration flux that is required to consider the compound as accessible.

model: scine_database.Model

db.Model (Scine::Database::Model) The Model determining the energies for the barrier determination.

property_label

str The label of the concentration property that is used to determine explorable compounds.

restart

bool Option to restart the filtering of the network, by disabling each compound again. Set this to True if you want to reevaluate a network with different settings

class scine_chemoton.gears.kinetics.MinimalConnectivityKinetics

This Gear enables the exploration of aggregates (Compounds and Flasks) if they were inserted by the user or created by a reaction that requires only explorable aggregates. This should be the case for any aggregates after a sufficient number of iterations and simply drive the exploration.

options :: MinimalConnectivityKinetics.Options

The options for the MinimalConnectivityKinetics Gear.

class Options

The options for the MinimalConnectivityKinetics Gear.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

restart

bool Option to restart the filtering of the network, by disabling all aggregates again. Set this to True if you want to reevaluate a network with different settings.

user_input_only

bool Option to only ever allow compounds that contain structures added to the database by a user. If enabled, no other compounds will ever be enabled irrespective of any connectivity.

Pathfinder

class scine_chemoton.gears.pathfinder.Pathfinder(db_manager)

A class to represent a list of reactions as a graph and query this graph for simple paths between two nodes. In a simple path, every node part of the path is visited only once.

_calculations :: db.Collection

Collection of the calculations of the connected database.

_compounds :: db.Collection

Collection of the compounds of the connected database.

_flasks :: db.Collection

Collection of the flasks of the connected database.

_reactions :: db.Collection

Collection of the reactions of the connected database.

_elementary_steps :: db.Collection

Collection of the elementary steps of the connected database.

_structures :: db.Collection

Collection of the structures of the connected database.

_properties :: db.Collection

Collection of the properties of the connected database.

graph_handler

A class handling the construction of the graph. Can be adapted to one’s needs.

_use_old_iterator :: bool

Bool to indicate if the old iterator shall be used querying for paths between a source - target pair.

_unique_iterator_memory :: Tuple[Tuple[List[str], float], Iterator]

Memory of iterator with the corresponding path and its length as well as the iterator.

start_compounds :: List[str]

A list containing the compounds which are present at the start.

start_compounds_set :: bool

Bool to indicate if start_compounds are set.

_pseudo_inf :: float

Float for edges with infinite weight.

compound_costs :: Dict[str, float]

A dictionary containing the cost of the compounds with the compounds as keys.

compound_costs_solved :: bool

Bool to indicate if all compounds have a compound cost.

class BarrierBasedHandler(db_manager, model)

A class derived from the basic graph handler class to encode the reaction barrier information in the edges. The barriers of the elementary step with the minimal TS energy of a reaction are employed. The barriers are converted to rate constants, normalized over all rate constants in the graph and then the cost function \(|log(normalized\ rate\ constant)|\) is applied to obtain the weight.

temperature :: float

The temperature for calculating the rate constants from the barriers. Default is 298.15 K.

_rate_constant_normalization :: float

The factor to normalize the rate constant.

_rxn_to_es_map :: Dict[str, db.ID]

A dictionary holding the ID of the elementary step with the lowest TS energy for each reaction.

get_temperature()

Gets the set temperature.

Returns

The set temperature.

Return type

self.temperature :: float

set_temperature(temperature)

Setting the temperature for determining the rate constants.

Parameters

: (temperature) – float: The temperature in Kelvin.

class BasicHandler(manager, model=None)

A basic class to handle the construction of the nx.DiGraph. A list of reactions can be added differently, depending on the implementation of _get_weight and get_valid_reaction_ids.

graph :: nx.DiGraph

The directed graph.

db_manager :: db.Manager

The database manager for the connected database.

barrierless_weight :: float

The weight to be set for barrierless reactions.

model :: Union[None, db.Model]

A model for filtering the valid reactions. Per default None, reactions are included regardless of the model.

add_reaction(reaction)

Add a reaction to the graph. Each reaction node represents the LHS and RHS. Hence every reagent of a reaction is connected to every product of a reaction via one reaction node.

For instance:

A + B = C + D, reaction R

A -> R₁ -> C

A -> R₁ -> D

B -> R₁ -> C

B -> R₁ -> D

C -> R₂ -> A

C -> R₂ -> B

D -> R₂ -> A

D -> R₂ -> B

Representing this reaction in the graph yields 4 compound nodes, 2 reaction nodes (same reaction) and 16 edges (2*2*2*2). The weights assigned to the edges depends on the _get_weight implementation.

The edges from a compound node to a reaction node contain several information:

weight

the weight of the edge 1.0 if the reaction is not barrierless, otherwise it is set to barrierless_weight

required_compounds

the IDs of the other reagents of this side of the reaction in a list

required_compound_costs

the sum over all compound costs of the compounds in the required_compounds list. None by default.

The edges from a reaction node to a compound node contain several information:

weight

the weight of the edge, set to 0.0

required_compounds

the IDs of the other products emerging; added for easier information extraction during the path analysis

Parameters

: (reaction) – db.Reaction: The reaction to be added to the graph.

get_valid_reaction_ids()

Basic filter function for reactions. Per default it returns all reactions.

Returns

List of IDs of the filtered reactions.

Return type

List[db.ID]

class Options

A class to vary the setup of Pathfinder.

barrierless_weight: float

The weight for barrierless reactions (basic) and rate constant (barrier), respectively.

energy_threshold: float

graph_handler: str

A string indicating which graph handler to be used.

model: Union[None, scine_database.Model]

The model for the compounds to be included.

use_energy_threshold: bool

build_graph()

Build the nx.DiGraph() from a list of filtered reactions.

calculate_compound_costs(recursive=True)

Determine the cost for all compounds via determining their shortest paths from the start_compounds. If this succeeds, set compound_costs_solved to True. Otherwise it stays False.

The algorithm works as follows: Given the starting conditions, one loops over the individual starting compounds as long as:

• the _pseudo_inf entries in compound_costs are reduced

• for any entry in compounds_cost a lower cost is found

With each starting compound, one loops over compounds which have yet no cost assigned. For each start - target compound pair, the shortest path is determined employing Dijkstra’s algorithm. The weight function checks the weight of the edges as well as the costs of the required compounds listed in the required_compounds of the traversed edges. If the path exceeds the length of self._pseudo_inf, this path is not considered for further evaluation. The weight of the starting compound is added to the tmp_cost. If the target compound has no weight assigned yet in compound_costs OR if the target compound has a weight assigned which is larger (in compound_costs as well as in tmp_compound_costs) than the current tmp_cost is written to the temporary storage of tmp_compound_costs.

After the loop over all starting compounds completes, the collected costs for the found targets are written to compound_costs. The convergence variables are updated and the while loop continues.

Notes

• Checks if the start compounds are set.

• Checks if the graph contains any nodes.

Parameters

: (recursive) – bool: All compounds are checked for shorter paths, True by default. If set to False, compounds for which a cost has been determined are not checked in the next loop.

find_paths(source, target, n_requested_paths=3, n_skipped_paths=0)

Query the build graph for simple paths between a source and target node.

Notes

Requires a built graph

Parameters

• source (str) – The ID of the starting compound as string.

• target (str) – The ID of the targeted compound as string.

• n_requested_paths (int) – Number of requested paths, by default 3

• n_skipped_paths (int) – Number of skipped paths from, by default 0. For example, when four paths are found (n_requested_paths=4) and n_skipped_paths=2, the third, fourth, fifth and sixth path are returned. Therefore, this allows to set the starting point of the query.

Returns

List of paths where each item (path) consists of the list of nodes of the path and its length.

Return type

found_paths :: List[Tuple[List[str] float]]

find_unique_paths(source, target, number=3)

Find a unique number of paths from a given source node to a given target node. Paths can have the same total length (in terms of sum over edge weights), but if one is solely interested in one path of paths with identical length, the shortest (in terms of length) longest (in terms of number of nodes) path is returned. This is called the unique path (shortest longest path).

Notes

- Checks if a stored iterator for the given source-target pair should be used.

- Maximal ten paths with identical length are compared.

Parameters

• source (str) – The ID of the starting compound as string.

• target (str) – The ID of the targeted compound as string.

• number (int) – The number of unique paths to be returned. Per default, 3 paths are returned.

Returns

List of paths where each item (path) consists the list of nodes of the path and its length.

Return type

path_tuple_list :: List[Tuple[List[str], float]]

get_elementary_step_sequence(path)

Prints the sequence of elementary steps of a path with the compounds written as molecular formulas with multiplicity and charge as well as the final cost of the path. Reactant node is printed in red, product node in blue to enhance readability.

Parameters

: (path) – Tuple[List[str] float]: Path containing a list of the traversed nodes and the cost of this path.

Return type

str

static get_valid_graph_handler_options()

Return type

List[str]

set_start_conditions(conditions)

Add the IDs of the start compounds to self.start_compounds and add entries for cost in self.compound_cost.

Parameters

: (conditions) – Dict[str float]: The IDs of the compounds as keys and its given cost as values.

update_graph_compound_costs()

Update the ‘weight’ of edges from compound to reaction nodes by adding the compound costs. The compound costs are the sum over the costs stored in self.compound_costs of the required compounds. The edges of the resulting graph contain a weight including the required_compound_costs based on the starting conditions. All analysis of the graph therefore depend on the starting conditions.

Notes

• Checks if the compound costs have successfully been determined.

Reaction Sorting

class scine_chemoton.gears.reaction.BasicReactionHousekeeping

This Gear updates all Elementary Steps stored in the database such that they are added to an existing Reaction or that a new Reaction is created if the Step does not fit an existing one.

options :: BasicReactionHousekeeping.Options

The options for the BasicReactionHousekeeping Gear.

Notes

Checks for all Elementary Steps without a ‘reaction’.

class Options

The options for the BasicReactionHousekeeping Gear.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

energy_tolerance

float The energy tolerance for the transition state energy deduplication.

rmsd_tolerance

float The RMSD tolerance for the transition state RMSD deduplication.

use_energy_deduplication

bool If true duplicated elementary steps are not sorted into reactions. The criterion is that the total electronic energy of the transition state (if available) has to be within the threshold limits of energy_tolerance. This criterion can be combined with other selection criteria. Steps are only eliminated if all selection criteria signal identical steps.

use_rmsd_deduplication

bool If true duplicated elementary steps are not sorted into reactions. The criterion is that the RMSD of the transition state coordinates (if available) have to be within the threshold limits of rmsd_tolerance. This criterion can be combined with other selection criteria. Steps are only eliminated if all selection criteria signal identical steps. Note that this deduplication strategy may fail to eliminate elementary steps if the atom ordering the transition state differs.

use_structure_deduplication

bool If true duplicated elementary steps are not sorted into reactions. The criterion is that all structures on the lhs of the elementary step have to be identical. This criterion can be combined with other selection criteria. Steps are only eliminated if all selection criteria signal identical steps.

Network Refinement

class scine_chemoton.gears.refinement.NetworkRefinement

This Gear can improve an existing network built with some model (e.g., semi-empirics) with additional calculations with a different model (e.g., DFT). The level of refinement is determined via its options.

options :: NetworkRefinement.Options

The options for the NetworkRefinement Gear.

Notes

Six different levels of refinement:

‘refine_single_points’:

New single point calculations for all minima and TS in the network with the refinement model

‘refine_optimizations’

New optimizations of all minima and TS in the network with the refinement model. Minima are checked via the CompoundGear to be within the same compound TS should be checked for validity with an IRC within the optimization job in Puffin

‘double_ended_refinement’

Check successful single ended react jobs and try to find a TS for these reactions with a double ended search

‘double_ended_new_connections’

Check structures of same PES without a unimolecular reaction combining their compounds to be connected via a double ended search. This can also be done with the same model with which the structures were generated.

‘refine_single_ended_search’

Perform single ended searches again with the refinement model, if they were already successful with a different model. Equality of products is not checked.

‘refine_structures_and_irc’

Perform single ended searches again starting with the transition state of the previous transition state search.

class Options

The options for the NetworkRefinement Gear.

caching_file_name

str The name of the file used to save the already considered calculation ids.

calculation_model: scine_database.Model

db.Model The model used for the loop over previous calculations. This is only used if use_calculation_model is True.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

double_ended_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for searching for a transition state between two compounds. The default is: the ‘scine_react_double_ended’ order on a single core.

double_ended_job_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings for searching for a transition state between two compounds. Empty by default.

exclude_barrierless

bool If true, barrier-less reactions/elementary steps are not refined.

jobs_to_wait_for

List[str] Wait for these jobs to finish for each reaction before setting up reaction-wise refinement calculations.

max_barrier: float

float Maximum electronic energy barrier in kJ/mol for which elementary reaction steps are refined if structures_on_elementary_steps = True.

opt_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for optimizing all minima. The default is: the ‘scine_geometry_optimization’ order on a single core.

opt_job_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings for optimizing all minima. Empty by default.

post_refine_model: scine_database.Model

db.Model (Scine::Database::Model) The Model used for the refinement The default is: DFT

pre_refine_model: scine_database.Model

db.Model (Scine::Database::Model) The Model that indicates that the structure(s) and/or calculation(s) should be refined The default is: PM6

reaction_based_loop

bool If true, the elementary steps are traversed reaction wise and the elementary steps that are refined can be narrowed down by the transition_state_energy_window, e.g., transition states with an energy higher than this window with respect to the lowest energy transition state for the reaction are not considered.

refinements: Dict[str, bool]

Dict[str, bool] A dictionary specifying the wanted refinement(s) ‘refine_single_points’: Calculate energies of all minima and transition states if they belong to a calculation that produced an elementary step with a barrier less than ‘max_barrier’. The job for the calculations can be selected with ‘options.sp_job’ and its settings with ‘options.sp_job_settings’. ‘refine_optimizations’: Perform optimizations of minima and transition states. The same maximum barrier condition applies as for ‘refine_single_points’. The job for the minima optimizations can be selected with ‘options.opt_job’ and its settings with ‘options.opt_job_settings’. The job for the transition state optimizations can be selected with ‘options.tsopt_job’ and its settings with ‘options.tsopt_job_settings’. ‘double_ended_refinement’: Perform double ended TS searches for compounds that are connected. The ‘max_barrier’ conditions applies as above. The job for this search can be selected with ‘options.double_ended_job’ and its settings with ‘options.double_ended_job_settings’. ‘double_ended_new_connections’: Perform double ended TS searches for compounds that might be connected. The job for this search can be selected with ‘options.double_ended_job’ and its settings with ‘options.double_ended_job_settings’. ‘refine_single_ended_search’: Perform single ended searches again with new model if they were already successful with another model. The ‘max_barrier’ conditions applies as above. The job for this search can be selected with ‘options.single_ended_job’ and its settings with ‘options.single_ended_job_settings’. ‘refine_structures_and_irc’: Reoptimize an elementary step that was found previously. The previous transition state is used as an initial guess. A complete IRC is performed. The ‘max_barrier’ conditions applies as above. The job for this search can be selected with ‘options.single_ended_step_refinement_job’ and its settings with ‘options.single_ended_step_refinement_settings’.

single_ended_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for searching for redoing previously successful single ended searches. The default is: the ‘scine_react_complex_nt’ order on a single core. This job implies the approximation that the structures of the old model can be used for the single ended calculation with the new model.

single_ended_job_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings for single ended reaction search. Empty by default.

single_ended_step_refinement_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for searching for refining previously successful single ended searches. The default is: the ‘scine_step_refinement’ order.

single_ended_step_refinement_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings for refining single ended reaction searches. Empty by default.

sp_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for calculating new single point energies. The default is: the ‘scine_single_point’ order on a single core.

sp_job_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings for calculating new single point energies. Empty by default.

transition_state_energy_window

float Energy window for the elementary step selection in kJ/mol for reaction based refinement (see reaction_based_loop).

tsopt_job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for optimizing all transition states. The default is: the ‘scine_ts_optimization’ order on a single core.

tsopt_job_settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings for optimizing all transition states. Empty by default.

use_calculation_model

bool If true, the option calculation_model is used for the loop over previous calculations.

Job Scheduling

class scine_chemoton.gears.scheduler.Scheduler

This Gear is a basic scheduler for all calculations stored in the database. By default, all Calculations generated by other Gears will be set to ‘hold’ upon creation. The scheduler will then, based on the given options, add them to the queue of Calculations run by the backend (Puffins).

options :: Scheduler.Options

The options for the Scheduler Gear.

Notes

The logic counts the number of active Calculations per Order and compares with the allowed number of active Calculations. The gap between these numbers will be closed by activating Calculations that are currently on hold. The order of the execution of the jobs as well as their activation does not necessarily follow the chronological order of their generation.

class Options

The options for the Scheduler Gear.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

job_counts: Dict[str, int]

Dict[str, int] The number of Calculations to be set to run at any given time. Counts are given per order type (i.e. ‘scine_hessian’). Defaults are: scine_geometry_optimization: 50, scine_bond_orders: 50, graph: 100, scine_hessian: 10, scine_react_complex: 10, conformers: 2

job_priorities: Dict[str, int]

Dict[str, int] The priority number of Calculations, which determines which are executed first. Priorities are given per order type (i.e. ‘scine_hessian’). A lower number corresponds to earlier execution. The possible range of numbers is 1 to 10. Defaults are: scine_geometry_optimization: 2, scine_bond_orders: 2, graph: 2, scine_hessian: 2, scine_react_complex: 5, conformers: 2

Thermodynamic Data Generation

class scine_chemoton.gears.thermo.BasicThermoDataCompletion

This Gear will autocomplete the thermochemistry data for optimized minimum energy structures and optimized transition states.

options :: BasicThermoDataCompletion.Options

The options for the BasicThermoDataCompletion Gear.

Notes

The logic checks for ‘user_optimized’, ‘minimum_optimized’ and ‘ts_optimized’ structures. For the optimized minima only those assigned to a compound will be queried. If no ‘gibbs_energy_correction’ with the given model is present, then a calculation generating that data is set up (on hold).

class Options

The options for the BasicThermoDataCompletion Gear.

cycle_time

int The minimum number of seconds between two cycles of the Gear. Cycles are finished independent of this option, thus if a cycle takes longer than the cycle_time will effectively lead to longer cycle times and not cause multiple cycles of the same Gear.

job: scine_database.Job

db.Job (Scine::Database::Calculation::Job) The Job used for the Hessian/thermo chemistry calculations. The default is: the ‘scine_hessian’ order on a single core.

model: scine_database.Model

db.Model (Scine::Database::Model) The Model used for the Hessian/thermo chemistry calculations. The default is: PM6 using Sparrow.

settings: scine_utilities.ValueCollection

utils.ValueCollection Additional settings passed to the Hessian/thermo chemistry calculations. Empty by default.