scine_puffin.jobs.scine_react_complex_nt¶

Classes

ScineReactComplexNt()

A job that tries to force a reaction, given a reactive complex and its parts.

class scine_puffin.jobs.scine_react_complex_nt.ScineReactComplexNt[source]¶

A job that tries to force a reaction, given a reactive complex and its parts. The reactive complex is expected to be generated as two structures placed next to one another. The job then forces groups of atoms onto or away from one another and analyzes the resulting structure(s) when relaxing. Only one pair of atom groups is allowed, and only repulsion or attraction of said groups can be screened at a time.

The list of calculations/steps done is the following:

Set up of a reactive complex based on the given specifications

Enforce collision of structure (NT optimization), and extraction of a transition state (TS) guess

Optimization of the TS guess to the actual TS.

Hessian calculation of the TS structure

Validate the TS using a combination of IRC scan and optimization of the resulting structures.

Check if the IRC generated the input on one side and a new set of structures on the other side of the TS.

Optimize the products separately.

Store the new elementary step in the database.

Order Name

scine_react_complex_nt

Required Input

The reactive complex (the structures it is made from) has to be defined in the list of structures handed to the task. If only one structure is provided, an intramolecular reaction is set up. Furthermore, the reactive sites in the complex that shall be pressed onto one another need to be given using:

nt_nt_rhs_listint: This specifies list of indices of atoms to be forced onto or away from those in the LHS list.
nt_nt_lhs_listint: This specifies list of indices of atoms to be forced onto or away from those in the RHS list.

Optional Settings

Optional settings are read from the settings field, which is part of any Calculation stored in a SCINE Database. All possible settings for this job are based on those available in SCINE Readuct. For a complete list see the ReaDuct manual

Given that this job does more than one, in fact many separate calculations it is possible to target each individually with the settings. In order to achieve this each regular setting, such as convergence_max_iterations has to be prepended with a tag, identifying which part of the job it is meant to impact. If the setting is meant to be added to the IRC scan at the end of this job irc_convergence_max_iterations should be used. Note that this may include a doubling of this style of flags, as Readuct uses a similar way of sorting options. Hence, choosing a none default irc_mode in this task has to be done using irc_irc_mode.

The complete list prefixes for specific settings for the steps listed at the start of this section is:

Reactive complex generation rc_*

Newton trajectory scan: nt_*

TS optimization: tsopt_*

Validation using an IRC scan: irc_*

Optimization of the structures obtained with the IRC scan : ircopt_*

Analyze supersystem, derive individual products and assign charges: sp_*

Optimization of new products: opt_*

(Optional) optimization of the reactive complex: rcopt_*

The following options are available for the reactive complex generation:

rc_x_alignment_0List[float], length=9: In case of two structures building the reactive complex, this option describes a rotation of the first structure (index 0) that aligns the reaction coordinate along the x-axis (pointing towards +x). The rotation assumes that the geometric mean position of all atoms in the reactive site (nt_lhs_list) is shifted into the origin.
rc_x_alignment_1List[float], length=9: In case of two structures building the reactive complex, this option describes a rotation of the second structure (index 1) that aligns the reaction coordinate along the x-axis (pointing towards -x). The rotation assumes that the geometric mean position of all atoms in the reactive site (nt_rhs_list) is shifted into the origin.
rc_x_rotationfloat: In case of two structures building the reactive complex, this option describes a rotation angle around the x-axis of one of the two structures after rc_x_alignment_0 and rc_x_alignment_1 have been applied.
rc_x_spreadfloat: In case of two structures building the reactive complex, this option gives the distance by which the two structures are moved apart along the x-axis after rc_x_alignment_0, rc_x_alignment_1, and rc_x_rotation have been applied.
rc_displacementfloat: In case of two structures building the reactive complex, this option adds a random displacement to all atoms (random direction, random length). The maximum length of this displacement (per atom) is set to be the value of this option.
rc_spin_multiplicityint: This option sets the spin_multiplicity of the reactive complex. In case this is not given the spin_multiplicity of the initial structure or minimal possible spin of the two initial structures is used.
rc_molecular_chargeint: This option sets the molecular_charge of the reactive complex. In case this is not given the molecular_charge of the initial structure or sum of the charges of the initial structures is used. Note: If you set the rc_molecular_charge to a value different from the sum of the start structures charges the possibly resulting elementary steps will never be balanced but include removal or addition of electrons.
rc_minimal_spin_multiplicitybool: True: The total spin multiplicity in a bimolecular reaction is based on the assumption of total spin recombination (s + t = s; t + t = s; d + s = d; d + t = d) False: No spin recombination is assumed (s + t = t; t + t = quin; d + s = d; d + t = quar) (default: False)

The following options are available for the analysis of the single points of the optimized supersystems:

