qmflows.packages

The Package (sub-)classes of QMFlows.

The Package Class

`Package`(pkg_name)	`Package` is the base class to handle the invocation to different quantum package.
`Package.__init__`(pkg_name)	Initialize a `Package` instance.
`Package.__call__`(settings, mol[, job_name, ...])	(scheduled) Perform a job with the package specified by `Package.pkg_name`.
`Package.prerun`(settings, mol, **kwargs)	Run a set of tasks before running the actual job.
`Package.run_job`(settings, mol[, job_name, ...])	Abstract method; should be implemented by the child class.
`Package.postrun`(result[, output_warnings, ...])	Run a set of tasks after running the actual job.
`Package.generic2specific`(settings[, mol])	Traverse settings and convert generic into package specific keys.
`Package.handle_special_keywords`(settings, ...)	Abstract method; should be implemented by the child class.

`ADF`([pkg_name])	`Package` subclass for ADF.
`DFTB`([pkg_name])	`Package` subclass for DFTB.
`CP2K`([pkg_name])	A Package subclass for running CP2K Jobs.
`CP2KMM`([pkg_name])	A Package subclass for running CP2K Jobs for classical forcefield calculations.
`ORCA`([pkg_name])	A class for preparing the input for running a Orca job using both PLAMS and templates.
`PackageWrapper`(job_type[, name])	A `Package` subclass for processing arbitrary `plams.Job` types.

Package Instances

`adf`(self, settings, mol[, job_name, ...])	(scheduled) Perform a job with the package specified by `Package.pkg_name`.
`dftb`(self, settings, mol[, job_name, ...])	(scheduled) Perform a job with the package specified by `Package.pkg_name`.
`cp2k`(self, settings, mol[, job_name, ...])	(scheduled) Perform a job with the package specified by `Package.pkg_name`.
`cp2k_mm`(self, settings, mol[, job_name, ...])	(scheduled) Perform a job with the package specified by `Package.pkg_name`.
`orca`(self, settings, mol[, job_name, ...])	(scheduled) Perform a job with the package specified by `Package.pkg_name`.

The Result Class

`Result`(settings, molecule, job_name[, ...])	Class containing the results associated with a quantum chemistry simulation.
`Result.__init__`(settings, molecule, job_name)	Initialize a `Result` instance.
`Result.get_property`(prop)	Look for the optional arguments to parse a property, which are stored in the properties dictionary.
`Result.results`	Getter for `Result.results`.

`ADF_Result`(settings, molecule, job_name[, ...])	Class providing access to PLAMS ADFJob result results.
`DFTB_Result`(settings, molecule, job_name[, ...])	Class providing access to PLAMS DFTBJob result results.
`CP2K_Result`(settings, molecule, job_name[, ...])	Class providing access to CP2K result.
`CP2KMM_Result`(settings, molecule, job_name)	A class providing access to CP2KMM result.
`ORCA_Result`(settings, molecule, job_name[, ...])	Class providing access to PLAMS OrcaJob results.
`ResultWrapper`(settings, molecule, job_name)	The matching `Result` subclass for `PackageWrapper`.

API

qmflows.packages.run(job, runner=None, path=None, folder=None, load_jobs=False, **kwargs)[source]

Pickup a runner and initialize it.

Serves as a wrapper around noodles.run_parallel().

Parameters:

job (noodles.PromisedObject) – The computation to run as constructed by Package.__call__().
runner (str, optional) – The job runner. Note that this value should be left at None.
path (str or PathLike, optional) – The path where the PLAMS working directory will be created. Will default to the current working directory if None.
folder (str or PathLike, optional) – The name of the new PLAMS working directory. Will default to "plams_workdir" if None.
load_jobs (bool) – Load all pre-existing Jobs (contained within the working directory) into memory. Note that this can be quite slow if a large number of pre-existing jobs is present.
**kwargs (Any) – Further keyword arguments to-be passed to call_default().

Returns:

A new Result instance. The exact type will depend on job.

Return type:

Result

See also

noodles.run_parallel(): Run a workflow in parallel threads, storing results in a Sqlite3 database.

class qmflows.packages.Package(pkg_name)[source]

