8.5. ParAMSResults
******************

Important:

  You should not initialize ParAMSResults yourself. Instead, use the
  corresponding ParAMSJob's "results" attribute to access the results.

**To get started**, see the ParAMS Python examples.

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)

   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_set : str
         '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_set : str
         '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) -> 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

      Returns : str
         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

      Returns : str
         Path to the xtb_files directory from GFN1-xTB optimizations

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

   get_production_engine_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') -> 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() -> 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() -> 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() -> 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() -> JobCollection

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

   get_initial_parameter_interface() -> 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() -> 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) -> 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, 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) -> 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.
