scine_puffin.jobs.scine_geometry_optimization

Classes

ScineGeometryOptimization()

A job optimizing the geometry of a given structure, in search of a local minimum on the potential energy surface.

class scine_puffin.jobs.scine_geometry_optimization.ScineGeometryOptimization

A job optimizing the geometry of a given structure, in search of a local minimum on the potential energy surface. Optimizing a given structure’s geometry, generating a new minimum energy structure, if successful.

Order Name

scine_geometry_optimization

Optional Settings

Optional settings are read from the settings field, which is part of any Calculation stored in a SCINE Database. Possible settings for this job are:

All settings recognized by ReaDuct’s geometry optimization task.

Common examples are:

optimizerstr

The name of the optimizer to be used, e.g. ‘bfgs’, ‘lbfgs’, ‘nr’ or ‘sd’.

convergence_max_iterationsint

The maximum number of geometry optimization cycles.

convergence_delta_valuefloat

The convergence criterion for the electronic energy difference between two steps.

convergence_gradient_max_coefficientfloat

The convergence criterion for the maximum absolute gradient. contribution.

convergence_step_rmsfloat

The convergence criterion for root mean square of the geometric gradient.

convergence_step_max_coefficientfloat

The convergence criterion for the maximum absolute coefficient in the last step taken in the geometry optimization.

convergence_gradient_rmsfloat

The convergence criterion for root mean square of the last step taken in the geometry optimization.

For a complete list see the ReaDuct manual

All settings that are recognized by the SCF program chosen.

Common examples are:

max_scf_iterationsint

The number of allowed SCF cycles until convergence.

Required Packages

• SCINE: Database (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 the following data will be generated and added to the database:

Structures

A new minimum energy structure.

Properties

The electronic_energy associated with the new structure.

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.

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.

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.

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

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

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

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

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

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

own_expected_results: List[str] = ['energy']

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 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

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.

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_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.

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