Package is the base class to handle the invocation to different quantum package.

The only relevant (instance) attribute of this class is Package.pkg_name which is a string representing the quantum package name that is going to be used to carry out the compuation.

The life-cycle of Package consists of 5 general steps:

Initializing an instance: Package.__init__().
Starting the job: Package.__call__(). This method handles the task distribution between the instance’s various methods.
Converting all generic into specific settings: Package.generic2specific().
Running the actual plams.Job (including pre- and post-processing): Package.run_job().
Returning the final Result instance at the end of Package.__call__().

generic_mapping = NotImplemented: A class variable with the name of the generic .yaml file. Should be set when creating a subclass.

pkg_name: An instance variable with the name of the respective quantum chemical package.

result_type = NotImplemented: A class variable pointing to the Package-specific Result class. Should be set when creating a subclass.

Package.__init__(pkg_name)[source]

Initialize a Package instance.

Parameters:: pkg_name (str) – The name of the respective quantum chemical package. See Package.pkg_name.

Package.__call__(settings, mol, job_name='', validate_output=True, **kwargs)[source]

(scheduled) Perform a job with the package specified by Package.pkg_name.

Parameters:

settings (qmflows.Settings) – The user settings.
mol (plams.Molecule or rdkit.Mol) – A PLAMS or RDKit molecule to-be passed to the calculation.
job_name (str) – The name of the job.
validate_output (bool) – If True, perform a package-specific validation of the output files’ content. Only relevant if the particular Package subclass has actually implemented output validation.
**kwargs (Any) – Further keyword arguments to-be passed to Package.prerun(), Package.run_job() and Package.post_run().

Returns:

A new Result instance.

Return type:

Result

Package.prerun(settings, mol, **kwargs)[source]

Run a set of tasks before running the actual job.

Parameters:

settings (qmflows.Settings) – Settings provided by the user. Note that these settings can still contain generic keywords.
mol (plams.Molecule, optional) – A PLAMS molecule to-be passed to the calculation.
**kwargs (Any) – Further keyword arguments to-be passed to Package.run_job().

See also

Package.run_job(): A method which handles the running of the actual plams.Job.

abstract classmethod Package.run_job(settings, mol, job_name='job', work_dir=None, validate_output=False, **kwargs)[source]

Abstract method; should be implemented by the child class.

A method which handles the running of the actual plams.Job.

Parameters:

settings (qmflows.Settings, optional) – User-provided Settings as processed by Package.generic2specific().
mol (plams.Molecule) – A PLAMS molecule to-be passed to the calculation.
job_name (str) – The name of the job.
workdir (str or PathLike, optional) – The path+folder name of the PLAMS working directory.
validate_output (bool) – If True, perform a package-specific validation of the output files’ content. Only relevant if the particular Package subclass has actually implemented output validation.
**kwargs (Any) – Further keyword arguments.

Returns:

A new Result instance.

Return type:

Result

Package.postrun(result, output_warnings=None, settings=None, mol=None, **kwargs)[source]

Run a set of tasks after running the actual job.

Parameters:

result (Result) – A Result instance.
output_warnings (Mapping [str, type [Warning]], optional) – A Mapping which maps an error messages to Warning types.
settings (qmflows.Settings, optional) – User-provided Settings as processed by Package.generic2specific(). Will be None if an error occured before this point.
mol (plams.Molecule, optional) – A PLAMS molecule as passed to the calculation. Will be None if an error occured before the molecule was parsed in Package.__call__().
**kwargs (Any) – Further keyword arguments that were passed to Package.run_job().

See also

Package.run_job(): A method which handles the running of the actual plams.Job.

Package.generic2specific(settings, mol=None)[source]

Traverse settings and convert generic into package specific keys.

Traverse all the key, value pairs of the settings, translating the generic keys into package specific keys as defined in the specific dictionary. If one key is not in the specific dictionary an error is raised. These new specific settings take preference over existing specific settings.

Parameters:

settings (qmflows.Settings) – Settings provided by the user.
mol (plams.Molecule, optional) – A PLAMS molecule to-be passed to the calculation.

Returns:

A new settings instance without any generic keys.

Return type:

