Python API
**********

Python APIs for the SimpleActiveLearningJob (a type of PLAMS Job) and
SimpleActiveLearningResults classes.

Import it like this:

   #!/usr/bin/env amspython

   from scm.simple_active_learning import SimpleActiveLearningJob

See also:

  * Python Examples tagged Active Learning

  * ParAMS Python quickstart

  * Getting Started with PLAMS

  * Python Input System for AMS (PISA) (*new in AMS2024*)


SimpleActiveLearningJob
=======================

class SimpleActiveLearningJob(name='simple_active_learning_job', driver=None, settings=None, molecule=None, **kwargs)

   PLAMS Job class for running Simple Active Learning.

   This class inherits from the PLAMS SingleJob class. For usage, see
   the SingleJob documentation.

   If you supply a Settings object to the constructor, it will be
   converted to a PISA (Python Input System for AMS) object.

   Attributes:

   * "input": an alias for self.settings.input

   __init__(name='simple_active_learning_job', driver=None, settings=None, molecule=None, **kwargs)

      Initialize the SimpleActiveLearningJob.

      name : str
         The name of the job

      driver : scm.input_classes.drivers.SimpleActiveLearning
         PISA object describing the input to the SimpleActiveLearning
         program

      settings: scm.plams.Settings
         All settings for the job. Input settings in the PLAMS
         settings format under "settings.input" are automatically
         converted to the PISA format. You can specify
         "settings.runscript.nproc" to set the total number of cores
         to run on.

      molecule: scm.plams.Molecule or Dict[str, scm.plams.Molecule]
         The initial system in PLAMS Molecule format, or if the
         simulation requires multiple input system, given as a
         dictionary where the main system has an empty string """" as
         the key.

   classmethod load_external(path, finalize=False)

      Load a previous SimpleActiveLearning job from disk.

      Parameters:
         * **path** (*Union**[**str**, **Path**]*) -- A reactions
           discovery results folder.

         * **finalize** (*bool**, **optional*) -- See SingleJob,
           defaults to False

      Raises:
         **FileError** -- When the path does not exist.

      Returns:
         An initialized SimpleActiveLearningJob

      Return type:
         SimpleActiveLearningJob

   classmethod from_rkf(path)

      Initialize a job from a simple_active_learning.rkf file.

      Parameters:
         **path** (*str*) -- Path to a simple_active_learning.rkf file

      Returns:
         A new SimpleActiveLearningJob instance based on the
         information found in path.

      Return type:
         SimpleActiveLearningJob

   classmethod from_input(text_input)

      Initialize a job from text input.

      Parameters:
         **text_input** (*str*) -- A multiline text input

      Returns:
         A SimpleActiveLearningJob

      Return type:
         SimpleActiveLearningJob

   classmethod restart_from(job, name='simple_active_learning_job', molecule=None, keep_initial_reference_data_settings=False, job_prefix=None)

      Returns a SimpleActiveLearningJob with LoadModel set
      appropriately.

      Parameters:
         * **job** (*Union**[**SimpleActiveLearningJob**, **str**,
           **Path**]*) -- A previously finished
           SimpleActiveLearningJob (or path to its results folder)

         * **molecule** (*Optional**[**Molecule**]**, **default None*)
           -- Input molecule for the new job. If None, use the final
           molecule from "job".

         * **keep_initial_reference_data_settings** (*bool**,
           **default False*) -- Whether to keep the
           ActiveLearning%InitialReferenceData block from the original
           job.

      Returns:
         Returns a new SimpleActiveLearningJob.

      Return type:
         SimpleActiveLearningJob

   get_errormsg()

      Returns the contents of the jobname.err file if it exists. If
      the file does not exist an empty string is returned.

      Returns:
         The error message

      Return type:
         str

   get_input()

      Obtain the input string.

      Returns:
         An input string.

      Return type:
         str

   get_runscript()

      Generates the runscript. Use
      "self.settings.runscript.preamble_lines = ['line1', 'line2']" or
      similarly for "self.settings.runscript.postamble_lines" to set
      custom settings.

      "self.settings.runscript.nproc" controls the total number of
      cores to run on.

   check()

      Returns True if "NORMAL TERMINATION" is given in the General
      section of simple_active_learning.rkf.

   ok()

      Synonym for check()

   run(jobrunner=None, jobmanager=None, watch=False, **kwargs)

      Runs the job

   property input

      PISA format input


SimpleActiveLearningResults
===========================

Note:

  You should not initialize SimpleActiveLearningResults yourself.
  Instead always access it as "job.results", where "job" is of type
  SimpleActiveLearningJob.

class SimpleActiveLearningResults(job)

   Results class for SimpleActiveLearningJob

   get_errormsg()

      Returns the error message of this calculation if any were
      raised.

      Returns:
         String containing the error message.

      Return type:
         str

   rkfpath(file='simple_active_learning')

      Returns path to simple_active_learning.rkf

      Returns:
         Path to simple_active_learning.rkf

      Return type:
         str

   readrkf(section, variable)

      Reads simple_active_learning.rkf

   get_simulation_directory(step=None, attempt=None, allow_final=True)

      Returns the absolute path to a simulation directory.

      step: optional, int
         The step number. If not specified will be autodetected to the
         last step.

      attempt: optional, int
         The attempt number. If not specified will be autodetected to
         the last attempt.

      allow_final: bool
         If True and step=None and attempt=None, then it will return
         final_production_simulation if it exists.

   get_main_molecule(allow_final=True)

      Returns AMSResults.get_main_molecule() on the main simulation
      job.

      Parameters:
         **allow_final** (*bool**, **optional*) -- _description_,
         defaults to True

      Returns:
         _description_

      Return type:
         Union[Molecule, Dict[str, Molecule], None]

   get_params_results_directory(step=None, attempt=None, allow_final=True)

      Returns the absolute path to a ParAMS results directory that can
      be loaded with ParAMSJob.load_external or used as LoadModel in
      ParAMS or SimpleActiveLearning input.

      step: optional, int
         The step number. If not specified will be autodetected to the
         last step.

      attempt: optional, int
         The attempt number. If not specified will be autodetected to
         the last attempt.

      allow_final: bool
         If True and step=None and attempt=None, then it will return
         final_training/results if it exists.

   get_params_job(step=None, attempt=None, allow_final=True)

      Returns the latest ParAMSJob. This can be used to analyze
      results from the parametrization.

      Parameters:
         * **step** (*Optional**[**int**]**, **optional*) --
           _description_, defaults to None

         * **attempt** (*Optional**[**int**]**, **optional*) --
           _description_, defaults to None

         * **allow_final** (*bool**, **optional*) -- _description_,
           defaults to True

      Returns:
         _description_

      Return type:
         ParAMSJob

   get_production_engine_settings(step=None, attempt=None, allow_final=True)

      Returns the production engine settings from the ParAMSJob

   get_reference_data_directory(step=None, attempt=None)

      Returns the absolute path to a reference data directory that can
      be opened in the ParAMS GUI or which lets you initialize a
      ParAMSJob with ParAMSJob.from_yaml()

      step: optional, int
         The step number. If not specified will be autodetected to the
         last step.

      attempt: optional, int
         The attempt number. If not specified will be autodetected to
         the last attempt.

      allow_final: bool
         If True and step=None and attempt=None, then it will return
         final_training/results if it exists.
