8. Python Classes and Functions
*******************************

See also: Tutorial examples: ParAMS Python examples

For ParAMS users, the **five most important Python classes to know**
are

* ResultsImporter: It lets you convert a reference (DFT) calculation
  into the ParAMS format (job collections, engine collections, and
  data sets)

* Extractors: Functions that extract data from jobs, e.g. "energy",
  "forces", "angle", etc.

* Parameter interfaces like ReaxFFParameters and GFN1xTBParameters:
  They let you set which parameters to optimize, their initial values,
  and can convert between the ParAMS format and the AMS format.

* ParAMSJob: It lets you set up the settings for a ParAMS job and run
  it through Python (using PLAMS).

* ParAMSResults: It lets you extract results from a finished ParAMS
  job (also works if the job was run with the GUI).

The ResultsImporter class is usually enough to add training data. For
full control of your training set, you can also use the classes that
ResultsImporter uses internally:

* Job Collection: Contains most settings for the jobs (the structure
  and task like SinglePoint or GeometryOptimization).

* Engine Collection: Contains additional engine settings. It is
  usually not needed, but may be used to set e.g. k-space sampling for
  GFN1-xTB parametrizations.

* Data Set: Contains reference values with units, what to extract from
  jobs, and the weights. It is used for both the **training set** and
  (optionally) **validation set**.

To set the data set weights, you may be interested in

* Weights schemes: They let you set different weights to different
  force components (for example) depending on how large the forces
  are.

To get more from your results, you may be interested in

* Data Set Evaluator: It lets you access the contents of files like
  "stats.txt" and "scatter_plots/forces.txt".

Finally, there are some classes that are used internally by ParAMS.
You typically shouldn't use these yourself, but instead set the
corresponding input options in the input file (that you can set up
with a ParAMSJob).

For end-to-end scripting examples using these classes, see the ParAMS
Python examples.

* 8.1. Results Importer

  * 8.1.1. ResultsImporter overview

    * 8.1.1.1. ResultsImporter summary

    * 8.1.1.2. ResultsImporter settings

    * 8.1.1.3. Training set, validation set, etc.

    * 8.1.1.4. Save and load from disk

    * 8.1.1.5. add_singlejob

    * 8.1.1.6. add_trajectory_singlepoints

    * 8.1.1.7. add_reaction_energy

    * 8.1.1.8. add_pesscan_singlepoints

    * 8.1.1.9. add_neb_singlepoints

    * 8.1.1.10. add_pesexploration_singlepoints

  * 8.1.2. AMS, VASP, Quantum ESPRESSO, and Gaussian reference data

    * 8.1.2.1. AMS

    * 8.1.2.2. VASP

    * 8.1.2.3. Quantum ESPRESSO and Gaussian

  * 8.1.3. ResultsImporters API

    * "ResultsImporter"

      * "ResultsImporter.__init__()"

      * "ResultsImporter.from_yaml()"

      * "ResultsImporter.from_params_results()"

      * "ResultsImporter.add_singlejob()"

      * "ResultsImporter.add_pesscan_singlepoints()"

      * "ResultsImporter.add_neb_singlepoints()"

      * "ResultsImporter.add_trajectory_singlepoints()"

      * "ResultsImporter.add_pesexploration_singlepoints()"

      * "ResultsImporter.add_reaction_energy()"

      * "ResultsImporter.store()"

      * "ResultsImporter.store_ase()"

      * "ResultsImporter.add_engine_from_amsjob()"

