wolfgpu.glsimulation
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.glsimulation.TileOptimisation[source]
Bases:
enum.Enum
Generic enumeration.
Derive from this class to define new enumerations.
- wolfgpu.glsimulation.shrink_array_by_two(a)[source]
Cut array in 2. A 5x5 array will be cut to a 3x3 (notiece the rounding)
- wolfgpu.glsimulation.find_stripes(a, rw, rh, tile_w, tile_h, with_dilatation=True)[source]
Find stripes on a. Elements of a different than zero are the ones taken into account.
There’s one stripe per line of the array !
Please note that the stripes coordinates will be in NDC (normalized device coordinate, see OpenGL) over the array (that is, they’re in [-1,+1] regardless of the size of the array)
- wolfgpu.glsimulation.find_non_empty_tiles_on_nap(nap: wolfgpu.gl_utils.np.ndarray, n: int)[source]
Tiles on NAP are used to guide the first level of computation, that is at the maximum detail level. After that level, one uses stripes which will be dynamically adjusted to water coverage. Tiles on NAP are not meant to change over the course of the simulation.
- class wolfgpu.glsimulation.GLSimulationGlobalState(simulation_time, previous_step_simulation_time, time_step, active_infiltration_line, nb_dryup_iterations, nb_active_tiles, status_code, total_active_tiles, infiltration_zones, simulation_step, step_times)[source]
- class wolfgpu.glsimulation.GLSimulation(width, height, ponderation_runge_kutta: float = 0.3, dx: float = 1.0, dy: float = 1.0, courant: float = 0.1, froude_max: float = 10.0, time_step_strategy=TimeStepStrategy.OPTIMIZED_TIME_STEP, time_step: float = 1.0, max_steps=SimulationDuration.from_seconds(10), report_frequency=SimulationDuration.from_steps(10), basefilename: str = 'simul', tile_size=DEFAULT_TILE_SIZE, shader_log_path: wolfgpu.gl_utils.Path = None, tile_packing_mode: wolfgpu.tile_packer.TilePackingMode = TilePackingMode.REGULAR, optimized_indirection: bool = False)[source]
OpenGL simulation.
Can be initialized from scractch, with SimpleSimulation or PrevWOLF2D CPU model.
This class can be used in a runner, which will call the simulation step method at each frame. The simulation step method will update the simulation state and draw the simulation on the screen.
- property infiltration_interpolation: wolfgpu.simple_simulation.InfiltrationInterpolation[source]
Get the infiltration interpolation mode.
- property nbx[source]
Get the width of the simulation domain.
Useful for interoperability with wolfhece package.
- property nby[source]
Get the height of the simulation domain.
Useful for interoperability with wolfhece package.
- set_params(width, height, ponderation_runge_kutta: float = 0.3, dx: float = 1.0, dy: float = 1.0, courant: float = 0.1, froude_max: float = 10.0, time_step_strategy=TimeStepStrategy.OPTIMIZED_TIME_STEP, time_step: float = None, simulation_duration=SimulationDuration.from_seconds(10), report_frequency=SimulationDuration.from_steps(10), basefilename: str = 'simul', tile_size=DEFAULT_TILE_SIZE, infiltration_interpolation: wolfgpu.simple_simulation.InfiltrationInterpolation = InfiltrationInterpolation.NONE, tile_packing_mode: wolfgpu.tile_packer.TilePackingMode = TilePackingMode.REGULAR, optimized_indirection=False, track_flows_at_borders=False)[source]
- set_track_flows_at_borders(v: bool)[source]
Track fluxes at borders.
This can be used to properly compute discharge across sections without recalculation of these fluxes from cell-centered values/unknowns.
- force_max_step_size(s: float)[source]
Prevents the max step size computation.
- Parameters:
s – Maximum step size [s]. Pass None to re-enable the computation.
Used in test/debug.
- set_ensure_positive_height(b: bool)[source]
Enable or disable positive height enforcment.
Used in debugging/testing
- set_froude_limit(l: float)[source]
- Parameters:
l – Froude max [-]. If None, then we turn off froude limitation.
- set_froude_bc_tolerance(l: float = 1.0)[source]
Set the tolerance for the Froude number at the boundaries.
If toleranceis 1.0, then the boundary condition impose the minimum of the water height computed based on the Froude number and the water height inside the computed domain.
If tolerance is greater than 1.0, then the water height inside the domain is multiplied by the tolerance before applying the minimum operator.
It could be useful if the water height inside the domain is too low and the regime is (near) supercritical that is not theoretically correct if we want to impose a BC at this position. In subcritical regime, usually, it is not a problem.
- Parameters:
l – tolerance >= 1.0
- set_report_frequency(d: wolfgpu.simple_simulation.SimulationDuration)[source]
Set the report frequency in seconds or iterations.
- set_simulation_duration(d: wolfgpu.simple_simulation.SimulationDuration)[source]
Set the simulation duration in seconds or iterations.
- set_rk_ponderation(p: float)[source]
Set the predictor’s ponderation of the Runge Kutta 2x scheme.
A RK22 scheme is obtained by setting p=0.5. A RK21 scheme is obtained by setting p=0.3.
For compatibility with previous WOLF2D CPU model, we accept p > 1.0 (like 3.). In this case, the runner will correct the value and will apply the RK21 scheme with a ponderation of 0.3.
- Parameters:
p (float) – ponderation [0,1].
- set_infiltration_interpolation(lerp: wolfgpu.simple_simulation.InfiltrationInterpolation)[source]
Set the infiltration interpolation mode (stepwise or linear interpolation).
- Parameters:
lerp (InfiltrationInterpolation) – interpolation mode.
- set_debug(dbg: bool)[source]
Record more data in results and activate debug textures.
- Attention:
Make sure to call this before everything else.
- set_tiles_packing_mode(mode: wolfgpu.tile_packer.TilePackingMode)[source]
Set the tiles packing mode (TRANSPARENT or REGULAR).
Transparent mode will not pack the tiles in a regular grid but will use the tiles as they are. This is useful for debugging purposes or small models.
- Attention:
This mode has no impact on the simulation results. Some unit tests
are performed o ensure that the simulation results are the same in both modes.
- Parameters:
mode (TilePackingMode) – packing mode.
- set_tile_size(tile_size: int)[source]
Set the tile size.
- Parameters:
tile_size (int) – tile size in number of cells (must be a power of 2).
- set_total_number_of_dry_up_outer_loops(n)[source]
Configure the number of desired iterations to solve all or some of the dry ups.
- Parameters:
n (None or int.) – Number of iterations: * n == 0 means no dry up (only Euler/RK) * n > 0 means a fixed number of dry up iterations * None means as many dry up iterations as needed to solve all dry ups
- tile_packer() wolfgpu.tile_packer.TilePacker[source]
- compute_time_step_for_tiles_phase1(current_quantity)[source]
Phase 1 of computing the minimum time step for the simulation. It consists of computing one minimum for each tile (the second phase will compute the minium across tiles).
- Parameters:
current_quantity (int) – The quantity index for which we compute the time step.
The current_quantity can be 0 or 1. It’s the index of the quantity in the quantity textures.
The minimum time step is computed for each tile and will be stored in the tiles_mins texture.
- compute_time_step_for_tiles_phase2()[source]
Phase 2: reduce the matrix of minimums.
No need to pass argument while the Phase 1 has already set the minimums in the tiles_mins texture.
- reset_size(width: int, height: int)[source]
Reset the size of the simulation.
- Attention:
Used in tests
- complete_textures()[source]
After having set several data textures, call this to upload blank texture replacement for those you didn’t set. and to recompute the framebuffers and create additional textures necessary to the computation.
- We are using some routines from gl_utils.py like:
upload_blank_texture_to_gpu
upload_np_array_to_gpu
create_frame_buffer_for_computation
- _create_debugging_textures()[source]
Create textures for debugging purposes.
Even if we used Framebuffers for debugging, we now use textures because it is more easy to download them to the CPU.
- set_buffers(max_step_size=None, strong_bc_array=None, strong_bc_values_array=None, quantity_arrays=None, bathymetry_array=None, manning_array=None, active_meshes_array=None, weak_bc_array=None, bc_cells_array=None, infiltration_zones_array=None, infiltration_timings=None)[source]
- reset_globals(sim_time, time_step, step_num, h, qx, qy)[source]
- Parameters:
time_step – the duration of the time step (in case you have a fixed time step)
step_num – The step number of the next computed simulation step.
- compute_derivative_with_dry_up_and_euler(current_quantity_tex_ndx: int, euler_base_quantity_tex_ndx: int, quantity_out_tex_ndx: int, current_alpha_tex_ndx=0, ignore_alpha=False)[source]
- compute_derivative_with_dry_up_and_rk(current_quantity_tex_ndx: int, predictor_quantity_tex_ndx: int, quantity_out_tex_ndx: int, current_alpha_tex_ndx=0, ignore_alpha=False)[source]
- detect_wet_tiles2(current_quantity: int)[source]
Detect wet tiles
FIXME we also call them active but that a misnomer because active also means NAP-active…
- simulation_step(source_quantity: int)[source]
Perform a full simulation step (with all substeps: euler, RK,…)
- Parameters:
source_quantity (int) – is 0 or 1 and tells in which of the ping/pong textures we’ll read information. Consequently, we’ll write into 1 - source_quantity.
- filter_low_water(current_quantity_tex_ndx: int, euler_base_quantity_tex_ndx: int, quantity_out_tex_ndx: int, current_alpha_tex_ndx=0, ignore_alpha=False)[source]
- _draw_active_tiles(program, uniforms: dict, textures: dict, viewport=None)[source]
Draw the active tiles
- plot_progress(current_quantity, zoom=1.0, mean=0.5, flip=True, gl_window_viewport=(0, 0, 100, 100))[source]
- active_infiltration_line(t: float) int[source]
Compute the active infiltration event number (or line in the array) at time t. The event number is one based. Returns 0 if none is active.
- _infiltrations_timings_as_gpu_array(nb_cells_per_zone, infiltrations_chronology: wolfgpu.simple_simulation.InfiltrationChronology)[source]
- read_flows_on_borders(which: int)[source]
Read flows on borders. Each cell of the returned arrays contains: (q_left, q_right, q_top, q_bottom).
Used only while debugging
- param which:
0 for Euler, 1 for Runge Kutta.
- read_rhs()[source]
Read RHS at Euler step or RK step (make sure you know which one is valid when). Each cell of the returned arrays contains: (q_left, q_right, q_top, q_bottom).
Used only while debugging
- read_quantity_result(current_quantity) wolfgpu.gl_utils.np.array[source]
Returns the matrix of quantities (h,qx,qy), unpacked. Used for debugging. Prefer the ResultStore.
- Parameters:
current_quantity – is 0,1 for the flip flop textures and 2
for the intermediate euler resul (if one uses Runge-Kutta).
- _read_full_quantity_result(current_quantity) wolfgpu.gl_utils.np.array[source]
Returns the matrix of quantities (h,qx,qy, UNSPECIFIED), unpacked.
- Parameters:
current_quantity – is 0,1 for the flip flop textures and 2
for the intermediate euler resul (if one uses Runge-Kutta).
- read_tile_packed_quantity_result(current_quantity)[source]
Returns the matrix of quantities (h,qx,qy), “tile-packed”.
- read_alpha(current_quantity)[source]
Returns the matrix of alpha-correction (dry ups), “tile-_un_packed”.
- read_tile_packed_alpha(current_quantity)[source]
Returns the matrix of alpha-correction (dry ups), “tile-packed”.
- read_active_cells_map()[source]
Read active cells map.
NOTE ! Be ware that this map is “packed” (as in tile packing)
- read_tile_min_step_size()[source]
The last computed minimum step size. This is only valid after the first phase of the computation of the time steps (the second phase reuse the texture for a reduction).
- read_bcs_descriptions() wolfgpu.gl_utils.np.ndarray[source]
Read the boundary conditions descriptions from the texture boundary_cond_cells_tex.
- read_global_state() GLSimulationGlobalState[source]
Read the global state variables of the simulation, as reported by the shaders in the GPU.
Be aware that this implies reading information from the GPU which usually leads to a huge drop in performance (up to 50% !!!).
- Returns:
simulation_time, time_step, active_infiltration_line, nb_dryup_iterations, nb_active_tiles, status_code
- plot_progress(current_quantity, zoom=1.0, mean=0.5, flip=True, gl_window_viewport=(0, 0, 100, 100))[source]
- _infiltrations_timings_as_gpu_array(nb_cells_per_zone, infiltrations_chronology: wolfgpu.simple_simulation.InfiltrationChronology)[source]
- wolfgpu.glsimulation.convert_wolf_rk_ponderation(wolf2d: wolfhece.mesh2d.wolf2dprev.prev_sim2D)[source]
Convert the ponderation value from prev_sim2D to the one used in the GLSimulation.
- wolfgpu.glsimulation.get_epsilon(wolf2d: wolfhece.mesh2d.wolf2dprev.prev_sim2D)[source]
Get the epsilon value used in the GLSimulation.
Based on the spatial resolution of the simulation, we take the minimum of dx and dy to the power of 4. The result is then compared to 0.000_001 and the minimum of the two values is returned.
- wolfgpu.glsimulation.get_report_frequency(m: wolfhece.mesh2d.wolf2dprev.prev_sim2D) wolfgpu.simple_simulation.SimulationDuration[source]
- wolfgpu.glsimulation.plot_evolution_of_simulation_base(sim: wolfgpu.simple_simulation.SimpleSimulation, rs: wolfgpu.results_store.ResultsStore)[source]