picometer.instructions
======================

.. py:module:: picometer.instructions

.. autoapi-nested-parse::

   Picometer routine file in a yaml file that contains a list of settings
   and instructions to be sequentially executed by the parser.
   In accordance with the yaml format, the file can comprise several
   "yaml files" / "picometer routines" seperated by "
   ---".
   However, these "files"/"routines" are ultimately concatenated
   and converted into a list of instructions.



Attributes
----------

.. autoapisummary::

   picometer.instructions.logger


Classes
-------

.. autoapisummary::

   picometer.instructions.Instruction
   picometer.instructions.Routine
   picometer.instructions.ProcessorProtocol
   picometer.instructions.BaseInstructionHandlerType
   picometer.instructions.BaseInstructionHandler
   picometer.instructions.SerialInstructionHandler
   picometer.instructions.LoadInstructionHandler
   picometer.instructions.SelectInstructionHandler
   picometer.instructions.RecenterInstructionHandler
   picometer.instructions.GroupInstructionHandler
   picometer.instructions.CentroidInstructionHandler
   picometer.instructions.LineInstructionHandler
   picometer.instructions.PlaneInstructionsHandler
   picometer.instructions.CoordinatesInstructionHandler
   picometer.instructions.DisplacementInstructionHandler
   picometer.instructions.DistanceInstructionHandler
   picometer.instructions.AngleInstructionHandler
   picometer.instructions.DihedralInstructionHandler
   picometer.instructions.WriteInstructionHandler
   picometer.instructions.ClearInstructionHandler
   picometer.instructions.SetInstructionHandler


Module Contents
---------------

.. py:data:: logger

.. py:class:: Instruction(raw_instruction: Union[dict, str] = None, /, **kwargs)

   An individual atomic instruction to be processed by the processor


   .. py:attribute:: keyword
      :type:  str


   .. py:attribute:: raw_kwargs
      :type:  Union[str, dict[str, Any]]


   .. py:method:: __eq__(other)


   .. py:method:: __repr__() -> str


   .. py:property:: handler
      :type: type



   .. py:property:: kwargs
      :type: dict[str, Any]



   .. py:method:: as_dict() -> dict[str:Union[str, dict]]


.. py:class:: Routine

   Bases: :py:obj:`collections.deque`\ [\ :py:obj:`Instruction`\ ]


   A queue of subsequent `Instruction`s to be executed by the processor.
   It can be created either in a single step from an input file,
   or by iteratively right-appending individual instructions.


   .. py:method:: concatenate(routines: list[Routine])
      :classmethod:



   .. py:method:: from_dict(dict_: dict) -> Routine
      :classmethod:



   .. py:method:: from_string(text: str) -> Routine
      :classmethod:



   .. py:method:: from_yaml(path: Union[str, pathlib.Path]) -> Routine
      :classmethod:



   .. py:method:: as_dict() -> dict[str, list[dict]]


   .. py:method:: to_yaml(path: Union[str, pathlib.Path]) -> None


.. py:class:: ProcessorProtocol

   Bases: :py:obj:`Protocol`


   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing), for example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto(Protocol[T]):
           def meth(self) -> T:
               ...


   .. py:attribute:: evaluation_table
      :type:  pandas.DataFrame


   .. py:attribute:: history
      :type:  Routine


   .. py:attribute:: model_states
      :type:  picometer.models.ModelStates


   .. py:attribute:: selection
      :type:  list[picometer.atom.Locator]


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


.. py:class:: BaseInstructionHandlerType

   Bases: :py:obj:`type`


   Metaclass that automatically registers new handlers in `REGISTRY`


   .. py:attribute:: REGISTRY


.. py:class:: BaseInstructionHandler(processor: ProcessorProtocol)

   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :type:  str
      :value: None



   .. py:attribute:: kwargs
      :type:  dict[str:type]
      :value: None



   .. py:method:: handle(instruction: Instruction) -> None
      :abstractmethod:


      Alter the state of the processor according to the instruction



   .. py:attribute:: processor


   .. py:method:: clear_selection()


   .. py:method:: clear_selection_after_use() -> None


.. py:class:: SerialInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction



   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None
      :abstractmethod:


      Abstract function to handle a process a single model state



   .. py:method:: _collect_shapes(ms: picometer.models.ModelState) -> list[picometer.shapes.ExplicitShape]


.. py:class:: LoadInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :value: 'load'



   .. py:attribute:: kwargs


   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction



   .. py:method:: _load_model_state(cif_path, block_name)


.. py:class:: SelectInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :value: 'select'



   .. py:attribute:: kwargs


   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction



.. py:class:: RecenterInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :value: 'recenter'



   .. py:attribute:: kwargs


   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction



.. py:class:: GroupInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :value: 'group'



   .. py:attribute:: kwargs


   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction



.. py:class:: CentroidInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'centroid'



   .. py:attribute:: kwargs


   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: LineInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'line'



   .. py:attribute:: kwargs


   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: PlaneInstructionsHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'plane'



   .. py:attribute:: kwargs


   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: CoordinatesInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'coordinates'



   .. py:attribute:: kwargs
      :value: None



   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: DisplacementInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'displacement'



   .. py:attribute:: kwargs
      :value: None



   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: DistanceInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'distance'



   .. py:attribute:: kwargs


   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: AngleInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'angle'



   .. py:attribute:: kwargs


   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: DihedralInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`SerialInstructionHandler`


   Handlers that handle model states independently and exhausts selection


   .. py:attribute:: name
      :value: 'dihedral'



   .. py:attribute:: kwargs


   .. py:method:: handle_one(instruction: Instruction, ms_key: str, ms: picometer.models.ModelState) -> None

      Abstract function to handle a process a single model state



.. py:class:: WriteInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :value: 'write'



   .. py:attribute:: kwargs


   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction



.. py:class:: ClearInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :value: 'clear'



   .. py:attribute:: kwargs


   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction



.. py:class:: SetInstructionHandler(processor: ProcessorProtocol)

   Bases: :py:obj:`BaseInstructionHandler`


   Base `InstructionHandler` class to be used for managing all instructions.
   Must define the following attributes and methods:
   - `name`: if given, auto-registers handler in the REGISTRY
   - `kwargs`: if given, auto-converts string arguments into dict
   - `handle()`: the method called be processor to handle instruction


   .. py:attribute:: name
      :value: 'set'



   .. py:attribute:: kwargs
      :value: None



   .. py:method:: handle(instruction: Instruction) -> None

      Alter the state of the processor according to the instruction