* 8.2. Extractors and Comparators

  * 8.2.1. Available Extractors

    * 8.2.1.1. Angle

      * "extract()"

    * 8.2.1.2. Average distance

      * "extract()"

    * 8.2.1.3. BandGap

      * "extract()"

    * 8.2.1.4. BandStructure

      * "extract()"

    * 8.2.1.5. Bulk modulus

      * "extract()"

    * 8.2.1.6. Cell angles

      * "extract()"

    * 8.2.1.7. Cell lengths

      * "extract()"

    * 8.2.1.8. Cell volume

      * "extract()"

    * 8.2.1.9. Charges

      * "extract()"

    * 8.2.1.10. Dihedral

      * "extract()"

    * 8.2.1.11. dipole_moment

      * "extract()"

    * 8.2.1.12. Distance

      * "extract()"

    * 8.2.1.13. Distance vector

      * "extract()"

    * 8.2.1.14. Energy

      * "extract()"

    * 8.2.1.15. Forces

      * "extract()"

    * 8.2.1.16. Hessian

      * "extract()"

    * 8.2.1.17. PES

      * "extract()"

    * 8.2.1.18. PES compared

      * "extract()"

    * 8.2.1.19. PESScan angle

      * "extract()"

    * 8.2.1.20. PESScan dihedral

      * "extract()"

    * 8.2.1.21. PESScan distance

      * "extract()"

    * 8.2.1.22. RMSD

      * "extract()"

    * 8.2.1.23. Shear modulus

      * "extract()"

    * 8.2.1.24. Stress tensor

      * "extract()"

    * 8.2.1.25. Stress tensor 1D

      * "extract()"

    * 8.2.1.26. Stress tensor 2D

      * "extract()"

    * 8.2.1.27. Stress tensor 3D

      * "extract()"

    * 8.2.1.28. Stress tensor diagonal 2D

      * "extract()"

    * 8.2.1.29. Stress tensor diagonal 3D

      * "extract()"

    * 8.2.1.30. Stress tensor off-diagonal 2D

      * "extract()"

    * 8.2.1.31. Stress tensor off-diagonal 3D

      * "extract()"

    * 8.2.1.32. Vibrational frequencies

      * "extract()"

    * 8.2.1.33. Young modulus

      * "extract()"

  * 8.2.2. Custom Extractors

  * 8.2.3. Supported Data Structures

  * 8.2.4. Custom Comparators

