larvaworld.lib.sim.subprocess_run
=================================

.. py:module:: larvaworld.lib.sim.subprocess_run


Classes
-------

.. autoapisummary::

   larvaworld.lib.sim.subprocess_run.Exec


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

.. py:class:: Exec(mode: str, conf: dict, experiment: str, run_externally: bool = True, progressbar: Any | None = None, w_progressbar: Any | None = None, **kwargs: Any)

   Subprocess execution wrapper for simulations.

   Manages simulation execution either synchronously (in-process) or
   asynchronously (as external subprocess) for non-blocking operation.


   .. py:attribute:: run_externally
      :value: True



   .. py:attribute:: mode


   .. py:attribute:: conf


   .. py:attribute:: progressbar
      :value: None



   .. py:attribute:: w_progressbar
      :value: None



   .. py:attribute:: type


   .. py:attribute:: done
      :value: False



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


   .. py:method:: run(**kwargs: Any) -> None


   .. py:method:: check() -> bool


   .. py:method:: retrieve(res: pandas.DataFrame | list[larvaworld.lib.process.LarvaDataset] | None = None) -> pandas.DataFrame | tuple[dict[str, dict[str, Any]], dict[str, Any]] | None

      Retrieve and process results from subprocess execution.

      Collects simulation results from subprocess execution and
      processes them according to experiment type and mode.

      Args:
          res: Results from subprocess - can be:
               - pd.DataFrame: Single batch endpoint data (batch mode).
               - list[LarvaDataset]: Multiple dataset results (sim mode).
               - None: Load from disk based on self.conf (default for external runs).

      Returns:
          Processed results, type depends on self.mode:
          - For 'batch' mode: DataFrame with batch results or None if load fails.
          - For 'sim' mode: tuple of (entry_dict, fig_dict) where:
            * entry_dict: {id: {'dataset': list[LarvaDataset], 'figs': dict}}
            * fig_dict: Figure dictionary (currently None - TODO)
          - None: If results cannot be retrieved.

      Example:
          >>> # After external batch run completes:
          >>> results = exec.retrieve()  # Loads from disk
          >>> if isinstance(results, pd.DataFrame):
          >>>     print(f"Batch results: {len(results)} rows")
          >>>
          >>> # For sim mode with manual results:
          >>> datasets = [LarvaDataset(dir=path) for path in paths]
          >>> entry, figs = exec.retrieve(res=datasets)



   .. py:method:: exec_run()