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:data:: unit_registry .. py:class:: SimulationProxy(glsim: wolfgpu.glsimulation.GLSimulation, global_state: wolfgpu.glsimulation.GLSimulationGlobalState, active_zone: wolfhece.wolf_array.header_wolf, simulation_current_quantity: int, original_infiltration_chronology: wolfgpu.simplesimu.infiltrations.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:attribute:: _glsim :type: wolfgpu.glsimulation.GLSimulation .. py:attribute:: _global_state .. py:attribute:: _active_zone :type: wolfhece.wolf_array.header_wolf .. py:attribute:: _cached_bathymetry :value: None Cached bathymetry over the whole simulation domain. (j,i) indexing. .. py:attribute:: _cached_h_qx_qy :value: None Cached h, qx, qy over the whole simulation domain. (j,i) indexing. .. py:attribute:: _cached_infiltration_zones :value: None Cached infiltration zones over the whole simulation domain. (j,i) indexing. .. py:attribute:: _cached_manning :value: None Cached Manning's n over the whole simulation domain. (j,i) indexing. .. py:attribute:: _cached_cell_param_pr_bcs_values :value: None .. py:attribute:: _cached_cell_param_or_bcs_indices :value: None .. py:attribute:: _bathymetry_was_set :value: False .. py:attribute:: _h_qx_qy_was_set :value: False .. py:attribute:: _infiltration_zones_was_set :value: False .. py:attribute:: _infiltration_chronology_was_set :value: False .. py:attribute:: _manning_was_set :value: False .. py:attribute:: _param_bc_was_set :value: False .. py:attribute:: _param_new_bc_was_set :value: False .. py:attribute:: _simulation_current_quantity .. py:attribute:: _infiltration_chronology .. py:method:: _ensure_array_size(a) Ensure the array size is the one expected for the active zone. :param a: The array to check. .. py:method:: _set_active_zone(zone_of_interest: wolfhece.wolf_array.header_wolf) Set a new active zone for this injector. :param zone_of_interest: The new active zone. .. py:property:: active_zone :type: wolfhece.wolf_array.header_wolf .. py:property:: _active_zones_as_slices Slices corresponding to the active zone of the injector, in simulation coordinates. 0-based indexing. We need to convert from world coordinates to simulation coordinates by subtracting the origin offsets. .. py:property:: _active_zones_as_bcs_slices .. py:method:: _updated_infiltration_chronology() .. 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:: get_bathymetry() -> numpy.ndarray Get the bathymetry unknown over the zone of interest. :return: The bathymetry values over the zone of interest. We cache the bathymetry to avoid multiple d/l from the GPU. .. py:method:: set_bathymetry(b: numpy.ndarray | wolfhece.wolf_array.WolfArray) 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_mannings_n() -> numpy.ndarray Get the Manning's n unknown over the zone of interest. :return: The Manning's n values over the zone of interest. We cache the Manning's n to avoid multiple d/l from the GPU. .. py:method:: set_mannings_n(b: numpy.ndarray | wolfhece.wolf_array.WolfArray) Set the Manning's n unknown over the zone of interest. :param b: The Manning's n values to set. The array size must be equal to the size of the zone of interest. .. py:method:: get_infiltration_zones() -> numpy.ndarray Get the infiltration zones over the zone of interest. Infiltration zone are 1-based indices as it is a WOLF convention. :return: The infiltration zones over the zone of interest. We cache the infiltration zones to avoid multiple d/l from the GPU. .. py:method:: set_infiltration_zones(b: numpy.ndarray | wolfhece.wolf_array.WolfArray) Set the infiltration zones over the zone of interest. :param b: The infiltration zones to set. The array size must be equal to the size of the zone of interest. .. 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_bcs_params_values_indices() Get the cell parameters values over the whole simulation domain. :return: A numpy array with the cell parameters values. .. py:method:: _convert_cached_bcs_params_indices() Get the cached BCs params indices over the whole simulation domain. .. py:method:: _add_new_bc_param(i: int, j: int) .. py:method:: get_BC_value(i: int, j: int, param_type: wolfgpu.glsimulation.BoundaryConditionIndices, zero_based: bool = False) -> float Get the cell parameter at location (i,j) in simulation coordinates. :param i: The i index (0-based or 1-based) in simulation coordinates. :param j: The j index (0-based or 1-based) in simulation coordinates. :param param_type: The type of parameter to get. See `BoundaryConditionIndices` enum for possible values. :param zero_based: If `True`, then (i,j) are 0-based indices. If `False`, then (i,j) are 1-based indices. :return: The cell parameter value at location (i,j). .. py:method:: get_bridge_roof_parameter(i: int, j: int, zero_based: bool = False) -> float Get the cell parameter at location (i,j) in simulation coordinates. :param i: The i index (0-based or 1-based) in simulation coordinates. :param j: The j index (0-based or 1-based) in simulation coordinates. :param zero_based: If `True`, then (i,j) are 0-based indices. If `False`, then (i,j) are 1-based indices. :return: The cell parameter value at location (i,j). .. py:method:: get_bridge_roof_in_active_zone_as_ijval(zero_based: bool = False) -> Tuple[numpy.ndarray, numpy.ndarray] Get all the bridge roof elevations over the active zone. .. py:method:: get_bridge_roof_in_active_zone_as_array() -> numpy.ndarray Get all the bridge roof elevations over the active zone as a full array. .. py:method:: _get_BCs_in_active_zone_as_ijval(param_type: wolfgpu.glsimulation.BoundaryConditionIndices, zero_based: bool = False) -> numpy.ndarray Get all the cell parameters of type `param_type` over the active zone. :param param_type: The type of parameter to get. See `BoundaryConditionIndices` enum for possible values. :return: A numpy array with the cell parameters of type `param_type` over the active zone. .. py:method:: get_BCs_in_active_zone_as_ijval(param_type: wolfgpu.glsimulation.BoundaryConditionsTypes, direction: wolfgpu.glsimulation.Direction, zero_based: bool = False) -> Tuple[numpy.ndarray, numpy.ndarray] Get all the cell parameters of type `param_type` over the active zone. :param param_type: The type of parameter to get. See `BoundaryConditionsTypes` enum for possible values. :param direction: The direction of the boundary condition. :return: A numpy array with the cell parameters of type `param_type` .. py:method:: get_BCs_in_active_zone_as_dict(zero_based: bool = False) -> dict .. py:method:: get_potential_BCs_in_active_zone(zero_based: bool = False) -> dict .. py:method:: get_BCs_values_in_active_zone_as_array(param_type: wolfgpu.glsimulation.BoundaryConditionIndices) -> numpy.ndarray Get all the cell parameters of type `param_type` over the active zone as a full array. :param param_type: The type of parameter to get. See `BoundaryConditionIndices` enum for possible values. :return: A numpy array with the cell parameters of type `param_type` over the active zone. .. py:method:: set_bridge_roof_parameter(i: int, j: int, value: float, zero_based: bool = False) -> None Set the cell parameter at location (i,j) in simulation coordinates. :param i: The i index (0-based or 1-based) in simulation coordinates. :param j: The j index (0-based or 1-based) in simulation coordinates. :param value: The value to set. :param zero_based: If `True`, then (i,j) are 0-based indices. If `False`, then (i,j) are 1-based indices. .. py:method:: set_bridge_roof_parameter_from_array(values: numpy.ndarray | wolfhece.wolf_array.WolfArray) -> None Set the bridge roof elevation parameter over the active zone from an array. :param values: The array of values to set. Its shape must match the active zone shape. .. py:method:: _set_BC_or_parameter_value(i: int, j: int, param_type: wolfgpu.glsimulation.BoundaryConditionIndices, value: float, zero_based: bool = False, check_neighbor: bool = True) -> None Set the cell parameter at location (i,j) in simulation coordinates. :param i: The i index (0-based or 1-based) in simulation coordinates. :param j: The j index (0-based or 1-based) in simulation coordinates. :param param_type: The type of parameter to set. See `BoundaryConditionIndices` enum for possible values. :param value: The value to set. :param zero_based: If `True`, then (i,j) are 0-based indices. If `False`, then (i,j) are 1-based indices. .. py:method:: set_BC_value(i: int, j: int, param_type: wolfgpu.glsimulation.BoundaryConditionsTypes, direction: wolfgpu.glsimulation.Direction, value: float, zero_based: bool = False) -> None Set the cell parameter at location (i,j) in simulation coordinates. :param i: The i index (0-based or 1-based) in simulation coordinates. :param j: The j index (0-based or 1-based) in simulation coordinates. :param param_type: The type of parameter to set. See `BoundaryConditionIndices` enum for possible values. :param value: The value to set. :param zero_based: If `True`, then (i,j) are 0-based indices. If `False`, then (i,j) are 1-based indices. .. py:method:: _h_qx_qy_cache() .. py:method:: get_h() Get the h unknown over the zone of interest. :return: The h values over the zone of interest. .. py:method:: set_h(h: numpy.ndarray | wolfhece.wolf_array.WolfArray) 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() Get the Qx unknown over the zone of interest. :return: The Qx values over the zone of interest. .. py:method:: set_qx(qx: numpy.ndarray | wolfhece.wolf_array.WolfArray) 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() Get the Qy unknown over the zone of interest. :return: The Qy values over the zone of interest. .. py:method:: set_qy(qy: numpy.ndarray | wolfhece.wolf_array.WolfArray) 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:method:: get_froude() Get the Froude number over the zone of interest. :return: The Froude number values over the zone of interest. .. py:method:: get_head() Get the water head over the zone of interest. :return: The water head values over the zone of interest. .. py:method:: get_wolfarray(which_quantity: Literal['h', 'qx', 'qy', 'froude', 'head', 'infiltration', 'manning'], mask_nodata: bool = True, mask_null_h: bool = False) -> wolfhece.wolf_array.WolfArray Get a wolf array over the zone of interest. :param which_quantity: The quantity to get. :return: The wolf array values over the zone of interest. .. py:method:: set_wolfarray(which_quantity: Literal['bathy', 'h', 'qx', 'qy', 'infiltration', 'manning'], wa: wolfhece.wolf_array.WolfArray) -> None Set a wolf array over the zone of interest. :param which_quantity: The quantity to set. :param wa: The wolf array to set over the zone of interest. .. py:method:: get_result_path() -> str Get the path to the result folder for this simulation. :return: The path to the result folder. .. 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. Injectors are called between simulation steps (that is after the end of a step and before the beginning of the next step). .. py:method:: compatibility() :classmethod: :abstractmethod: Give the versions of Python and wolfgpu this injector should work with. The versions numbers can be expressed as version constraints. In that case they must match [SimpleSpec](https://python-semanticversion.readthedocs.io/en/latest/reference.html?highlight=simplespec#semantic_version.SimpleSpec) of the [semantic_version](https://pypi.org/project/semantic-version/) package. :rtype: This method returns a dictionary with two entries "python" and "wolfgpu". For example: ``` return { "python": ">=3.11", "wolfgpu": ">=1.4" } ``` .. py:method:: inject(sim_proxy: SimulationProxy) -> None :abstractmethod: This method will starting from 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 .. py:method:: do_report(proxy: SimulationProxy, rs: wolfgpu.results_store.ResultsStore, record_path: pathlib.Path) -> None :abstractmethod: This method will propose to write some reporting data. :return: Nothing. :rtype: None .. py:method:: make_from_dict(json_dict: dict) -> SimulationInjector :classmethod: Given a dictionary, create a brand new injector. This method will be called by the simulator to build the injector. :param json_dict: A `dict` that is JSON-serializable. :rtype: SimulationInjector .. py:method:: get_params() -> dict Create a dictionary from an existing injector. This method will be called by the simulator to save the injector. :rtype: A JSON-serializable dict. In practice, that means that the dict values must be either dict or simple types: int, float, string. Arrays are currently excluded. If you need them, use relative paths to files. .. py:function:: default_dict_active_zone(which_type: Literal['header_wolf', 'bounds'] = 'header_wolf') -> dict Get a default active zone dictionary that can be used to create a header_wolf. :param which_type: The type of data to save: 'header_wolf' or 'bounds'. :return: A dictionary that can be used to create a header_wolf. .. py:function:: get_injector_dict(injector_class: SimulationInjector, type_duration: Literal['time', 'step'], duration: float | int, active_zone: wolfhece.wolf_array.header_wolf | dict | None = None, source_file: str | pathlib.Path | None = None) -> dict Get a default injector dictionary that can be used to create a TimeBasedInjector or StepBasedInjector. :param type_duration: The type of duration: 'time' or 'step'. :param duration: The duration value. :return: A dictionary that can be used to create an injector.