* 8.3. Parameter Interfaces

  * 8.3.1. Available Parameter Interfaces

    * 8.3.1.1. GFN1-xTB

      * 8.3.1.1.1. List of parameter names

      * 8.3.1.1.2. GFN1xTBParameters API

        * "GFN1xTBParameters"

          * "GFN1xTBParameters.__init__()"

          * "GFN1xTBParameters.write()"

          * "GFN1xTBParameters.get_engine()"

    * 8.3.1.2. ReaxFF

      * 8.3.1.2.1. Reading Legacy params files

      * 8.3.1.2.2. Addition of Parameters

      * 8.3.1.2.3. Trim (remove elements) from a ReaxFF force field

      * 8.3.1.2.4. Apply recommended parameter ranges (constraints)

      * 8.3.1.2.5. Parameter Databases and Value Suggestions

      * 8.3.1.2.6. ReaxFF Conversion Functions

        * "trainset_to_params()"

        * "geo_to_params()"

      * 8.3.1.2.7. ReaxFF Interface API

        * "ReaxFFParameters"

          * "ReaxFFParameters.Parameter"

            * "ReaxFFParameters.Parameter.__init__()"

          * "ReaxFFParameters.__init__()"

          * "ReaxFFParameters.__str__()"

          * "ReaxFFParameters.get_engine()"

          * "ReaxFFParameters.write()"

          * "ReaxFFParameters.get_constraints()"

          * "ReaxFFParameters.read_paramsfile()"

          * "ReaxFFParameters.add_blocks()"

          * "ReaxFFParameters.generate_paramsdb()"

          * "ReaxFFParameters.params_from_db()"

          * "ReaxFFParameters.block_from_db()"

          * "ReaxFFParameters.names_in_block()"

          * "ReaxFFParameters.name_to_index()"

          * "ReaxFFParameters.copy_block()"

          * "ReaxFFParameters.get()"

          * "ReaxFFParameters.trim()"

          * "ReaxFFParameters.apply_default_constraints()"

          * "ReaxFFParameters.get_default_constraints()"

          * "ReaxFFParameters.yaml_load()"

      * 8.3.1.2.8. Full List of Parameter Names

      * 8.3.1.2.9. Parameter Categories

    * 8.3.1.3. SCC-DFTB repulsive potential

      * 8.3.1.3.1. DFTBSplineRepulsivePotentialParameters API

        * "DFTBSplineRepulsivePotentialParameters"

          * "DFTBSplineRepulsivePotentialParameters.__init__()"

          * "DFTBSplineRepulsivePotentialParameters.yaml_store()"

          * "DFTBSplineRepulsivePotentialParameters._get_spline_strin
            g_list()"

          * "DFTBSplineRepulsivePotentialParameters.write()"

          * "DFTBSplineRepulsivePotentialParameters.pickle_dump()"

          * "DFTBSplineRepulsivePotentialParameters.pickle_load()"

          * "DFTBSplineRepulsivePotentialParameters.get_engine()"

      * 8.3.1.3.2. TaperedDoubleExponential API

        * "TaperedDoubleExponential"

          * "TaperedDoubleExponential.__init__()"

          * "TaperedDoubleExponential.__call__()"

    * 8.3.1.4. Lennard-Jones

      * "LennardJonesParameters"

        * "LennardJonesParameters.__init__()"

        * "LennardJonesParameters.get_engine()"

        * "LennardJonesParameters.write()"

    * 8.3.1.5. No parameters (empty interface)

      * "NoParameters"

        * "NoParameters.__init__()"

        * "NoParameters.get_engine()"

        * "NoParameters.write()"

    * 8.3.1.6. ASE Parameters

      * "ASEParameters"

        * "ASEParameters.__init__()"

        * "ASEParameters._create_initial_parameters()"

        * "ASEParameters.write()"

        * "ASEParameters.get_engine()"

  * 8.3.2. Working with Parameter Interfaces

    * 8.3.2.1. Parameter Interface Basics

    * 8.3.2.2. Working with Parameters

    * 8.3.2.3. The Active Parameters Subset

    * 8.3.2.4. Storage

      * 8.3.2.4.1. Lossless Storage

    * 8.3.2.5. Relation to PLAMS Settings

    * 8.3.2.6. Parameter API

      * "Parameter"

    * 8.3.2.7. Interface Base Class API

      * "BaseParameters"

        * "BaseParameters.__init__()"

        * "BaseParameters.x"

        * "BaseParameters.names"

        * "BaseParameters.is_active"

        * "BaseParameters.range"

        * "BaseParameters.active"

        * "BaseParameters.get_engine()"

        * "BaseParameters.write()"

        * "BaseParameters.yaml_store()"

        * "BaseParameters.yaml_load()"

        * "BaseParameters.__len__()"

        * "BaseParameters.__iter__()"

        * "BaseParameters.__getitem__()"

        * "BaseParameters.__call__()"

        * "BaseParameters.__eq__()"

        * "BaseParameters.index()"

* 8.4. ParAMSJob

  * "ParAMSJob"

    * "ParAMSJob.__init__()"

    * "ParAMSJob.from_yaml()"

    * "ParAMSJob.from_inputfile()"

    * "ParAMSJob.load_external()"

    * "ParAMSJob.set_generator()"

    * "ParAMSJob.set_optimizer_selector()"

    * "ParAMSJob.set_parameters_kernel()"

    * "ParAMSJob.set_lossvalues_kernel()"

    * "ParAMSJob.add_exit_condition()"

    * "ParAMSJob.add_stopper()"

    * "ParAMSJob.add_optimizer()"

    * "ParAMSJob.get_input()"

    * "ParAMSJob.validate_input()"

    * "ParAMSJob.load_settings()"

    * "ParAMSJob.prerun()"

    * "ParAMSJob.get_errormsg()"

