8.5. ParAMSResults¶

To get started, see the tutorial Getting Started: Python.

class ParAMSResults(*args, **kwargs)¶

Use this class to access results from a finished ParAMS job (the job may have been run either with the GUI or using the ParAMSJob Python class).

You should not create an instance of this class yourself. Instead, create a ParAMSJob, which will have a results attribute of type ParAMSResults.

Example:

job = ParAMSJob.load_external("/path/to/jobname.results")
print(type(job.results)) # job.results is of type ParAMSResults
print(job.results.get_loss()) # print the best loss function value for the training set
print(job.results.path) # "/path/to/jobname.results"

__init__(*args, **kwargs)¶

Initialize self. See help(type(self)) for accurate signature.

get_loss(source: str = 'best', data_set: str = 'training_set', optimizer: int = None) → float¶

Get the loss function value. Works for tasks ‘optimization’ and ‘singlepoint’.

source: str

‘best’, ‘latest’, ‘validation_set_best_parameters’, etc. Ignored if the task is ‘singlepoint’.

data_set: str

‘training_set’ or ‘validation_set’. Will read results from the directory training_set_results etc.

optimizer: int or None

If integer, read from the corresponding optimizer_XXX directory. If None, read from the “overall” (global) results. Ignored if the task is ‘singlepoint’.

Returns: float

The loss function value (loss.txt)

get_evaluation_number(source: str = 'best', data_set: str = 'training_set', optimizer: int = None) → int¶

Get the (global) evaluation number.

Returns: int

The other arguments are described for ParAMSResults.get_loss()

get_running_loss(data_set: str = 'training_set', optimizer: int = None) → tuple¶

Get the running loss from running_loss.txt.

data_setstr

‘training_set’ or ‘validation_set’

optimizer: int or None

If an integer, only get the running loss for that optimizer. Otherwise, get the loss for all optimizers.

Returns: 2-tuple (evaluation_id, loss) where each item is a list of length N

get_running_active_parameters(data_set: str = 'training_set', optimizer: int = None) → tuple¶

Get the running active parameters from running_active_parameters.txt.

data_setstr

‘training_set’ or ‘validation_set’

optimizer: int or None

If an integer, only get the running active parameters for that optimizer. Otherwise, get the parameters for all optimizers.

Returns: 2-tuple (evaluation_id, parameters) where evaluation_id is a list of float, and parameters is a dict where the keys are the parameter names and the values are a list of float (of the same length as evaluation_id)

get_parameter_interface_path(source: str = 'best', data_set: str = 'training_set', optimizer: int = None) → str¶

Returns: the path to a parameter interface (ReaxFFParameters, GFN1xTBParameters, …) yaml file.

The arguments are described for ParAMSResults.get_loss()

get_parameter_interface(source: str = 'best', data_set: str = 'training_set', optimizer: int = None) → scm.params.parameterinterfaces.base.BaseParameters¶

Returns: a parameter interface (ReaxFFParameters, GFN1xTBParameters, …) from a parameter_interface.yaml file.

The arguments are described for ParAMSResults.get_loss()

get_ffield(source: str = 'best', data_set: str = 'training_set', optimizer: int = None) → str¶

Returnsstr

Path to the ffield.ff file from ReaxFF optimizations

The arguments are described for ParAMSResults.get_loss()

get_xtb_files(source: str = 'best', data_set: str = 'training_set', optimizer: int = None) → str¶

Returnsstr

Path to the xtb_files directory from GFN1-xTB optimizations

The arguments are described for ParAMSResults.get_loss()

get_production_engine_settings() → scm.plams.core.settings.Settings¶

Obtain a Settings object that specifies the engine settings need for AMS to run a calculation with the model trained in this ParAMS job.

Returns

The engine settings object.

Return type

Settings

get_deployed_model_path() → str¶

Returns : str

Path to the * deployed.pth file from a NequIP training, or * frozen_model.pb file from DeePMD training (if approximate=False) * frozen_model_compress.pb file from DeePMD training (if approximate=True)

get_deployed_model_paths() → List[str]¶

Returns : list of str

get_restart_model_path() → str¶

Path to the (undeployed) best model used for restarting a NequIP training run

Returns

Path to the (undeployed) best model used for restarting a NequIP training run

Return type

str

get_restart_model_paths() → List[str]¶

Returns : list of str

get_data_set(data_set: str = 'training_set') → scm.params.core.dataset.DataSet¶

Returns a DataSet based on settings_and_initial_data/data_sets/data_set.yaml.gz

get_training_set_path() → str¶

Returns the absolute path to settings_and_initial_data/data_sets/training_set.yaml.gz

get_training_set() → scm.params.core.dataset.DataSet¶

