From e6c6b807ee96e1e035a450cbca1effe3d65875d9 Mon Sep 17 00:00:00 2001 From: loferga Date: Fri, 26 Sep 2025 13:59:55 +0200 Subject: [PATCH] Adds proper doc to each undocumented class --- .../boundary/BoundaryCondition.py | 1 + .../dassflow2d_py/boundary/Discharge1.py | 5 +- .../dassflow2d_py/input/DassflowMeshReader.py | 3 +- .../dassflow2d_py/input/InitialStateReader.py | 10 ++++ .../dassflow2d_py/input/MeshReader.py | 10 ++++ .../dassflow2d_py/output/ResultWriter.py | 52 ++++++++++++++++++- .../dassflow2d_py/resolution/EulerHLLC.py | 3 ++ .../resolution/ResolutionMethod.py | 12 +++++ 8 files changed, 91 insertions(+), 5 deletions(-) diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/boundary/BoundaryCondition.py b/src/main/py/fr/dasshydro/dassflow2d_py/boundary/BoundaryCondition.py index cff300a..8f60e90 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/boundary/BoundaryCondition.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/boundary/BoundaryCondition.py @@ -35,6 +35,7 @@ def update(self, bathymetry: dict[Cell, float], current_state: TimeStepState, cu from fr.dasshydro.dassflow2d_py.boundary.RatingCurve import RatingCurve from fr.dasshydro.dassflow2d_py.boundary.Wall import Wall +# default association between namespaces and BoundaryCondition implementation default_boundary_condition_class: dict[str, Type[BoundaryCondition]] = { "discharg1": Discharge1, "ratcurve": RatingCurve, diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/boundary/Discharge1.py b/src/main/py/fr/dasshydro/dassflow2d_py/boundary/Discharge1.py index 8c60b02..e2ba0c9 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/boundary/Discharge1.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/boundary/Discharge1.py @@ -13,6 +13,9 @@ def getBoundaryType(self) -> BoundaryType: return BoundaryType.INFLOW def update(self, bathymetry, current_state: TimeStepState, current_simulation_time: float): + """ + Distribute the interpolated q_in value to each boundaries in the list + """ q_in = self.interpolate_dynamic_value(current_simulation_time) @@ -25,14 +28,12 @@ def update(self, bathymetry, current_state: TimeStepState, current_simulation_ti h = max(0.0001, h) # Avoid zero or very small values sum_pow_h += (h ** (5/3)) * edge.getLength() - inflows = {} for boundary in self.boundaries: edge = boundary.getEdge() cell = edge.getCells()[0] h = current_state.getNode(cell).h h = max(0.0001, h) # Avoid zero or very small values inflow = -q_in * (h ** (2/3)) / sum_pow_h - inflows[boundary] = inflow # Update the ghost cell's u (discharge) value ghost_cell = edge.getGhostCell() ghost_cell_node = current_state.getNode(ghost_cell) diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/input/DassflowMeshReader.py b/src/main/py/fr/dasshydro/dassflow2d_py/input/DassflowMeshReader.py index f411783..695d34a 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/input/DassflowMeshReader.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/input/DassflowMeshReader.py @@ -4,7 +4,8 @@ class DassflowMeshReader(MeshReader): - """This class implements the reading of a mesh, on a dassflow mesh type + """ + This class implements the reading of a mesh, on a dassflow mesh type """ def __init__(self): diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/input/InitialStateReader.py b/src/main/py/fr/dasshydro/dassflow2d_py/input/InitialStateReader.py index 3818873..b51a8ef 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/input/InitialStateReader.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/input/InitialStateReader.py @@ -7,6 +7,16 @@ def __init__(self): pass def read(self, file_path: str, number_of_cells: int) -> list[Node]: + """ + Reads an init file with all h, u, and v values for every node at the start of the simulation + + Args: + file_path (str): string path to the init file + number_of_cells (int): number of cells in the mesh + + Returns: + list[Node]: every node read, the nodes are in order such as it maps to a cell list sorted by id + """ node_list = [] with open(file_path, 'r') as file: for _ in range(number_of_cells): diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/input/MeshReader.py b/src/main/py/fr/dasshydro/dassflow2d_py/input/MeshReader.py index f0dd0c3..26942d5 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/input/MeshReader.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/input/MeshReader.py @@ -14,4 +14,14 @@ def read(self, file_path: str) -> tuple[ dict[int, float], dict[int, float] ]: + """ + Read all information contained in a dassflow mesh. + + Args: + file_path (str): string path to the mesh file + + Returns: + tuple[ list[RawVertex], list[RawCell], list[RawInlet], list[RawOutlet], dict[int, float], dict[int, float] ]: + all information in a tuple + """ pass diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/output/ResultWriter.py b/src/main/py/fr/dasshydro/dassflow2d_py/output/ResultWriter.py index 6a46724..e981086 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/output/ResultWriter.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/output/ResultWriter.py @@ -36,6 +36,15 @@ def __init__(self, mesh: Mesh, result_file_path: str, delta_to_write: float): self.last_quotient = 0 def isTimeToWrite(self, current_simulation_time: float) -> bool: + """ + Tells if the result writer is ready to write considering the time of the request + + Args: + current_simulation_time (float): simulation time at request moment + + Returns: + bool: wether or not a save call can be done + """ quotient = current_simulation_time // self.dtw if quotient > self.last_quotient: # it's time to write! @@ -76,6 +85,16 @@ def _read_raw_file(self, raw_filepath: str): return ids, hs, us, vs def _write_vtk(self, ids, hs, us, vs, filename: str): + """ + Write a file in .vtk format for gnuplot + + Args: + ids (_type_): list of all ids in a result file + hs (_type_): list of all h value in a result file + us (_type_): list of all u value in a result file + vs (_type_): list of all v value in a result file + filename (str): result vtk file + """ points = vtk.vtkPoints() cells = vtk.vtkCellArray() h_data = vtk.vtkDoubleArray() @@ -116,6 +135,16 @@ def _write_vtk(self, ids, hs, us, vs, filename: str): writer.Write() def _write_tecplot(self, ids, hs, us, vs, simulation_time: float, filename: str): + """ + Write a file in .plt format for tecplot + + Args: + ids (_type_): list of all ids in a result file + hs (_type_): list of all h value in a result file + us (_type_): list of all u value in a result file + vs (_type_): list of all v value in a result file + filename (str): result plt file + """ with open(filename, "w") as file: file.write('TITLE = "DassFlow Result File in Time"\n') file.write('VARIABLES = "x","y","bathy","h","zs","Manning","u","v"\n') @@ -145,6 +174,16 @@ def _write_tecplot(self, ids, hs, us, vs, simulation_time: float, filename: str) file.write(f"{vertex1_id} {vertex2_id} {vertex3_id} {vertex4_id}\n") def _write_gnuplot(self, ids, hs, us, vs, filename: str): + """ + Write a file in .dat format for gnuplot + + Args: + ids (_type_): list of all ids in a result file + hs (_type_): list of all h value in a result file + us (_type_): list of all u value in a result file + vs (_type_): list of all v value in a result file + filename (str): result dat file + """ with open(filename, "w") as file: file.write(" # Gnuplot DataFile Version\n") file.write(" # i x y bathy h zs Manning u v\n") @@ -154,10 +193,13 @@ def _write_gnuplot(self, ids, hs, us, vs, filename: str): y = cell.getGravityCenter()[1] file.write(f" {id} {x} {y} 0.0 {hs[i]} {hs[i]} 0.0 {us[i]} {vs[i]}\n") - def _write_hdf5(self, all_data, filename: str): + def _write_hdf5(self, all_data: dict[float, tuple[int, float, float, float]], filename: str): """ Write all raw results into a single HDF5 file. - all_data: dict{simulation_time: (ids, hs, us, vs)} + + Args: + all_data (dict[float, tuple[int, float, float, float]]): all node values linked to their corresponding time + filename (str): result hdf5 file """ with h5py.File(filename, "w") as hdf: for time, (ids, hs, us, vs) in all_data.items(): @@ -169,6 +211,12 @@ def _write_hdf5(self, all_data, filename: str): group.create_dataset("v", data=vs) def writeAll(self, output_mode: OutputMode): + """ + Write all saved results to the corresponding final format specified + + Args: + output_mode (OutputMode): specified output mode format + """ raw_files = [f for f in os.listdir(self.result_folder) if f.endswith(".raw")] all_data = {} # Dictionary to store all raw data: {simulation_time: (ids, hs, us, vs)} diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/resolution/EulerHLLC.py b/src/main/py/fr/dasshydro/dassflow2d_py/resolution/EulerHLLC.py index 9db512b..d44feff 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/resolution/EulerHLLC.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/resolution/EulerHLLC.py @@ -7,4 +7,7 @@ def __init__(self, configuration: Configuration): pass def resolve(self, previous_time_step, delta, mesh, bathymetry): + """ + Implements a resolution method using euler time scheme and the hllc solver + """ return previous_time_step \ No newline at end of file diff --git a/src/main/py/fr/dasshydro/dassflow2d_py/resolution/ResolutionMethod.py b/src/main/py/fr/dasshydro/dassflow2d_py/resolution/ResolutionMethod.py index 1980f79..910f111 100644 --- a/src/main/py/fr/dasshydro/dassflow2d_py/resolution/ResolutionMethod.py +++ b/src/main/py/fr/dasshydro/dassflow2d_py/resolution/ResolutionMethod.py @@ -17,4 +17,16 @@ class SpatialScheme(Enum): class ResolutionMethod(ABC): @abstractmethod def resolve(self, previous_time_step: TimeStepState, delta: float, mesh: Mesh, bathymetry: dict[Cell, float]) -> TimeStepState: + """ + Resolution call that should return a new (or modified) TimeStepState with corrected value + + Args: + previous_time_step (TimeStepState): state at the time of call + delta (float): time to skip to + mesh (Mesh): geometry of the problem + bathymetry (dict[Cell, float]): bathymetry of each cell (including ghost cells) + + Returns: + TimeStepState: state after delta + """ pass