* 8.5. ParAMSResults

  * "ParAMSResults"

    * "ParAMSResults.__init__()"

    * "ParAMSResults.get_loss()"

    * "ParAMSResults.get_evaluation_number()"

    * "ParAMSResults.get_running_loss()"

    * "ParAMSResults.get_running_active_parameters()"

    * "ParAMSResults.get_parameter_interface_path()"

    * "ParAMSResults.get_parameter_interface()"

    * "ParAMSResults.get_ffield()"

    * "ParAMSResults.get_xtb_files()"

    * "ParAMSResults.get_production_engine_settings()"

    * "ParAMSResults.get_deployed_model_path()"

    * "ParAMSResults.get_deployed_model_paths()"

    * "ParAMSResults.get_restart_model_path()"

    * "ParAMSResults.get_restart_model_paths()"

    * "ParAMSResults.get_data_set()"

    * "ParAMSResults.get_training_set_path()"

    * "ParAMSResults.get_training_set()"

    * "ParAMSResults.get_validation_set_path()"

    * "ParAMSResults.get_validation_set()"

    * "ParAMSResults.get_training_set_ref_path()"

    * "ParAMSResults.get_training_set_ref()"

    * "ParAMSResults.get_reference_jobs_dir()"

    * "ParAMSResults.get_job_collection_path()"

    * "ParAMSResults.get_job_collection()"

    * "ParAMSResults.get_initial_parameter_interface()"

    * "ParAMSResults.get_engine_collection_path()"

    * "ParAMSResults.get_engine_collection()"

    * "ParAMSResults.get_inputfile()"

    * "ParAMSResults.get_data_set_evaluator()"

    * "ParAMSResults.plot_simple_correlation()"

    * "ParAMSResults.get_num_optimizers()"

    * "ParAMSResults.get_checkpoints()"

    * "ParAMSResults.get_all_pes_prediction_names()"

    * "ParAMSResults.get_pes_prediction()"

    * "ParAMSResults.get_sensitivities()"

    * "ParAMSResults.get_sensitivity()"

    * "ParAMSResults.get_num_bootstraps()"

    * "ParAMSResults.get_num_samples()"

    * "ParAMSResults.get_ordered_parameters()"

    * "ParAMSResults.get_parameter_rankings()"

    * "ParAMSResults.get_suggested_weights()"

* 8.6. Job and Engine Collections

  * 8.6.1. Job Collection

    * 8.6.1.1. Adding Jobs

    * 8.6.1.2. Lookup

    * 8.6.1.3. Removing Entries

    * 8.6.1.4. Renaming Entries

    * 8.6.1.5. Comparison

    * 8.6.1.6. Saving and loading

    * 8.6.1.7. Generating AMSJobs

    * 8.6.1.8. Running Collection Jobs

  * 8.6.2. Engine Collection

  * 8.6.3. Collections API

    * 8.6.3.1. JCEntry

      * "JCEntry"

        * "JCEntry.__init__()"

        * "JCEntry.from_amsjob()"

        * "JCEntry.__str__()"

        * "JCEntry.copy()"

        * "JCEntry.is_pipeable()"

        * "JCEntry.__eq__()"

        * "JCEntry.__hash__"

    * 8.6.3.2. JobCollection

      * "JobCollection"

        * "JobCollection.__init__()"

        * "JobCollection.load()"

        * "JobCollection.load_yaml()"

        * "JobCollection.duplicate_entry()"

        * "JobCollection.store()"

        * "JobCollection.from_jobids()"

        * "JobCollection.writexyz()"

        * "JobCollection.to_amsjobs()"

        * "JobCollection.run()"

        * "JobCollection.run_reference()"

        * "JobCollection.set_extra_engine()"

    * 8.6.3.3. Engine

      * "Engine"

        * "Engine.__init__()"

        * "Engine.__str__()"

        * "Engine.__eq__()"

        * "Engine.copy()"

        * "Engine.__hash__"

    * 8.6.3.4. EngineCollection

      * "EngineCollection"

        * "EngineCollection.load()"

        * "EngineCollection.store()"

    * 8.6.3.5. Collection Base Class

      * "BaseCollection"

        * "BaseCollection.__init__()"

        * "BaseCollection.load()"

        * "BaseCollection.store()"

        * "BaseCollection.add_entry()"

        * "BaseCollection.add_entry_nonstrict()"

        * "BaseCollection.remove_entry()"

        * "BaseCollection.rename_entry()"

        * "BaseCollection.duplicate_entry()"

        * "BaseCollection._check_entry()"

        * "BaseCollection.__str__()"

        * "BaseCollection.items()"

        * "BaseCollection.values()"

        * "BaseCollection.keys()"

        * "BaseCollection.__getitem__()"

        * "BaseCollection.__setitem__()"

        * "BaseCollection.__delitem__()"

        * "BaseCollection.__len__()"

        * "BaseCollection.__iter__()"

        * "BaseCollection.__add__()"

        * "BaseCollection.update()"

        * "BaseCollection.__contains__()"

        * "BaseCollection.__eq__()"

        * "BaseCollection.__ne__()"

        * "BaseCollection.__repr__()"

        * "BaseCollection.__hash__"

