wolfgpu.injector
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
- class wolfgpu.injector.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)[source]
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.
- _active_zone: wolfhece.wolf_array.header_wolf[source]
- _cached_bathymetry = None[source]
Cached bathymetry over the whole simulation domain. (j,i) indexing.
- _cached_infiltration_zones = None[source]
Cached infiltration zones over the whole simulation domain. (j,i) indexing.
- _cached_manning = None[source]
Cached Manning’s n over the whole simulation domain. (j,i) indexing.
- _ensure_array_size(a)[source]
Ensure the array size is the one expected for the active zone. :param a: The array to check.
- _set_active_zone(zone_of_interest: wolfhece.wolf_array.header_wolf)[source]
Set a new active zone for this injector. :param zone_of_interest: The new active zone.
- property active_zone: wolfhece.wolf_array.header_wolf[source]
- property _active_zones_as_slices[source]
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.
- property current_sim_time: float[source]
The current time in the simulation. Expressed in seconds (starting at zero).
- get_bathymetry() numpy.ndarray[source]
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.
- set_bathymetry(b: numpy.ndarray | wolfhece.wolf_array.WolfArray)[source]
Set the bathymetry unknown over the zone of interest.
- Parameters:
b – The bathymetry values to set. The array size must be equal to the size of the zone of interest.
- get_mannings_n() numpy.ndarray[source]
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.
- set_mannings_n(b: numpy.ndarray | wolfhece.wolf_array.WolfArray)[source]
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.
- get_infiltration_zones() numpy.ndarray[source]
Get the infiltration zones over the zone of interest.
Infiltration zone are 1-based indices as it is a WOLF convention.
- Returns:
The infiltration zones over the zone of interest.
We cache the infiltration zones to avoid multiple d/l from the GPU.
- set_infiltration_zones(b: numpy.ndarray | wolfhece.wolf_array.WolfArray)[source]
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.
- get_active_infiltration_quantities()[source]
Get the current infiltration chronology’s row: that is, the currently infiltrated quantities.
- Returns:
The current infitlration chronology’s row. If none is
active (because current time is before the chronology beginning) then None is returned.
- set_active_infiltration_quantities(q) None[source]
Set the current infiltration chronology’s row: that is, set the infiltrated quantities.
- insert_infiltration_quantities(t: float, q: List[float]) None[source]
Insert or replace an infiltration chronology’s row.
- Parameters:
t – Beginning time for the infiltration of the row (seconds).
q – Infiltrated quantities, as many as the number of infiltrated zones.
- _cell_bcs_params_values_indices()[source]
Get the cell parameters values over the whole simulation domain. :return: A numpy array with the cell parameters values.
- _convert_cached_bcs_params_indices()[source]
Get the cached BCs params indices over the whole simulation domain.
- get_BC_value(i: int, j: int, param_type: wolfgpu.glsimulation.BoundaryConditionIndices, zero_based: bool = False) float[source]
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.
- Parameters:
zero_based – If True, then (i,j) are 0-based indices. If False, then (i,j) are 1-based indices.
- Returns:
The cell parameter value at location (i,j).
- get_bridge_roof_parameter(i: int, j: int, zero_based: bool = False) float[source]
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.
- Returns:
The cell parameter value at location (i,j).
- get_bridge_roof_in_active_zone_as_ijval(zero_based: bool = False) Tuple[numpy.ndarray, numpy.ndarray][source]
Get all the bridge roof elevations over the active zone.
- get_bridge_roof_in_active_zone_as_array() numpy.ndarray[source]
Get all the bridge roof elevations over the active zone as a full array.
- _get_BCs_in_active_zone_as_ijval(param_type: wolfgpu.glsimulation.BoundaryConditionIndices, zero_based: bool = False) numpy.ndarray[source]
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.
- Returns:
A numpy array with the cell parameters of type param_type over the active zone.
- 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][source]
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.
- Parameters:
direction – The direction of the boundary condition.
- Returns:
A numpy array with the cell parameters of type param_type
- get_BCs_values_in_active_zone_as_array(param_type: wolfgpu.glsimulation.BoundaryConditionIndices) numpy.ndarray[source]
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.
- Returns:
A numpy array with the cell parameters of type param_type over the active zone.
- set_bridge_roof_parameter(i: int, j: int, value: float, zero_based: bool = False) None[source]
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.
- set_bridge_roof_parameter_from_array(values: numpy.ndarray | wolfhece.wolf_array.WolfArray) None[source]
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.
- _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[source]
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.
- Parameters:
value – The value to set.
zero_based – If True, then (i,j) are 0-based indices. If False, then (i,j) are 1-based indices.
- set_BC_value(i: int, j: int, param_type: wolfgpu.glsimulation.BoundaryConditionsTypes, direction: wolfgpu.glsimulation.Direction, value: float, zero_based: bool = False) None[source]
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.
- Parameters:
value – The value to set.
zero_based – If True, then (i,j) are 0-based indices. If False, then (i,j) are 1-based indices.
- get_h()[source]
Get the h unknown over the zone of interest. :return: The h values over the zone of interest.
- set_h(h: numpy.ndarray | wolfhece.wolf_array.WolfArray)[source]
Set the h unknown over the zone of interest.
- Parameters:
h – The h values to set. The array size must be equal to the size of the zone of interest.
- get_qx()[source]
Get the Qx unknown over the zone of interest. :return: The Qx values over the zone of interest.
- set_qx(qx: numpy.ndarray | wolfhece.wolf_array.WolfArray)[source]
Set the Qx unknown over the zone of interest.
- Parameters:
qx – The Qx values to set. The array size must be equal to the size of the zone of interest.
- get_qy()[source]
Get the Qy unknown over the zone of interest. :return: The Qy values over the zone of interest.
- set_qy(qy: numpy.ndarray | wolfhece.wolf_array.WolfArray)[source]
Set the Qy unknown over the zone of interest.
- Parameters:
qy – The Qy values to set. The array size must be equal to the size of the zone of interest.
- get_froude()[source]
Get the Froude number over the zone of interest. :return: The Froude number values over the zone of interest.
- get_head()[source]
Get the water head over the zone of interest. :return: The water head values over the zone of interest.
- 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[source]
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.
- set_wolfarray(which_quantity: Literal['bathy', 'h', 'qx', 'qy', 'infiltration', 'manning'], wa: wolfhece.wolf_array.WolfArray) None[source]
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.
- class wolfgpu.injector.SimulationInjector[source]
Bases:
abc.ABC
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).
- classmethod compatibility()[source]
- 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.
- Return type:
This method returns a dictionary with two entries “python” and “wolfgpu”. For example: ``` return {
”python”: “>=3.11”, “wolfgpu”: “>=1.4”
- abstractmethod inject(sim_proxy: SimulationProxy) None[source]
This method will starting from the time_to_first_injection or after the time it itself returned.
- Returns:
Return the time the simulator must wait before calling this method again. Return None if you don’t want to be called anymore.
- Return type:
- abstractmethod do_report(proxy: SimulationProxy, rs: wolfgpu.results_store.ResultsStore, record_path: pathlib.Path) None[source]
This method will propose to write some reporting data.
- Returns:
Nothing.
- Return type:
None
- classmethod make_from_dict(json_dict: dict) SimulationInjector[source]
Given a dictionary, create a brand new injector. This method will be called by the simulator to build the injector.
- Parameters:
json_dict – A dict that is JSON-serializable.
- Return type:
- get_params() dict[source]
Create a dictionary from an existing injector. This method will be called by the simulator to save the injector.
- Return type:
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.
- wolfgpu.injector.default_dict_active_zone(which_type: Literal['header_wolf', 'bounds'] = 'header_wolf') dict[source]
Get a default active zone dictionary that can be used to create a header_wolf.
- Parameters:
which_type – The type of data to save: ‘header_wolf’ or ‘bounds’.
- Returns:
A dictionary that can be used to create a header_wolf.
- wolfgpu.injector.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[source]
Get a default injector dictionary that can be used to create a TimeBasedInjector or StepBasedInjector.
- Parameters:
type_duration – The type of duration: ‘time’ or ‘step’.
duration – The duration value.
- Returns:
A dictionary that can be used to create an injector.