iphasimulator.trajectory_processing
===================================

.. py:module:: iphasimulator.trajectory_processing

.. autoapi-nested-parse::

   Configuration-driven, streaming GROMACS XTC processing for enzyme–PHA systems.

   Run ``python -m iphasimulator.trajectory_processing instrcution.txt --dry-run``.
   Paths in YAML are relative to that file. No simulation or viewer is launched.



Attributes
----------

.. autoapisummary::

   iphasimulator.trajectory_processing.WORKFLOW


Classes
-------

.. autoapisummary::

   iphasimulator.trajectory_processing.ProcessingConfig


Functions
---------

.. autoapisummary::

   iphasimulator.trajectory_processing.load_config
   iphasimulator.trajectory_processing.resolved_settings
   iphasimulator.trajectory_processing.check_output_safety
   iphasimulator.trajectory_processing.preflight
   iphasimulator.trajectory_processing.command_plan
   iphasimulator.trajectory_processing.process_trajectory
   iphasimulator.trajectory_processing.main


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

.. py:data:: WORKFLOW
   :value: 'iphasimulator.trajectory_processing.v1'


.. py:class:: ProcessingConfig

   Validated settings; all filesystem paths are absolute after loading.


   .. py:attribute:: instruction_file
      :type:  pathlib.Path


   .. py:attribute:: input_trajectory
      :type:  pathlib.Path


   .. py:attribute:: structure
      :type:  pathlib.Path


   .. py:attribute:: index
      :type:  pathlib.Path


   .. py:attribute:: output_dir
      :type:  pathlib.Path


   .. py:attribute:: schema_version
      :type:  int
      :value: 1



   .. py:attribute:: stride
      :type:  int
      :value: 100



   .. py:attribute:: pbc
      :type:  str
      :value: 'none'



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



   .. py:attribute:: center_group
      :type:  str | None
      :value: None



   .. py:attribute:: fit
      :type:  str
      :value: 'none'



   .. py:attribute:: fit_group
      :type:  str | None
      :value: None



   .. py:attribute:: output_group
      :type:  str
      :value: 'SYSTEM'



   .. py:attribute:: prepare_vmd
      :type:  bool
      :value: True



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



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



   .. py:attribute:: gmx
      :type:  str
      :value: 'gmx'



   .. py:attribute:: custom_groups
      :type:  dict[str, str]


.. py:function:: load_config(path: str | pathlib.Path) -> ProcessingConfig

   Read strict YAML, rejecting unknown/duplicate keys and invalid values.


.. py:function:: resolved_settings(cfg: ProcessingConfig) -> dict

   Return JSON/YAML-serialisable settings, including resolved paths.


.. py:function:: check_output_safety(cfg: ProcessingConfig) -> None

   Refuse raw-input containment and replacement of unowned output folders.


.. py:function:: preflight(cfg: ProcessingConfig)

   Validate files/tools, topology, named selections and the first XTC frame.

   This is read-only, including in dry-run mode. XTC contains no atom identities:
   its atom count can be checked, but provenance/order must be supplied correctly.


.. py:function:: command_plan(cfg: ProcessingConfig, executable: str, directory: pathlib.Path | None = None) -> list[dict]

   Construct separate preparation and optional fitting trjconv operations.


.. py:function:: process_trajectory(instruction_file: str | pathlib.Path, *, dry_run: bool | None = None) -> dict

   Load, validate and run once; a dry run reads only metadata/first frame.

   Results are assembled in a staging directory and published locally only after
   streaming verification. Explicit overwrite archives the previous owned result.
   Failures retain logs in the staging directory and leave previous results intact.


.. py:function:: main(argv=None)

   CLI entry point shared with the notebook.