* 8.7. Data Set

  * 8.7.1. An example DataSet

  * 8.7.2. Load or store DataSet

  * 8.7.3. Adding entries

  * 8.7.4. Demonstration: Working with a DataSet

    * 8.7.4.1. Add an entry

    * 8.7.4.2. DataSetEntry attributes

    * 8.7.4.3. Accessing the DataSet entries

    * 8.7.4.4. Delete a DataSet entry

    * 8.7.4.5. Compute the intersection of two DataSets

    * 8.7.4.6. Split a DataSet into subsets

    * 8.7.4.7. DataSet header

    * 8.7.4.8. Save the data set

  * 8.7.5. Calculating and Adding Reference Data with AMS

  * 8.7.6. Calculating the Loss Function Value

  * 8.7.7. Checking for Consistency with a given Job Collection

  * 8.7.8. Sigma vs. weight: What is the difference?

  * 8.7.9. Data Set Entry API

    * "DataSetEntry"

  * 8.7.10. Data Set API

    * "DataSet"

      * "DataSet.__init__()"

      * "DataSet.add_entry()"

      * "DataSet.calculate_reference()"

      * "DataSet.evaluate()"

      * "DataSet.get()"

      * "DataSet.set()"

      * "DataSet.load()"

      * "DataSet.store()"

      * "DataSet.copy()"

      * "DataSet.__contains__()"

      * "DataSet.__getitem__()"

      * "DataSet.__delitem__()"

      * "DataSet.remove()"

      * "DataSet.index()"

      * "DataSet.keys()"

      * "DataSet.__len__()"

      * "DataSet.__iter__()"

      * "DataSet.__call__()"

      * "DataSet.__eq__()"

      * "DataSet.__ne__()"

      * "DataSet.__add__()"

      * "DataSet.__and__()"

      * "DataSet.__sub__()"

      * "DataSet.__str__()"

      * "DataSet.__repr__()"

      * "DataSet.jobids"

      * "DataSet.check_consistency()"

      * "DataSet.from_extractors()"

      * "DataSet.maxjobs()"

      * "DataSet.split()"

      * "DataSet.split_by_jobids()"

      * "DataSet.random()"

      * "DataSet.from_jobids()"

      * "DataSet.from_metadata()"

      * "DataSet.from_expressions()"

      * "DataSet.from_data_set_entries()"

      * "DataSet.from_weights()"

      * "DataSet.from_reference_values()"

      * "DataSet.from_atomic_expressions()"

      * "DataSet.print_contributions()"

      * "DataSet.print_residuals()"

      * "DataSet.get_predictions()"

      * "DataSet.get_unique_metadata_values()"

      * "DataSet.group_by_metadata()"

      * "DataSet.apply_weights_scheme()"

      * "DataSet.get_raveled_reference_values()"

      * "DataSet.__hash__"

* 8.8. Data Set Evaluator

  * 8.8.1. Load a data_set_predictions.yaml file

    * 8.8.1.1. Summary statistics (stats.txt)

    * 8.8.1.2. Access individual predictions and reference values
      (scatter_plots/)

  * 8.8.2. Calculate reference or run jobs

    * 8.8.2.1. Example: DataSetEvaluator.calculate_reference()

    * 8.8.2.2. Example: DataSetEvaluator.run()

  * 8.8.3. DataSetEvaluator API

    * "DataSetEvaluator"

      * "DataSetEvaluator.__init__()"

      * "DataSetEvaluator.calculate_reference()"

      * "DataSetEvaluator.run()"

      * "DataSetEvaluator.group_by()"

      * "DataSetEvaluator.__str__()"