expect_charge_separationbool: If true, fragment charges are no longer determined by rounding, i.e, if a product consists of multiple molecules (according to its graph), the charges are determined initially by rounding. However, then the residual (the difference of the integrated charge to the rounded one) is checked against <charge_separation_threshold>. If this residual exceeds the charge separation threshold, the charge is increased/lowered by one according to its sign. This is especially useful if a clear charge separation only occurs upon separation of the molecules which is often the case for DFT-based descriptions of the electronic structure. (default: False)
charge_separation_thresholdfloat: The threshold for the charge separation (vide supra). (default: 0.4)

The following settings are recognized without a prepending flag:

add_based_on_distance_connectivitybool: Whether to add the connectivity (i.e. add bonds) as derived from atomic distances when graphs are generated. (default: True)
sub_based_on_distance_connectivitybool: Whether to subtract the connectivity (i.e. remove bonds) as derived from atomic distances when graphs are generated. (default: True)
only_distance_connectivitybool: Whether to impose the connectivity solely from distances. (default: False)
imaginary_wavenumber_thresholdfloat: Threshold value in inverse centimeters below which a wavenumber is considered as imaginary when the transition state is analyzed. Negative numbers are interpreted as imaginary. (default: 0.0)
spin_propensity_checkint: The range to check for possible multiplicities for products. A value of 2 (default) will check triplet and quintet for a singlet and will check singlet, quintet und septet for triplet.
allow_exhaustive_product_decompositionbool: Whether to allow the decomposition of the new products of a complex into further sub-products, e.g. of the complex A+B, the product B further decomposes during the optimization of new products to C and D. Might ignore possible elementary steps (the formation of B from C and D), hence the option should be activated with care. (default: False)

Additionally all settings that are recognized by the SCF program chosen. are also available. These settings are not required to be prepended with any flag.

Common examples are:

max_scf_iterationsint: The number of allowed SCF cycles until convergence.

Required Packages

SCINE: Database (present by default)
SCINE: molassembler (present by default)
SCINE: Readuct (present by default)
SCINE: Utils (present by default)
A program implementing the SCINE Calculator interface, e.g. Sparrow

Generated Data

If successful (technically and chemically) the following data will be generated and added to the database:

Elementary Steps: If found, a single new elementary step with the associated transition state will be added to the database.
Structures: The transition state (TS) and also the separated products will be added to the database.
Properties: The hessian (DenseMatrixProperty), frequencies (VectorProperty), normal_modes (DenseMatrixProperty), gibbs_energy_correction (NumberProperty) and gibbs_free_energy (NumberProperty) of the TS will be provided. The electronic_energy associated with the TS structure and each of the products will be added to the database.

add_graph(structure: db.Structure, bond_orders: utils.BondOrderCollection, surface_indices: List[int] | Set[int] | None = None) → None¶

Add molassembler graph information to a Database structure based on the given bond orders.

Parameters:

structureUnion[utils.AtomCollection, db.Structure]: Either an AtomCollection or a structure for which distance based bond orders are constructed.
bond_ordersutils.BondOrderCollection (Scine::Utilities::BondOrderCollection): The bond orders of the structure.
surface_indicesOptional[Union[List[int], Set[int]]]: The indices of the atoms for which the rules of solid state atoms shall be applied.

analyze_side(input_name: str, initial_charge: int, opt_name: str, calculator_settings: utils.Settings) → Tuple[str, List[int], List[str], List[str]] | Tuple[None, None, None, None]¶

archive(archive: str) → None¶

Archives all files existent in the job’s directory into tarball named with the job’s ID. The tarball is then moved to the given destination.

Parameters:

archivestr: The path to move the resulting tarball to.

static bond_orders_from_db_bond_orders(structure: db.Structure, db_bond_orders: db.SparseMatrixProperty) → utils.BondOrderCollection¶

A shortcut to construct a BondOrderCollection from a Database Property holding bond orders.

Returns:

bond_ordersutils.BondOrderCollection (Scine::Utilities::BondOrderCollection): The bond orders of the structure.

build_reactive_complex(settings_manager: SettingsManager) → utils.AtomCollection¶

Aligns the structure(s) to form a reactive complex and returns the AtomCollection. In case of multiple structures, the active site settings are modified to reflect the correct index in the supermolecule. Some ‘start’ information is saved in class members as well.

Parameters:

settings_managerSettingsManager: The settings_manager in which the charge and multiplicity of the new atoms are set.

Returns:

reactive_complexutils.AtomCollection (Scine::Utilities::AtomCollection): The atoms of the reactive complex

Notes

Requires run configuration
May throw exception

calculation_postprocessing(success: bool, systems: Dict[str, utils.core.Calculator | None], keys: List[str], expected_results: List[str] | None = None) → db.Results¶

Performs a verification protocol that a Scine Calculation was successful. If not throws an exception, if yes, the model is updated and the cleared db.Results object of the configured calculation is returned to be added with actual results.

Parameters:

successbool: Whether the calculation was successful (either forwarded from readuct task or specified if not relevant).
systemsDict[str, utils.core.Calculator] (Scine::Core::Calculator): The dictionary holding calculators.
keysList[str]: The list of keys of the systems dict to be checked.
expected_resultsOptional[List[str]]: The results to be required to be present in systems to qualify as successful calculations. If None is given, this defaults to the expected results of the class, see expected_results().

