mythos.simulators.oxdna
=======================

.. py:module:: mythos.simulators.oxdna

.. autoapi-nested-parse::

   oxDNA simulator module.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/mythos/simulators/oxdna/oxdna/index
   /autoapi/mythos/simulators/oxdna/utils/index


Attributes
----------

.. autoapisummary::

   mythos.simulators.oxdna.CMAKE_BIN_ENV_VAR
   mythos.simulators.oxdna.ERR_BUILD_SETUP_FAILED
   mythos.simulators.oxdna.ERR_INPUT_FILE_NOT_FOUND
   mythos.simulators.oxdna.ERR_MISSING_REQUIRED_KEYS
   mythos.simulators.oxdna.MAKE_BIN_ENV_VAR


Classes
-------

.. autoapisummary::

   mythos.simulators.oxdna.oxDNASimulator


Functions
---------

.. autoapisummary::

   mythos.simulators.oxdna._guess_binary_location


Package Contents
----------------

.. py:data:: CMAKE_BIN_ENV_VAR
   :value: 'CMAKE_BIN_PATH'


.. py:data:: ERR_BUILD_SETUP_FAILED
   :value: 'OXDNA build setup failed wiht return code: {}'


.. py:data:: ERR_INPUT_FILE_NOT_FOUND
   :value: 'Input file not found: {}'


.. py:data:: ERR_MISSING_REQUIRED_KEYS
   :value: 'Missing required keys: {}'


.. py:data:: MAKE_BIN_ENV_VAR
   :value: 'MAKE_BIN_PATH'


.. py:function:: _guess_binary_location(bin_name: str, env_var: str) -> pathlib.Path | None

   Guess the location of a binary.


.. py:class:: oxDNASimulator

   Bases: :py:obj:`mythos.simulators.base.InputDirSimulator`


   A sampler base on running an oxDNA simulation.

   This simulator runs an oxDNA simulation in a subprocess, first compiling
   oxDNA from source with the provided parameters, or by using a precompiled
   binary (in the case parameter updates are not desired).

   :param input_dir: Path to the directory containing the oxDNA input file.
   :param sim_type: The type of oxDNA simulation to run.
   :param energy_fn: The energy function to use for default parameter updates.
   :param n_build_threads: Number of threads to use when building oxDNA from
                           source.
   :param logger_config: Configuration for the logger.
   :param binary_path: Path to a precompiled oxDNA binary to use. This is mutually
                       exclusive with source_path. When provided, the binary will be called
                       and no recompilation will be performed. In such a case, parameters
                       cannot be updated, and if supplied to the run will result in an
                       error unless ignore_params is set to True.
   :param source_path: Path to the oxDNA source code to compile. Updating
                       parameters in this simulator requires compiling oxDNA from source
                       with the parameters built into the object code.
   :param ignore_params: Whether to ignore provided parameters when running the
                         simulation. This argument is required to be True if there is no
                         source_path set and parameters are passed.
   :param overwrite_input: Whether to overwrite the input directory or copy it. If
                           this is False (default), the contents of the input_dir will be
                           copied to a temporary directory for running the simulation to avoid
                           overwriting input.
   :param input_overrides: Key-value pairs to override in the input file. The
                           values accept scalar values that can be converted to str. For
                           example: {"T": "275K", "steps": 10000}. WARNING: no validation is
                           performed on the provided key-value pairs.


   .. py:attribute:: sim_type
      :type:  mythos.utils.types.oxDNASimulatorType


   .. py:attribute:: energy_fn
      :type:  mythos.energy.base.EnergyFunction


   .. py:attribute:: n_build_threads
      :type:  int
      :value: 4



   .. py:attribute:: logger_config
      :type:  dict[str, Any] | None
      :value: None



   .. py:attribute:: binary_path
      :type:  pathlib.Path | None
      :value: None



   .. py:attribute:: source_path
      :type:  pathlib.Path | None
      :value: None



   .. py:attribute:: ignore_params
      :type:  bool
      :value: False



   .. py:attribute:: input_overrides
      :type:  dict[str, Any]


   .. py:method:: __post_init__(*args, **kwds) -> None

      Check the validity of the configuration.



   .. py:method:: with_cached_build(binary_path: pathlib.Path) -> None

      Switch to use a precompiled binary.

      This may be useful when running on a cluster with a shared file system,
      or running on a single machine, particularly in cases where:
          N_simulators * n_build_threads > N_cpu_cores.

      Caution: the user is responsible for ensuring that the binary at
      provided path is pre-built for the appropriate parameter set, there is
      no check performed at simulation run-time to verify this.



   .. py:method:: run_simulation(input_dir: pathlib.Path, opt_params: mythos.utils.types.Params | None = None, seed: float | None = None, **_) -> mythos.simulators.base.SimulatorOutput

      Run an oxDNA simulation.



   .. py:method:: _read_trajectory(input_dir: pathlib.Path) -> mythos.simulators.io.SimulatorTrajectory


   .. py:method:: build(*, input_dir: pathlib.Path, new_params: mythos.utils.types.Params, input_config: dict | None = None) -> None

      Update the simulation.

      This function will recompile the oxDNA binary with the new parameters.