qmflows.Settings

abstract static Package.handle_special_keywords(settings, key, value, mol)[source]

Abstract method; should be implemented by the child class.

A method providing additional processing for Package dependant generic keywords.

Parameters:

settings (qmflows.Settings, optional) – User-provided Settings as being processed by Package.generic2specific().
key (str) – The key associated with the special keyword
value (Any) – The value associated with the special key.
mol (plams.Molecule) – A PLAMS molecule to-be passed to the calculation.

See also

Package.generic2specific(): Traverse settings and convert generic into package specific keys.

class qmflows.packages.ADF(pkg_name='adf')[source]

Package subclass for ADF.

This class takes care of calling the ADF quantum package. it uses both Plams and the Templates module to create the input files, while Plams takes care of running the plams.ADFJob. It returns a ADF_Result instance containing the output data.

class qmflows.packages.DFTB(pkg_name='dftb')[source]: Package subclass for DFTB.

class qmflows.packages.CP2K(pkg_name='cp2k')[source]

A Package subclass for running CP2K Jobs.

It uses plams together with the templates to generate the stucture input and also uses Plams to invoke the binary CP2K code. This class is not intended to be called directly by the user, instead the cp2k function should be called.

class qmflows.packages.CP2KMM(pkg_name='cp2k')[source]

A Package subclass for running CP2K Jobs for classical forcefield calculations.

It uses plams together with the templates to generate the stucture input and also uses Plams to invoke the binary CP2K code. This class is not intended to be called directly by the user, instead the cp2k_mm function should be called.

class qmflows.packages.ORCA(pkg_name='orca')[source]

A class for preparing the input for running a Orca job using both PLAMS and templates.

It also does the manangement of the input/output files resulting from running Orca and returns a Results object that containing the methods and data required to retrieve the output.

class qmflows.packages.PackageWrapper(job_type, name=None)[source]

A Package subclass for processing arbitrary plams.Job types.

Will automatically convert the passed Job type into the appropiate Package instance upon calling PackageWrapper.__call__().

Examples

>>> from scm.plams import ADFJob, AMSJob

>>> from qmflows import PackageWrapper, run
>>> from qmflows.packages import ResultWrapper, ADF_Result

# Start of with two PackageWrapper instances
>>> pkg_adf = PackageWrapper(ADFJob)
>>> pkg_ams = PackageWrapper(AMSJob)

# End up with two different Result instances
>>> result_adf: ADF_Result = run(pkg_adf(...), ...)  
>>> result_ams: ResultWrapper = run(pkg_ams(...), ...)  

job_type

The to-be executed plams.Job type. Will be automatically translated, when possible, into to the appropiate Package instance upon calling PackageWrapper.__call__(). If not, default to the more bare-bones implementation within this class and the matching ResultWrapper instance.

Type:: type[plams.Job]

See also

JOB_MAP: A dictionary mapping PLAMS Job types to appropiate QMFlows Package instances.

class qmflows.packages.Result(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]

Class containing the results associated with a quantum chemistry simulation.

prop_mapping = NotImplemented: A Settings instance with Result-specific properties. Should be set when creating a subclass.

Result.__init__(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]

Initialize a Result instance.

Parameters:

settings (qmflows.Settings) – Job Settings.
molecule (plams.Molecule) – molecular Geometry
job_name (str) – Name of the computations
dill_path (str) – The absolute path to the pickled .dill file.
plams_dir (str) – path to the Plams folder.
work_dir – scratch or another directory different from the plams_dir.

Type:

work_dir: str

Result.get_property(prop)[source]: Look for the optional arguments to parse a property, which are stored in the properties dictionary.

property Result.results

Getter for Result.results.

Get will load the .dill file and add all of its class attributes to this instance, barring the following three exceptions:

Private attributes/methods.
Magic methods.
Methods/attributes with names already contained within this instance.

This attribute’s value is set to None if the unpickling process fails.

class qmflows.packages.ADF_Result(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]: Class providing access to PLAMS ADFJob result results.

class qmflows.packages.DFTB_Result(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]: Class providing access to PLAMS DFTBJob result results.

class qmflows.packages.CP2K_Result(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]: Class providing access to CP2K result.