Notes

Requires run configuration
May throw Exception

capture_raw_output() → Tuple[str, str]¶

Tries to capture the raw output of the calculation context and save it in the raw_output field of the configured calculation. This should never throw.

Notes

Requires run configuration

classmethod check_configuration(instance: T) → typing_extensions.TypeGuard[T]¶

static check_duplicate_property(structure: db.Structure, properties: db.Collection, property_name: str, model: db.Model) → db.ID | bool¶

Checks for a property that is an exact match for the one queried here. Exact match meaning that key and model both are matches.

Parameters:

propertiesdb.Collection (Scine::Database::Collection): The collection housing all properties.
property_namestr: The name (key) of the queried property, e.g. electronic_energy.
modeldb.Model (Scine::Database::Model): The model used in the calculation that resulted in this property.
structuredb.Structure (Scine::Database::Structure): The structure to be checked in. The structure has to be linked to its collection.

Returns:

IDdb.ID (Scine::Database::ID): Returns False if there is no existing property like the one queried or the ID of the first duplicate.

check_for_barrierless_reaction() → Tuple[str, List[str]] | Tuple[None, None]¶

Optimizes the reactive complex, comparing the result to the start structures determining if a barrierless reaction occurred.

Returns:

rc_opt_graphOptional[str]: Sorted molassembler cbor graphs separated by semicolons of the reaction product if there was any.
rc_opt_decision_listsOptional[List[str]]: Molassembler decision lists for free dihedrals of the reaction product if there was any.

check_structures(start_structures: List[db.ID] | None = None) → db.Structure¶

Perform sanity check whether we only have 1 or 2 structures in the configured calculation. Return a possible reference structure (the largest one) for the construction of a ProgramHelper.

Parameters:

start_structuresList[db.ID]: If given, this structure id list is used instead of the list given in self._calculation.get_structures().

Returns:

ref_structuredb.Structure (Scine::Database::Structure): The largest structure of the calculation.

Notes

Requires run configuration
May throw exception

clear() → None¶: Clears the directory in which the job was run.

complete_job() → None¶: Saves the executing Puffin, changes status to db.Status.COMPLETE.

config: Configuration¶

configure_run(manager: db.Manager, calculation: db.Calculation, config: Configuration) → None¶

Configures a job for a given Calculation to do tasks in the run function

Parameters:

managerdb.Manager (Scine::Database::Manager): The manager of the database holding all collections
calculationdb.Calculation (Scine::Database::Calculation): The calculation to be performed
configConfiguration: The configuration of the Puffin doing the job

connectivity_settings_from_only_connectivity_settings() → None¶

Overwrite default connectivity settings based on settings of configured Calculation and expect no other settings to be present. Throws if there are other settings present.

Notes

Requires run configuration
May throw exception

create_helpers(structure: db.Structure) → Tuple[SettingsManager, ProgramHelper | None]¶

Creates a Scine SettingsManager and ProgramHelper based on the configured job and the given structure. The ProgramHelper is None if no ProgramHelper is specified for the specified program or no program was specified in the model

Parameters:

structuredb.Structure (Scine::Database::Structure): The structure on which a Calculation is performed.

Returns:

