7.1.1. ResultsImporter overview¶

7.1.1.1. ResultsImporter summary¶

The ResultsImporter class is convenient for setting up the Job Collection, Data Set, and Engine Collection from finished reference calculations. A results importer typically affects all three of those classes with a single method (see Import training data (Python))

Most ResultsImporters work on finished reference jobs, coming from one of these computational chemistry programs:

The ResultsImporter

• reads the input and output from the reference job,

• creates a reference engine in the Engine Collection if it does not already exist,

• adds one or more jobs to the Job Collection using one or more systems from the reference job, if they do not already exist

• adds one or more entries to the Data Set

The Import training data (Python) gives an example on how to use ResultsImporters.

All ResultsImporters are summarized in the below table, where SP stands for SinglePoint, GO for GeometryOptimization, MD for MolecularDynamics, and QE for Quantum ESPRESSO.

1

add_reaction_energy can also be used without reference jobs, only the atomic coordinates are needed.

2

add_singlejob takes the “main molecule”, unless the reference job is a PESScan (then the input molecule is used).

3

Trajectory properties: energy, relative_energies, forces, stresstensor

7.1.1.2. ResultsImporter settings¶

When initializing a ResultsImporter, you can pass a settings argument, that is either a string pointing to a results_importer_settings.yaml file, or which is a PLAMS Settings instance.

Example:

results_importer_settings = Settings()
results_importer_settings.trim_settings = True
results_importer_settings.default_go_settings.MaxIterations = 30
results_importer_settings.units.energy = 'kcal/mol'

ri = ResultsImporter(settings=results_importer_settings)

For a detailed description of the available settings, see __init__().

7.1.1.3. Training set, validation set, etc.¶

See the tutorial: Training set, validation set, and other data sets.

7.1.1.4. Save and load from disk¶

The job collection, engine collection, data_set(s), and shortcut settings can be stored for later retrieval with the store() method.

To load them from files, pass the paths to the files as arguments to __init__().

For an example, see the tutorial: Save to disk.

7.1.1.5. add_singlejob¶

add_singlejob() adds 1 job to the job collection, together with an arbitrary number of entries in the data_set.

For how to use it, see the Import training data (Python), in particular

• Add a singlepoint calculation on the optimized geometry

• Add a geometry optimization job extracting the bond length and bond angle

See also the API docs: add_singlejob()

Each entry in the data_set must be an extractor acting on the job.

Adding for example 'distance(0,1)' to the properties argument will add a data_set entry with the expression distance('jobname',0,1).

Example:

ri = ResultsImporter()
ri.add_singlejob('/path/to/ams.rkf',
                 properties=['energy', 'distance(0,1)'],
                 task='GeometryOptimization')

7.1.1.6. add_trajectory_singlepoints¶

add_trajectory_singlepoints() extracts given number of frames from a trajectory file. The properties must be one or more of the following: energy, relative_energies, forces, or stresstensor.

For how to use it, see Import training data (Python), in particular

• Add a trajectory

See also the API docs: add_trajectory_singlepoints()

Example:

ri = ResultsImporter()

# extract every 10 frames
ri.add_trajectory_singlepoints('/path/to/ams.rkf',
                  properties=['forces', 'relative_energies'],
                  start=0,
                  step=10)

# extract 20 frames
ri.add_trajectory_singlepoints('/path/to/ams.rkf',
                  properties=['forces', 'relative_energies'],
                  N=20)

7.1.1.7. add_reaction_energy¶

add_reaction_energy() calculates and adds a reaction energy to the data_set. The reaction is automatically balanced: only the reactants and products need to specified, not the stoichiometric coefficients. The coefficients are normalized according to the normalization and normalization_value arguments.

Setting normalization='r0' will set the coefficient for the first reactant to normalization_value. normalization='r1' would correspond to the second reactant, etc. normalization='p0' would correspond to the first product, etc.

add_reaction_energy can also be used with PLAMS molecules instead of reference jobs. In that case one should specify the reference value with the reference keyword.

For how to use it, see Import training data (Python), in particular

• Add a reaction energy

See also the API docs: add_reaction_energy()

Simple example:

ri = ResultsImporter()

# from reference jobs
ri.add_reaction_energy(reactants=['/reactant1/ams.rkf', '/reactant2/ams.rkf'],
                       products=['/product1/ams.rkf', '/product2/ams.rkf'],
                       normalization='r0',
                       normalization_value=1.0)

# from Molecule instances. mol_1 etc. need to be PLAMS Molecules
ri.add_reaction_energy(reactants=[mol_1, mol_2],
                       products=[mol_3, mol_4],
                       normalization='p1',
                       normalization_value=2.0,
                       reference=12.34,
                       unit='kcal/mol')

7.1.1.8. add_pesscan_singlepoints¶

add_pesscan_singlepoints() extracts a given number of (converged) frames from an AMS PESScan reference job, and adds them as single point calculations to the job collection.

The properties must be one or more of the following: energy, relative_energies, stresstensor* (stresstensor, stresstensor_2d, etc., see Available Extractors).

See the API docs for details: add_pesscan_singlepoints()

Example:

ri = ResultsImporter()

ri.add_pesscan_singlepoints('/path/to/ams.rkf',  # ams.rkf from a PESScan job
               properties=['relative_energies'])

7.1.1.9. add_neb_singlepoints¶

add_neb_singlepoints() extracts the converged frames from an AMS NEB reference job, and adds them as single point calculations to the job collection.

The properties must be one or more of the following: energy, relative_energies.

See the API docs for details: add_neb_singlepoints()

Example:

ri = ResultsImporter()

ri.add_neb_singlepoints('/path/to/ams.rkf',  # ams.rkf from a NEB job
           properties=['relative_energies'])

7.1.1.10. add_pesexploration_singlepoints¶

add_pesexploration_singlepoints() extracts a given list of states an AMS PESExploration reference job, and adds them as single point calculations to the job collection.

The properties must be one or more of the following: energy, relative_energies.

See the API docs for details: add_pesexploration_singlepoints()

Example:

ri = ResultsImporter()

ri.add_pesexploration_singlepoints('/path/to/ams.rkf',  # ams.rkf from a PESExploration job
                      properties=['relative_energies'],
                      indices=[1,2,5,6]) # state numbers (start with 1)