class qmflows.packages.CP2KMM_Result(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]: A class providing access to CP2KMM result.

class qmflows.packages.ORCA_Result(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]: Class providing access to PLAMS OrcaJob results.

class qmflows.packages.ResultWrapper(settings, molecule, job_name, dill_path=None, plams_dir=None, work_dir=None, status='successful', warnings=None)[source]: The matching Result subclass for PackageWrapper.

qmflows.adf(self, settings, mol, job_name='', validate_output=True, **kwargs)

(scheduled) Perform a job with the package specified by Package.pkg_name.

Parameters:

settings (qmflows.Settings) – The user settings.
mol (plams.Molecule or rdkit.Mol) – A PLAMS or RDKit molecule to-be passed to the calculation.
job_name (str) – The name of the job.
validate_output (bool) – If True, perform a package-specific validation of the output files’ content. Only relevant if the particular Package subclass has actually implemented output validation.
**kwargs (Any) – Further keyword arguments to-be passed to Package.prerun(), Package.run_job() and Package.post_run().

Returns:

A new Result instance.

Return type:

Result

qmflows.dftb(self, settings, mol, job_name='', validate_output=True, **kwargs)

(scheduled) Perform a job with the package specified by Package.pkg_name.

Parameters:

settings (qmflows.Settings) – The user settings.
mol (plams.Molecule or rdkit.Mol) – A PLAMS or RDKit molecule to-be passed to the calculation.
job_name (str) – The name of the job.
validate_output (bool) – If True, perform a package-specific validation of the output files’ content. Only relevant if the particular Package subclass has actually implemented output validation.
**kwargs (Any) – Further keyword arguments to-be passed to Package.prerun(), Package.run_job() and Package.post_run().

Returns:

A new Result instance.

Return type:

Result

qmflows.cp2k(self, settings, mol, job_name='', validate_output=True, **kwargs)

(scheduled) Perform a job with the package specified by Package.pkg_name.

Parameters:

settings (qmflows.Settings) – The user settings.
mol (plams.Molecule or rdkit.Mol) – A PLAMS or RDKit molecule to-be passed to the calculation.
job_name (str) – The name of the job.
validate_output (bool) – If True, perform a package-specific validation of the output files’ content. Only relevant if the particular Package subclass has actually implemented output validation.
**kwargs (Any) – Further keyword arguments to-be passed to Package.prerun(), Package.run_job() and Package.post_run().

Returns:

A new Result instance.

Return type:

Result

qmflows.cp2k_mm(self, settings, mol, job_name='', validate_output=True, **kwargs)

(scheduled) Perform a job with the package specified by Package.pkg_name.

Parameters:

settings (qmflows.Settings) – The user settings.
mol (plams.Molecule or rdkit.Mol) – A PLAMS or RDKit molecule to-be passed to the calculation.
job_name (str) – The name of the job.
validate_output (bool) – If True, perform a package-specific validation of the output files’ content. Only relevant if the particular Package subclass has actually implemented output validation.
**kwargs (Any) – Further keyword arguments to-be passed to Package.prerun(), Package.run_job() and Package.post_run().

Returns:

A new Result instance.

Return type:

Result

qmflows.orca(self, settings, mol, job_name='', validate_output=True, **kwargs)

(scheduled) Perform a job with the package specified by Package.pkg_name.

Parameters:

settings (qmflows.Settings) – The user settings.
mol (plams.Molecule or rdkit.Mol) – A PLAMS or RDKit molecule to-be passed to the calculation.
job_name (str) – The name of the job.
validate_output (bool) – If True, perform a package-specific validation of the output files’ content. Only relevant if the particular Package subclass has actually implemented output validation.
**kwargs (Any) – Further keyword arguments to-be passed to Package.prerun(), Package.run_job() and Package.post_run().

Returns:

A new Result instance.

Return type:

Result

`run`(job[, runner, path, folder, load_jobs])	Pickup a runner and initialize it.
`registry`()	Pass to the noodles infrastructure all the information related to the structure of the `Package` object that is scheduled.

qmflows.packages

Package-related Functions

The Package Class

Package Instances

The Result Class

API