helper_tupleTuple[SettingsManager, Optional[ProgramHelper]: A tuple of the SettingsManager for Scine Calculators and ProgramHelper if available.

Notes

Requires run configuration

create_new_structure(calculator: utils.core.Calculator, label: db.Label) → db.Structure¶

Add a new structure to the database based on the given calculator and label.

Parameters:

calculatorutils.core.Calculator: The calculator holding the optimized structure
labeldb.Label: The label of the new structure

Returns:

db.Structure: The new structure

Notes

Requires run configuration

determine_new_label(old_label: db.Label, graph: str, is_surface: bool, ignore_user_label: bool = False) → db.Label¶

Derive the label of an optimized structure based on the previous label and the Molassembler graph.

Parameters:

old_labeldb.Label: The label which the structure had previous to optimization
graphstr: The graph of the structure
is_surfacebool: Whether the structure is a surface
ignore_user_labelbool: Whether the user label of the given structure shall be ignored. If True, an input structure ‘user_guess’ will get an optimized structure with ‘minimum_optimized’

Returns:

new_labeldb.Label: The label of the optimized structure

Notes

May throw exception

determine_pes_of_rc(settings_manager: SettingsManager, s0: db.Structure, s1: db.Structure | None = None) → None¶

Set charge and spin multiplicity within the settings_manager based on the reaction type (uni- vs. bimolecular) and the given settings for the reactive complex.

Parameters:

settings_managerSettingsManager: The settings_manager in which the charge and multiplicity of the new atoms are set.
s0db.Structure (Scine::Database::Structure): A structure of the configured calculation
s1Union[db.Structure, None]: A potential second structure for bimolecular reactions

Notes

Requires run configuration

distance_bond_orders(structure: db.Structure | utils.AtomCollection, surface_indices: List[int] | Set[int] | None = None) → utils.BondOrderCollection¶

Construct bond order solely based on distance for either an AtomCollection or a Database Structure.

Parameters:

structureUnion[utils.AtomCollection, db.Structure]: Either an AtomCollection or a structure for which distance based bond orders are constructed.
surface_indicesOptional[Union[List[int], Set[int]]]: The indices of the atoms for which the rules of solid state atoms shall be applied.

Returns:

bond_ordersutils.BondOrderCollection (Scine::Utilties::BondOrderCollection): The bond orders of the structure.

Notes

Requires run configuration
May throw exception

classmethod expected_results() → List[str]¶

Gives a list of str specifying the results expected to be present for a system within a job based on the class member and all its parents.

Returns:

expected_resultsList[str]: The results to be expected as str corresponding to the members of the Scine::Utils::Results class.

expected_results_check(systems: Dict[str, utils.core.Calculator | None], keys: List[str], expected_results: List[str] | None = None) → Tuple[bool, str]¶

Checks the results of the given systems based on the expected results. If the expected results are not given, they default to the expected results of the class, see expected_results(). Throws exception if expected result is not present.

Parameters:

systemsDict[str, Optional[utils.core.Calculator]] (Scine::Core::Calculator): The dictionary holding calculators.
keysList[str]: The list of keys of the systems dict to be checked.
expected_resultsOptional[List[str]]: The results to be required to be present in systems to qualify as successful calculations. If None is given, this defaults to the expected results of the class, see expected_results().

Returns:

Tuple[bool, str]: Whether the results are correct and an error message, describing failure in expected results.

Notes

Requires run configuration
May throw Exception

extract_connectivity_settings_from_dict(dictionary: Dict[str, Any]) → None¶: Overwrite default connectivity settings based on given dictionary and removes those from the dictionary.

fail_job() → None¶: Saves the executing Puffin, changes status to db.Status.FAILED.

failed_file() → str¶: Returns the path to the file indicating a failed calculation, None if job has not been prepared

generate_spline(trajectory: utils.MolecularTrajectory, ts_index: int, n_fit_points: int = 23, degree: int = 3) → utils.bsplines.TrajectorySpline¶

Using the transition state, IRC and IRC optimization outputs generates a spline that describes the trajectory of the elementary step, fitting both atom positions and energy. Removes all structures that have a higher energy than the transition state.

Parameters:

trajectoryutils.MolecularTrajectory: The trajectory of the elementary step.
ts_indexint: The index of the transition state in the trajectory.
n_fit_pointsstr: Number of fit points to use in the spline compression.
degreestr: Fit degree to use in the spline generation.

Returns:

splineutils.bsplines.TrajectorySpline: The fitted spline of the elementary step trajectory.

Notes

May throw exception

get_calc(name: str, systems: Dict[str, utils.core.Calculator | None]) → utils.core.Calculator¶

Get a calculator from the given map and ensures the system is present

Parameters:

namestr: The name of the system to get
systemsDict[str, Optional[utils.core.Calculator]]: The map of systems

Returns:

utils.core.Calculator: The calculator

Notes

May throw exception

get_calculation() → db.Calculation¶

Getter for the current calculation. Throws if not configured.

Returns:

calculationdb.Calculation (Scine::Database::Calculation): The current calculation being carried out.

Notes

Requires run configuration
May throw Exception

static get_charge(calculator: utils.core.Calculator) → int¶

Get the molecular charge of a calculator’s settings.

Parameters:

calculatorutils.core.Calculator: The calculator

Returns:

int: The molecular charge

get_energy(calculator: utils.core.Calculator) → float¶

Get the energy of a calculator’s results.

Parameters:

calculatorutils.core.Calculator: The calculator

Returns:

float: The energy

get_graph_charges_multiplicities(name: str, total_charge: int, total_system_name: str | None = None, split_index: int | None = None) → Tuple[List[utils.AtomCollection], str, List[int], List[int], List[str]]¶

Runs bond orders for the specified name in the dictionary of systems, constructs the resulting graphs and splits the system into the corresponding molecules. Computes the charges of each molecule from partial charges and the corresponding minimal spin. All resulting lists are sorted according to the graphs and, if these are equal, according to the charges.

Parameters:

namestr: Index into systems dictionary to calculate bond orders for
total_chargestr: The charge of the system
total_system_namestr: The name of the total system which can be specified in case this method is called for a partial system. This can enable to assign the indices of the total system to the indices of the partial system.
split_indexint: The index of the system in the total system which is split. This is used to assign the indices of the total system to the indices of the partial system. Both total_system_name and split_index must be specified or neither must be specified.

Returns:

ordered_structuresList[utils.AtomCollection]: List of atom collections corresponding to the split molecules.
graph_stringstr: Sorted molassembler cbor graphs separated by semicolons.
chargesList[int]: Charges of the molecules.
multiplicitiesList[int]: Multiplicities of the molecules, total multiplicity before split influences these returned values based on a buff spread over all split structures, these values have to be checked with spin propensity checks
decision_listsList[str]: Molassembler decision lists for free dihedrals

Notes

Requires run configuration
May throw exception

static get_multiplicity(calculator: utils.core.Calculator) → int¶

Get the spin multiplicity of a calculator’s settings. Return 0 if the setting is not present.

Parameters:

calculatorutils.core.Calculator: The calculator

Returns:

int: The molecular charge

get_system(name: str) → utils.core.Calculator¶

Get a calculator from the system map by name and ensures the system is present

Parameters:

namestr: The name of the system to get

Notes

May throw exception

irc_sanity_checks_and_analyze_sides(initial_charge: int, check_charges: bool, inputs: List[str], calculator_settings: utils.Settings) → Tuple[List[str], List[str] | None] | Tuple[None, None]¶

Check whether we found a new structure, whether our IRC matches the start (and end in case of double ended). This decision is made based on optimized structures of the separated molecules taken from IRC endpoints. Both starting structures and products are assigned, starting structure names are returned only if they do not match the conformers of the initial input.

Parameters:

initial_chargeint: The charge of the reactive complex
check_chargesbool: Whether the charges must be checked
inputsList[str]: The name of the IRC outputs to use as inputs
calculator_settingsutils.Settings: The general settings for the Scine calculator. Charge and spin multiplicity will be overwritten.

Returns:

product_namesOptional[List[str]]: A list of the access keys to the products in the system map.
start_namesOptional[List[str]]: A list of the access keys to the starting materials in the system map.

Notes

Requires run configuration
May throw exception

make_bond_orders_from_calc(systems: Dict[str, utils.core.Calculator | None], key: str, surface_indices: List[int] | Set[int] | None = None) → Tuple[utils.BondOrderCollection, Dict[str, utils.core.Calculator | None]]¶

Gives bond orders for the specified system based on the connectivity settings of this class.

Parameters:

systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them
keystr: Index into systems dictionary to get bond orders for
surface_indicesOptional[Union[List[int], Set[int]]]: The indices of the atoms for which the rules of solid state atoms shall be applied.

Returns:

bond_ordersutils.BondOrderCollection (Scine::Utilties::BondOrderCollection): The bond orders of the system
systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them, updated with the results of the single point calculation requesting bond orders.

Notes

Requires run configuration
May throw exception

make_decision_lists_from_calc(systems: Dict[str, utils.core.Calculator | None], key: str, surface_indices: List[int] | Set[int] | None = None) → Tuple[List[str], Dict[str, utils.core.Calculator | None]]¶

Calculates bond orders for the specified name in the dictionary of systems if not present already. Then generates and returns the decision lists.

Parameters:

systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them
keystr: Index into systems dictionary to get bond orders for
surface_indicesOptional[Union[List[int], Set[int]]]: The indices of the atoms for which the rules of solid state atoms shall be applied.

Returns:

decision_listsList[str]: Decision lists per molecule in structure.
systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them, updated with the results of a possible single point calculation requesting bond orders.

Notes

Requires run configuration
May throw exception

make_graph_from_calc(systems: Dict[str, utils.core.Calculator | None], key: str, surface_indices: List[int] | Set[int] | None = None) → Tuple[str, Dict[str, utils.core.Calculator | None]]¶

Runs bond orders for the specified name in the dictionary of systems if not present already and return cbor graph for based on them.

Parameters:

systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them
keystr: Index into systems dictionary to get bond orders for
surface_indicesOptional[Union[List[int], Set[int]]]: The indices of the atoms for which the rules of solid state atoms shall be applied.

Returns:

graph_cborstr: Serialized representation of interpreted molassembler molecule.
systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them,

Notes

Requires run configuration
May throw exception

make_masm_result_from_calc(systems: Dict[str, utils.core.Calculator | None], key: str, unimportant_atoms: List[int] | Set[int] | None) → Tuple[masm.interpret.MoleculesResult, Dict[str, utils.core.Calculator | None]]¶

Gives Molassembler interpret result for the specified system based on the connectivity settings of this class.

Parameters:

systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them
keystr: Index into systems dictionary to get bond orders for
unimportant_atomsOptional[Union[List[int], Set[int]]]: The indices of atoms for which no stereopermutators shall be determined.

Returns:

masm_resultmasm.interpret.MoleculesResult (Scine::Molassembler::interpret::MoleculesResult): The interpretation result
systemsDict[str, Optional[utils.core.Calculator]]: Dictionary of system names to calculators representing them, updated with the results of the single point calculation requesting bond orders.

Notes

Requires run configuration
May throw exception

n_imag_frequencies(name: str) → int¶

A helper function to count the number of imaginary frequencies based on the threshold in the settings. Does not carry out safety checks.

Parameters:

namestr: The name of the system which holds Hessian results.

Notes

May throw exception (system not present)

observed_readuct_call(task: SubTaskToReaductCall, systems: Dict[str, utils.core.Calculator | None], input_names: List[str], **kwargs) → Tuple[Dict[str, utils.core.Calculator | None], bool]¶

observed_readuct_call_with_throw(subtask: SubTaskToReaductCall, systems: Dict[str, utils.core.Calculator | None], input_names: List[str], expected_results: List[str], error_msg: str, **kwargs) → Dict[str, utils.core.Calculator | None]¶

optimization_postprocessing(success: bool, systems: Dict[str, utils.core.Calculator | None], keys: List[str], old_structure: db.Structure, new_label: db.Label, program_helper: ProgramHelper | None, expected_results: List[str] | None = None) → db.Structure¶

Checks after an optimization whether everything went well and saves information to database.

Parameters:

successbool: The boolean signalling whether the task was successful (forwarded from ReaDuct)
systemsdict: Dictionary holding the calculators (forwarded from ReaDuct)
keysList[str]: The keys specifying the checked calculator
old_structuredb.Structure: The structure which was optimized
new_labeldb.Label: The label of the new structure
program_helperUnion[ProgramHelper, None]: The optional helper of the employed program for postprocessing
program_helperUnion[List[str], None]: The expected results for the calculators, if not given, assumed from invoking Job class
expected_resultsUnion[List[str], None]: The expected results for the calculators, if not given, assumed from invoking Job class

Returns:

db.Structure: The new structure

Notes

Requires run configuration
May throw exception

optimize_structures(name_stub: str, systems: Dict[str, utils.core.Calculator | None], structures: List[utils.AtomCollection], structure_charges: List[int], structure_multiplicities: List[int], calculator_settings: utils.Settings, stop_on_error: bool = True, readuct_task: SubTaskToReaductCall = SubTaskToReaductCall.OPT, task_settings_key: str | None = None) → Tuple[List[str], Dict[str, utils.core.Calculator | None]]¶

For each given product AtomCollection: First, construct a Scine Calculator and save in class member map. Second, perform a Single Point with the given charge and spin multiplicity including spin propensity check Last, optimize the product if more than one atom and perform spin propensity check again to be sure.

Parameters:

name_stubstr: The stub for naming of the structures, example: start will generate systems start_00, start_01, and so on.
systemsDict[str, Optional[utils.core.Calculator]]: The map of systems
structuresList[utils.AtomCollection]: The atoms of the structures in a list.
structure_chargesList[int]: The charges of the structures.
structure_multiplicitiesList[int]: The spin multiplicities of the structures.
calculator_settingsutils.Settings: The general settings for the Scine calculator. Charge and spin multiplicity will be overwritten.
stop_on_errorbool: If set to False, skip unsuccessful calculations and replace calculator with None
readuct_taskSubTaskToReaductCall: The task to perform with readuct, by default SubTaskToReaductCall.OPT
task_settings_keyOptional[str]: The key in the settings dictionary to use for the task settings, by default None which will be the opt_key

Returns:

product_namesList[str]: A list of the access keys to the structures in the system map.
systemsDict[str, Optional[utils.core.Calculator]]: The updated map of systems.

Notes

Requires run configuration
May throw exception

output(name: str) → List[str]¶

A helper function fetching the output entry from the system specified with the given name to ease task chaining and ensure correct chaining even if user changes the output setting.

Parameters:

namestr: Index into systems dictionary to retrieve output for

Returns:

outputsList[str]: A list of output system names

Notes

May throw exception

own_expected_results: List[str] = ['energy', 'bond_orders']¶

postprocess_calculation_context() → bool¶

Postprocesses a calculation context, pushing all errors and comments.

Returns:

True if the job succeeded, False otherwise.

prepare(job_dir: str, id: db.ID) → None¶

Prepares the actual job. This function has to be implemented by any job that shall be added to Puffins job portfolio.

Parameters:

job_dirstr: The path to the directory in which all jobs are executed.
iddb.ID (Scine::Database::ID): The calculation that triggered the execution of this job.

prepend_to_comment(message: str) → None¶

Prepends given message to the comment field of the currently configured calculation.

Parameters:

messagestr: The message to be prepended.

Notes

Requires run configuration

query_bond_orders(structure: db.Structure) → db.SparseMatrixProperty¶

Query the given Database structure for bond orders based on the model of the configured calculation

Parameters:

structuredb.Structure (Scine::Database::Structure): A database structure to query.

Returns:

db_bond_ordersdb.SparseMatrixProperty (Scine::Database::SparseMatrixProperty): A database property holding bond orders.

Notes

Requires run configuration
May throw exception

raise_named_exception(error_message: str, exception_type: ~typing.Type[BaseException] = <class 'BaseException'>) → None¶: Raises an error including the name/description of the current job.

static random_displace_atoms(atoms: utils.AtomCollection, displacement: float = 0.05) → None¶: Apply small seeded random displacement based on setting

react_postprocessing(product_names: List[str], program_helper: ProgramHelper | None, tsopt_task_name: str, reactant_structure_ids: List[db.ID]) → Tuple[List[db.ID], List[db.ID], db.ElementaryStep]¶

Carries out a verification protocol after the calculation context has been closed, clears database result and then fills it with the found products, TS, and elementary step and all properties that can be associated with those.

Parameters:

product_namesList[str]: A list of the access keys to the products in the system map.
program_helperUnion[ProgramHelper, None]: The ProgramHelper which might also want to do postprocessing
tsopt_task_namestr: The name of the task where the TS was output
reactant_structure_idsList[scine_database.ID]: A list of all structure IDs for the reactants.

Notes

Requires run configuration
May throw exception

reactive_complex_preparations() → Tuple[SettingsManager, ProgramHelper | None]¶

Determine settings for this task based on settings of configured calculation, construct a reactive complex from the structures of the configured calculation, build a Scine Calculator for it and construct the SettingsManager and ProgramHelper that are returned.

Returns:

settings_manager, program_helperTuple[SettingsManager, Union[ProgramHelper, None]]: A database property holding bond orders.

Notes

Requires run configuration
May throw exception

read_irc_and_irc_opt_trajectories(tsopt_task_name: str, irc_task_name: str) → Tuple[utils.MolecularTrajectory, int]¶

Reads the IRC and IRC optimization trajectories in the correct order to get a cohesive minimum energy path.

Parameters:

tsopt_task_namestr: The name of the transition state optimization task.
irc_task_namestr: The name of the IRC task.

Returns:

Tuple[utils.MolecularTrajectory, int]: The IRC trajectory and the index of the transition state in the IRC trajectory.

Raises:

RuntimeError: If the IRC or IRC optimization trajectory files are missing.
RuntimeError: If the step_direction is not “forward” or “backward”.

static required_programs() → List[str]¶

This function has to be implemented by any job that shall be added to Puffins job portfolio.

Returns:

requirementsList[str]: A list of names of programs/packages that are required for the execution of the job.

run(manager: db.Manager, calculation: db.Calculation, config: Configuration) → bool[source]¶

Runs the actual job. This function has to be implemented by any job that shall be added to Puffins job portfolio.

Parameters:

managerdb.Manager (Scine::Database::Manager): The manager/database to work on/with.
calculationdb.Calculation (Scine::Database::Calculation): The calculation that triggered the execution of this job.
configscine_puffin.config.Configuration: The configuration of Puffin.

save_barrierless_reaction_from_rcopt(product_graph: str, program_helper: ProgramHelper | None) → None¶

save_initial_graphs_and_charges(settings_manager: SettingsManager, structures: List[db.Structure]) → None¶

Save the graphs and charges of the reactants.

Parameters:

settings_managerSettingsManager: The settings manager for the calculation.
structuresList[scine_database.Structure]: The reactant structures.

Notes

May throw exception

save_mep_in_db(elementary_step: db.ElementaryStep, trajectory: utils.MolecularTrajectory, ts_index: int, charge: int, multiplicity: int, model: db.Model) → List[db.ID]¶

Store each point on the MEP as a structure in the database. Attaches electronic_energy properties for each point.

Parameters:

elementary_stepscine_database.ElementaryStep: The elementary step of which to store the MEP.
trajectoryutils.MolecularTrajectory: The trajectory of the elementary step.
ts_indexint: The index of the transition state in the trajectory.
chargeint: The total charge of the system.
multiplicityint: The spin multiplicity of the system.
modelscine_database.Model: The model with which all energies in the elementary Step were calculated.

Notes

May throw exception

setup_automatic_mode_selection(name: str) → None¶

A settings sanity check, which adds the settings for automatic mode selection or doesn’t based on the given user settings.

Parameters:

namestr: The name of the subtask for which the automatic mode selection is added.

sort_settings(task_settings: Dict[str, Any]) → None¶

Take settings of configured calculation and save them in class member. Throw exception for unknown settings.

Parameters:

task_settingsdict: A dictionary from which the settings are taken

Notes

Requires run configuration
May throw exception

sp_postprocessing(success: bool, systems: Dict[str, utils.core.Calculator | None], keys: List[str], structure: db.Structure, program_helper: ProgramHelper | None) → None¶

Performs a verification and results saving protocol for a Scine Single Point Calculation.

Parameters:

successbool: Whether the calculation was successful (either forwarded from readuct task or specified if not relevant).
systemsDict[str, utils.core.Calculator] (Scine::Core::Calculator): The dictionary holding calculators.
keysList[str]: The list of keys of the systems dict to be checked.
structuredb.Structure (Scine::Database::Structure): The structure on which the calculation was performed.
program_helperProgramHelper: The possible ProgramHelper that may also want to do some postprocessing after a calculation.

Notes

Requires run configuration
May throw Exception

stderr_path: str = 'stderr'¶

stdout_path: str = 'stdout'¶

store_bond_orders(bond_orders: utils.BondOrderCollection, structure: db.Structure) → None¶

store_energy(system: utils.core.Calculator, structure: db.Structure) → None¶

Stores an ‘electronic_energy’ property for the given structure based on the energy in the results of the given system. Does not perform checks.

Parameters:

systemutils.core.Calculator (Scine::Core::Calculator): A Scine calculator holding a results object with the energy property.
structuredb.Structure (Scine::Database::Structure): A structure for which the property is saved.

Notes

Requires run configuration

store_hessian_data(system: utils.core.Calculator, structure: db.Structure) → None¶

Stores results from a Hessian calculation and Thermochemistry for the specified structure based on the given calculator. Does not perform checks.

Parameters:

systemutils.core.Calculator (Scine::Core::Calculator): A Scine calculator holding a results object with energy, Hessian, and Thermochemistry properties.
structuredb.Structure (Scine::Database::Structure): A structure for which the property is saved.

Notes

Requires run configuration

store_property(properties: db.Collection, property_name: str, property_type: str, data: Any, model: db.Model, calculation: db.Calculation, structure: db.Structure, replace: bool = True) → db.Property | None¶

Adds a single property into the database, connecting it with a given structure and calculation (it’s results section) and also

Parameters:

propertiesdb.Collection (Scine::Database::Collection): The collection housing all properties.
property_namestr: The name (key) of the new property, e.g. electronic_energy.
property_typestr: The type of property to be added, e.g. NumberProperty.
dataAny (According to ‘property_type’): The data to be stored in the property, the type of this object is dependent on the type of property requested. A NumberProperty will require a float, a VectorProperty will require a List[float], etc.
modeldb.Model (Scine::Database::Model): The model used in the calculation that resulted in this property.
calculationdb.Calculation (Scine::Database::Calculation): The calculation that resulted in this property. The calculation has to be linked to its collection.
structuredb.Structure (Scine::Database::Structure): The structure for which the property is to be added. The properties field of the structure will receive an additional entry, or have an entry replaced, based on the options given to this function. The structure has to be linked to its collection.
replacebool: If true, replaces an existing property (identical name and model) with the new one. This option is true by default. If false, doesnothing in the previous case, and returns None

Returns:

propertyDerived of db.Property (Scine::Database::Property): The property, a derived class of db.Property, linked to the properties’ collection, or None if no property was generated due to duplication.

store_start_structures(start_structure_names: List[str], program_helper: ProgramHelper | None, tsopt_task_name: str, start_structures: List[db.ID] | None = None)¶

Store the new start systems in the database.

Parameters:

start_structure_namesList[str]: The names of the start structure names in the system map.
program_helperUnion[ProgramHelper, None]: The ProgramHelper which might also want to do postprocessing
tsopt_task_namestr: The name of the task where the TS was output
start_structuresOptional[List[db.ID]]: Optional list of the starting structure ids. If no list is given. The input structures of the calculation are used.

Returns:

start_structure_idsList[scine_database.ID]: A list of the database IDs of the start structures.

Notes

May throw exception

success_file() → str¶: Returns the path to the file indicating a successful calculation, empty string if job has not been prepared

surface_indices(structure: db.Structure) → Set[int]¶

surface_indices_all_structures(start_structures: List[db.ID] | None = None) → Set[int]¶

Get the combined surface indices of all structures of the configured calculation except a structure with the label db.Label.SURFACE_ADSORPTION_GUESS. Throws if a structure is specified to be a surface but does not have surface_indices property.

Parameters:

start_structuresOptional[List[db.ID]]: Optional list of the starting structure ids. If no list is given. The input structures of the calculation are used.

Returns:

surface_indicesset: A set of all surface indices over all structures combined assuming an atom ordering identical to the addition of all structures in their order within the calculation.

Notes

Requires run configuration
May throw exception

throw_if_not_successful(success: bool, systems: Dict[str, utils.core.Calculator | None], keys: List[str], expected_results: List[str] | None = None, sub_task_error_line: str = '') → None¶

Throw an exception if some calculations results are unexpected.

Parameters:

successbool: Whether the calculation was successful (either forwarded from readuct task or specified if not relevant).
systemsDict[str, Optional[utils.core.Calculator]] (Scine::Core::Calculator): The dictionary holding calculators.
keysList[str]: The list of keys of the systems dict to be checked.
expected_resultsOptional[List[str]]: The results to be required to be present in systems to qualify as successful calculations. If None is given, this defaults to the expected results of the class, see expected_results().
sub_task_error_linestr: An additional line for the error message to specify in which subtask the calculation crashed.

Notes

Requires run configuration
Will throw Exception or do nothing

transfer_properties(old_structure: db.Structure, new_structure: db.Structure, transfer_helper: TransferHelper | None = None) → None¶

Copies property IDs from one structure to another one based on the specified properties in the class member.

Parameters:

old_structuredb.Structure (Scine::Database::Structure): The structure holding the properties. If a specified property is not present for the structure, no error is given.
new_structuredb.Structure (Scine::Database::Structure): The structure for which the properties are to be added.
transfer_helperOptional[TransferHelper]: An optional helper for more difficult transfer task. Otherwise, the specified properties are just copied.

verify_connection() → None¶

Verifies the connection to the database. Returns only if a connection is established, if it is not, the function will attempt to generate a connection every 10 seconds, indefinitely.

Notes

Requires run configuration

work_dir: str¶