:py:mod:`wolfgpu.injector`
==========================

.. py:module:: wolfgpu.injector

.. autoapi-nested-parse::

   Author: HECE - University of Liege, Stéphane Champailler, Pierre Archambeau
   Date: 2024

   Copyright (c) 2024 University of Liege. All rights reserved.

   This script and its content are protected by copyright law. Unauthorized
   copying or distribution of this file, via any medium, is strictly prohibited.



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

.. py:class:: SimulationProxy(glsim: wolfgpu.glsimulation.GLSimulation, global_state: wolfgpu.glsimulation.GLSimulationGlobalState, zone_of_interest: Tuple[slice, slice], simulation_current_quantity: int, original_infiltration_chronology: wolfgpu.simple_simulation.InfiltrationChronology)


   A proxy to query and update a running simulation.

   This class exists to hide the methods of the simulator from the caller
   because they are numerous and many of them are of no interest to
   the caller.

   .. py:property:: current_sim_step
      :type: int

      The current step in the simulation (starting at zero).

   .. py:property:: current_sim_time
      :type: float

      The current time in the simulation. Expressed in seconds (starting
      at zero).

   .. py:method:: _ensure_array_size(a)


   .. py:method:: _set_zone_of_interest(zone_of_interest: Tuple[slice, slice])


   .. py:method:: _updated_infiltration_chronology()


   .. py:method:: get_bathymetry() -> numpy.ndarray


   .. py:method:: set_bathymetry(b: numpy.ndarray)

      Set the bathymetry unknown over the zone of interest.

      :param b: The bathymetry values to set. The array size must be equal to the size of the
          zone of interest.


   .. py:method:: get_infiltration_zones() -> numpy.ndarray


   .. py:method:: set_infiltration_zones(b: numpy.ndarray)


   .. py:method:: get_active_infiltration_quantities()

      Get the current infiltration chronology's row: that is, the
      currently infiltrated quantities.

      :return: The current infitlration chronology's row. If none is
      active (because current time is before the chronology beginning)
      then `None` is returned.


   .. py:method:: set_active_infiltration_quantities(q) -> None

      Set the current infiltration chronology's row: that is, set the
      infiltrated quantities.


   .. py:method:: insert_infiltration_quantities(t: float, q: List[float]) -> None

      Insert or replace an infiltration chronology's row.

      :param t: Beginning time for the infiltration of the row (seconds).
      :param q: Infiltrated quantities, as many as the number of infiltrated zones.


   .. py:method:: _cell_parameters_values()


   .. py:method:: get_cell_parameter(i: int, j: int)


   .. py:method:: _h_qx_qy_cache()


   .. py:method:: get_h()


   .. py:method:: set_h(h: numpy.ndarray)

      Set the h unknown over the zone of interest.

      :param h: The h values to set. The array size must be equal to the size of the
          zone of interest.


   .. py:method:: get_qx()


   .. py:method:: set_qx(qx: numpy.ndarray)

      Set the Qx unknown over the zone of interest.

      :param qx: The Qx values to set. The array size must be equal to the size of the
         zone of interest.


   .. py:method:: get_qy()


   .. py:method:: set_qy(qy: numpy.ndarray)

      Set the Qy unknown over the zone of interest.

      :param qy: The Qy values to set. The array size must be equal to the size of the
          zone of interest.



.. py:class:: SimulationInjector


   Bases: :py:obj:`abc.ABC`

   .. autoapi-inheritance-diagram:: wolfgpu.injector.SimulationInjector
      :parts: 1
      :private-bases:

   Injectors allow small python scripts to be run at several point in time during
   the simulation. The goal of these script should be to update the simulation in
   real time, potentially affecting the simulation outcome.

   Inkjectors are called between simulation steps (that is after the end of a
   step and before the beginning of the next step).

   .. py:method:: active_zone() -> tuple[slice, slice]
      :abstractmethod:

      The zone that this injector wants to update expressed as a tuple of two slices.
      The first slice gives the columns span, the second gives the rows span.

      This zone must be constant across the simulation. In particular, it
      must be evaluable before the simulation has started.

      We limit the region where updates are necessary to avoid
      downloading/uploading potentially big textures to the GPU.


   .. py:method:: time_to_new_injection(current_step: int, current_time: float) -> wolfgpu.simple_simulation.SimulationDuration

      How long the simulator must wait before calling
      `None` means the injector should not be called anymore.

      This method is independent because it will be called once
      at the beginning of the simulation to get the time of the first
      update.

      :param current_step: The current step in the simulation.
      :param current_time: The current time in the simulation, expressed in seconds.
      :return: A `SimulationDuration`. `None` means the injector should not be called anymore.


   .. py:method:: do_updates(sim_proxy: SimulationProxy) -> None

      This method will be called after the `time_to_first_injection` or
      after the time it itself returned.

      :return: Return the time the simulator must wait before calling this
         method again. Return `None` if you don't want to be called anymore.
      :rtype: SimulationDuration