scine_puffin.jobs.graph¶
Classes
|
A job generating the molassembler graph and decision lists of a structure. |
- class scine_puffin.jobs.graph.Graph[source]¶
A job generating the molassembler graph and decision lists of a structure.
- Order Name
graph
- Optional Settings
Optional settings are read from the
settings
field, which is part of anyCalculation
stored in a SCINE Database. Possible settings for this job are:- add_based_on_distance_connectivitybool
If
True
, the structure’s connectivity is derived from interatomic distances via the utils.BondDetector: The bond orders used for interpretation are set to the maximum between those given in thebond_orders
property and 1.0, wherever the utils.BondDetector detects a bond. (default: True)- sub_based_on_distance_connectivitybool
If
True
, the structure’s connectivity is derived from interatomic distances via the utils.BondDetector: The bond orders used for interpretation are removed, wherever the utils.BondDetector does not detect a bond. (default: True)- enforce_bond_order_modelbool
If
True
, only processesbond_orders
that were generated with the specified model. IfFalse
, eventually falls back to anybond_orders
available for the structure. (default: True)
- Required Packages
SCINE: Database (present by default)
SCINE: molassembler (present by default)
SCINE: Utils (present by default)
- Generated Data
If successful the following data will be generated and added to the database:
- Properties
None
- Other
Graph representations of the structure will be added to the structures
graphs
field. The added representations are: A representation of the graphmasm_cbor_graph
, and the decision representations of the existing stereopermutators using a nearest neighbor fitmasm_decision_list
Any previous graph representations of the structure will be overwritten.
- 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.
- 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
- 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.
- 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
- 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] [source]¶
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.
- 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
- 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 afloat
, aVectorProperty
will require aList[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_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.