Returns a DataSet based on settings_and_initial_data/data_sets/training_set.yaml.gz

get_validation_set_path() → str¶

Returns the absolute path to settings_and_initial_data/data_sets/validation_set.yaml.gz

get_validation_set() → scm.params.core.dataset.DataSet¶

Returns a DataSet based on settings_and_initial_data/data_sets/validation_set.yaml.gz

get_training_set_ref_path() → str¶

Returns the absolute path to training_set.ref.yaml from a task GenerateReference job

get_training_set_ref() → scm.params.core.dataset.DataSet¶

Returns a DataSet containing the newly calculated reference values from a task GenerateReference job

get_reference_jobs_dir() → str¶

Returns the absolute path to the directory containing the reference jobs from a task GenerateReference job

get_job_collection_path() → str¶

Returns the path to settings_and_initial_data/job_collection.yaml.gz

get_job_collection() → scm.params.core.jobcollection.JobCollection¶

Returns a JobCollection based on settings_and_initial_data/job_collection.yaml.gz

get_initial_parameter_interface() → scm.params.parameterinterfaces.base.BaseParameters¶

Returns a parameter interface (ReaxFFParameters, GFN1xTBParameters, …) from settings_and_initial_data/initial_parameter_interface.yaml

Note: This function will always return the initial parameter interface. For task ‘optimization’, if you performed an evaluation with the initial parameters you could also call get_parameter_interface(source='initial').

get_engine_collection_path() → str¶

Returns the path to settings_and_initial_data/job_collection_engines.yaml.gz

NOTE: This file does not always exist.

get_engine_collection() → scm.params.core.engines.EngineCollection¶

Returns an engine collection based on settings_and_initial_data/job_collection_engines.yaml.gz

get_inputfile() → str¶

Returns the path to the settings_and_initial_data/params.in file.

get_data_set_evaluator(source: str = 'best', data_set: str = 'training_set', optimizer: int = None) → scm.params.common.dataset_evaluator.DataSetEvaluator¶

Returns: a DataSetEvaluator from a data_set_predictions.yaml file.

The arguments are described for ParAMSResults.get_loss()

plot_simple_correlation(key: str, title: str = '', training_set: bool = True, validation_set: bool = True, source: str = 'best', optimizer: int = None)¶

Makes a simple correlation plot from the first-level DataSetEvaluator.results[key] type of GroupedResult.

key: bool

What property to plot. For a default grouping of the DataSetEvaluator this can be for example “energy”, “forces”, etc., i.e. any extractor name.

training_set: bool

Plot training set results

validation_set: bool

Plot validation set results

The other arguments are described for ParAMSResults.get_loss()

get_num_optimizers() → int¶

Returns the number of optimizers as determined by the number of files/directories starting with optimizer_ inside the optimization/ folder

get_checkpoints() → List[str]¶

Returns a list of all checkpoint files sorted by creation date

get_all_pes_prediction_names(source: str = 'best', data_set: str = 'training_set', optimizer: int = None)¶

Returns a list of all files in pes_predictions/, excluding the .txt suffix.

get_pes_prediction(name, source: str = 'best', data_set: str = 'training_set', optimizer: int = None)¶

name: str

The name. Example: if there’s a file in pes_predictions/my_pesscan.txt, then set name='my_pesscan'.

The other arguments are described for ParAMSResults.get_loss().

Returns: 5-tuple

x_headers (list of str), x_values (list of list of float), ref_values (list of float), pred_values (list of float), ref_and_pred_unit (str)

E.g. x_headers[0] would be a description of the first scan direction of the first scan coordinate, and x_values[0] would be the corresponding coordinate values.

get_sensitivities(average_bootstraps: bool = True) → Dict[str, numpy.ndarray]¶

Normalised HSIC calculation results. If average_bootstraps is True and multiple bootstraps were calculated, this represents the mean over the bootstraps. Otherwise, a matrix of sensitivities is returned.

get_sensitivity(parameter_name: str, average_bootstraps: bool = True) → numpy.ndarray¶

Return the sensitivity for a particular parameter (averaged or not over the repeated calculations).

get_num_bootstraps() → int¶

Return the number of bootstraps (repeats) of the sensitivity calculation.

get_num_samples() → int¶

Return the number of samples used in each sensitivity calculation.

get_ordered_parameters() → List[str]¶

Return a list of parameter names, ordered from most sensitive to least sensitive.

get_parameter_rankings() → Dict[str, int]¶

Return a dictionary of parameter names and their relative sensitivity ranking (1 being the most sensitive.)

get_suggested_weights(data_set: str = 'training_set') → Dict[str, float]¶

Return a dictionary of data set items and suggested weights based on the results of the reweight calculation.