larvaworld.lib.sim.ABM_model
============================

.. py:module:: larvaworld.lib.sim.ABM_model

.. autoapi-nested-parse::

   Basic Agent-based modeling classes



Classes
-------

.. autoapisummary::

   larvaworld.lib.sim.ABM_model.BasicABModel
   larvaworld.lib.sim.ABM_model.ABModel


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

.. py:class:: BasicABModel(id: str = 'ABModel', parameters: Any | None = None, _run_id: Any | None = None, **kwargs: Any)

   Basic Class for the Agent-based model
   Extends the agentpy Model class



   .. py:attribute:: p


   .. py:attribute:: type
      :value: 'BasicABModel'



   .. py:attribute:: id
      :value: 'ABModel'



   .. py:attribute:: t
      :value: 0



   .. py:attribute:: running
      :value: False



   .. py:attribute:: random


   .. py:attribute:: nprandom


   .. py:attribute:: reporters


   .. py:attribute:: output


   .. py:method:: as_function(**kwargs: Any)
      :classmethod:


      Converts the model into a function that can be used with the
      `ema_workbench <https://emaworkbench.readthedocs.io/>`_ library.

      Arguments:
          **kwargs: Additional keyword arguments that will passed
              to the model in addition to the parameters.

      Returns:
          function:
              The model as a function that takes
              parameter values as keyword arguments and
              returns a dictionary of reporters.




   .. py:property:: info


   .. py:method:: report(rep_keys: Any, value: Any | None = None) -> None

      Reports a new simulation result.
      Reporters are meant to be 'summary statistics' or 'evaluation measures'
      of the simulation as a whole, and only one value can be stored per run.
      In comparison, variables that are recorded with :func:`Model.record`
      can be recorded multiple times for each time-step and object.

      Arguments:
          rep_keys (str or list of str):
              Name(s) of the reporter(s) to be documented.
          value (int or float, optional): Value to be reported.
              The same value will be used for all `rep_keys`.
              If none is given, the values of object attributes
              with the same name as each rep_key will be used.

      Examples:
          Store a reporter `x` with a value `42`::

              model.report('x', 42)

          Define a custom model that stores a reporter `sum_id`
          with the sum of all agent ids at the end of the simulation::

              class MyModel(ap.Model):
                  def setup(self):
                      agents = ap.AgentList(self, self.p.agents)
                  def end(self):
                      self.report('sum_id', sum(self.agents.id))

          Running an experiment over different numbers of agents for this
          model yields the following datadict of reporters::

              >>> sample = ap.sample({'agents': (1, 3)}, 3)
              >>> exp = ap.Experiment(MyModel, sample)
              >>> results = exp.run()
              >>> results.reporters
                      sum_id
              run_id
              0            1
              1            3
              2            6




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

      Defines the model's actions before the first simulation step.
      Can be overwritten to initiate agents and environments.



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

      Defines the model's actions
      during each simulation step (excluding `t==0`).
      Can be overwritten to define the models' main dynamics.



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

      Defines the model's actions
      after each simulation step (including `t==0`).
      Can be overwritten for the recording of dynamic variables.



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

      Defines the model's actions after the last simulation step.
      Can be overwritten for final calculations and reporting.



   .. py:method:: set_parameters(parameters: Any) -> None

      Adds and/or updates the parameters of the model.



   .. py:method:: sim_setup(steps: Any | None = None, seed: Any | None = None) -> None

      Prepares time-step 0 of the simulation.
      Initiates (additional) steps and the two random number generators,
      and then calls :func:`Model.setup` and :func:`Model.update`.



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

      Proceeds the simulation by one step, incrementing `Model.t` by 1
      and then calling :func:`Model.step` and :func:`Model.update`.



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

      Reset model to initial conditions.



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

      Stops :meth:`Model.run` during an active simulation.



   .. py:method:: run(steps: Any | None = None, seed: Any | None = None)

      Executes the simulation of the model.
      Can also be used to continue a partly-run simulation
      for a given number of additional steps.

      It starts by calling :func:`Model.run_setup` and then calls
      :func:`Model.run_step` until the method :func:`Model.stop` is called
      or `steps` is reached. After that, :func:`Model.end` and
      :func:`Model.create_output` are called. The simulation results can
      be found in :attr:`Model.output`.

      Arguments:
          steps (int, optional):
              Number of (additional) steps for the simulation to run.
              If passed, the parameter 'Model.p.steps' will be ignored.
              The simulation can still be stopped with :func:'Model.stop'.
          seed (int, optional):
              Seed to initialize the model's random number generators.
              If none is given, the parameter 'Model.p.seed' is used.
              If there is no such parameter, a random seed will be used.
              For a partly-run simulation, this argument will be ignored.
          display (bool, optional):
              Whether to display simulation progress (default True).

      Returns:
          DataDict: Recorded variables and reporters.




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

      Generates a :class:`DataDict` with dataframes of all recorded
      variables and reporters, which will be stored in :obj:`Model.output`.



.. py:class:: ABModel(**kwargs: Any)

   Bases: :py:obj:`BasicABModel`, :py:obj:`larvaworld.lib.reg.generators.SimConfigurationParams`


   Basic Class for the Agent-based model
   Extends the agentpy Model class