* 8.9. Utilities

  * 8.9.1. ParAMS Converters

    * 8.9.1.1. ASE to ParAMS

      * "ase_to_params()"

    * 8.9.1.2. ParAMS to ASE

      * "params_to_ase()"

    * 8.9.1.3. AMS Job to Settings

      * "ams_to_settings()"

    * 8.9.1.4. AMS Job to Engine

      * "ams_to_engine()"

  * 8.9.2. Plotting Functions

    * "plot_residuals()"

    * "plot_predictions()"

    * "plot_history()"

    * "plot_contributions()"

  * 8.9.3. Helper functions

    * "get_extractors_for_amsjob()"

  * 8.9.4. Weights schemes

    * 8.9.4.1. Types of weights schemes

    * 8.9.4.2. Examples of weight schemes

    * 8.9.4.3. Weights schemes API

      * "WeightsScheme"

        * "WeightsScheme.__init__()"

        * "WeightsScheme.get_weights()"

        * "WeightsScheme.normalize()"

        * "WeightsScheme.__str__()"

      * "WeightsSchemeUniform"

        * "WeightsSchemeUniform.__init__()"

        * "WeightsSchemeUniform.get_weights()"

        * "WeightsSchemeUniform.__str__()"

      * "WeightsSchemeClip"

        * "WeightsSchemeClip.__init__()"

        * "WeightsSchemeClip.get_weights()"

        * "WeightsSchemeClip.__str__()"

      * "WeightsSchemeGaussian"

        * "WeightsSchemeGaussian.__init__()"

        * "WeightsSchemeGaussian.get_weights()"

        * "WeightsSchemeGaussian.__str__()"

      * "WeightsSchemeBoltzmann"

        * "WeightsSchemeBoltzmann.__init__()"

        * "WeightsSchemeBoltzmann.get_weights()"

        * "WeightsSchemeBoltzmann.__str__()"

* 8.10. Internal ParAMS classes

  * 8.10.1. Architecture Quick Reference

    * 8.10.1.1. Diagram

    * 8.10.1.2. Simple usage of some classes

  * 8.10.2. Optimization

    * 8.10.2.1. Optimization Setup

    * 8.10.2.2. Optimization API

      * "Optimization"

        * "Optimization.__init__()"

        * "Optimization.read()"

        * "Optimization.optimize()"

        * "Optimization.initial_eval()"

        * "Optimization.summary()"

        * "Optimization.__str__()"

        * "Optimization.delete()"

        * "Optimization._relog_bests()"

  * 8.10.3. Parallelization

    * "ParallelLevels"

  * 8.10.4. Constraints

  * 8.10.5. Logger

    * "Logger"

  * 8.10.6. Loss Functions

    * 8.10.6.1. Specifying the loss function

    * 8.10.6.2. Technical information

    * 8.10.6.3. Sum of Squares Error

      * "SSE"

    * 8.10.6.4. Sum of Absolute Errors

      * "SAE"

    * 8.10.6.5. Mean Absolute Error

      * "MAE"

    * 8.10.6.6. Root-Mean-Square Error

      * "RMSE"

    * 8.10.6.7. Loss Function API

      * "Loss"

        * "Loss.__init__()"

        * "Loss.__call__()"

        * "Loss.__repr__()"

  * 8.10.7. GloMPO Backend

  * 8.10.8. Experimental Features

    * 8.10.8.1. Working with Data Sets

      * 8.10.8.1.1. Data Set Sensitivity

        * "SubsetScan"

          * "SubsetScan.__init__()"

          * "SubsetScan.scan()"

          * "SubsetScan.makesteps_exp()"

          * "SubsetScan.plotscan()"

      * 8.10.8.1.2. Normalization of Data Set Weights

        * "normalize_weights()"
