diff --git a/examples/post_processing/report/automotive_report.py b/examples/post_processing/report/automotive_report.py
new file mode 100644
index 000000000..f95b66149
--- /dev/null
+++ b/examples/post_processing/report/automotive_report.py
@@ -0,0 +1,424 @@
+import flow360 as fl
+from flow360 import u
+from flow360.examples import DrivAer
+from flow360.log import log
+from flow360.plugins.report.report import ReportTemplate
+from flow360.plugins.report.report_items import (
+ BottomCamera,
+ Chart2D,
+ Chart3D,
+ FrontCamera,
+ FrontLeftBottomCamera,
+ FrontLeftTopCamera,
+ Inputs,
+ LeftCamera,
+ RearCamera,
+ RearLeftTopCamera,
+ RearRightBottomCamera,
+ Settings,
+ Summary,
+ Table,
+ TopCamera,
+)
+from flow360.plugins.report.utils import Average, DataItem, Delta, Expression, Variable
+
+DrivAer.get_files()
+
+project = fl.Project.from_volume_mesh(
+ DrivAer.mesh_filename,
+ name="Automotive DrivAer",
+)
+
+vm = project.volume_mesh
+
+log.info("Volume mesh contains the following boundaries:")
+for boundary in vm.boundary_names:
+ log.info("Boundary: " + boundary)
+
+freestream_surfaces = ["blk-1/WT_side1", "blk-1/WT_side2", "blk-1/WT_inlet", "blk-1/WT_outlet"]
+slip_wall_surfaces = ["blk-1/WT_ceiling", "blk-1/WT_ground_front", "blk-1/WT_ground"]
+wall_surfaces = list(set(vm.boundary_names) - set(freestream_surfaces) - set(slip_wall_surfaces))
+
+cases = []
+
+for beta in [0, 5, 10]:
+ with fl.SI_unit_system:
+ params = fl.SimulationParams(
+ meshing=None,
+ reference_geometry=fl.ReferenceGeometry(area=2.17, moment_length=2.7862),
+ operating_condition=fl.AerospaceCondition(velocity_magnitude=40, beta=beta * u.deg),
+ models=[
+ fl.Wall(surfaces=[vm[i] for i in wall_surfaces], use_wall_function=True),
+ fl.Freestream(
+ surfaces=[vm[i] for i in freestream_surfaces],
+ ),
+ fl.SlipWall(
+ surfaces=[vm[i] for i in slip_wall_surfaces],
+ ),
+ ],
+ user_defined_fields=[
+ fl.UserDefinedField(
+ name="Cpx",
+ expression="double prel = primitiveVars[4] - pressureFreestream;"
+ + "double PressureForce_X = prel * nodeNormals[0]; "
+ + "Cpx = PressureForce_X / (0.5 * MachRef * MachRef) / magnitude(nodeNormals);",
+ ),
+ ],
+ outputs=[
+ fl.SurfaceOutput(
+ surfaces=vm["*"],
+ output_fields=[
+ "Cp",
+ "Cf",
+ "yPlus",
+ "CfVec",
+ "primitiveVars",
+ "wall_shear_stress_magnitude",
+ "Cpx",
+ ],
+ ),
+ fl.SliceOutput(
+ entities=[
+ *[
+ fl.Slice(
+ name=f"slice_y_{name}",
+ normal=(0, 1, 0),
+ origin=(0, y, 0),
+ )
+ for name, y in zip(
+ ["0", "0_2", "0_4", "0_6", "0_8"], [0, 0.2, 0.4, 0.6, 0.8]
+ )
+ ],
+ *[
+ fl.Slice(
+ name=f"slice_z_{name}",
+ normal=(0, 0, 1),
+ origin=(0, 0, z),
+ )
+ for name, z in zip(
+ ["neg0_2", "0", "0_2", "0_4", "0_6", "0_8"],
+ [-0.2, 0, 0.2, 0.4, 0.6, 0.8],
+ )
+ ],
+ ],
+ output_fields=["velocity", "velocity_x", "velocity_y", "velocity_z"],
+ ),
+ fl.IsosurfaceOutput(
+ output_fields=["Cp", "Mach"],
+ isosurfaces=[
+ fl.Isosurface(
+ name="isosurface-cpt",
+ iso_value=-1,
+ field="Cpt",
+ ),
+ ],
+ ),
+ fl.ProbeOutput(
+ entities=[fl.Point(name="point1", location=(10, 0, 1))],
+ output_fields=["velocity"],
+ ),
+ ],
+ )
+
+ case_new = project.run_case(params=params, name=f"DrivAer 5.7M - beta={beta}")
+
+ cases.append(case_new)
+
+# wait until all cases finish running
+for case in cases:
+ case.wait()
+
+exclude = ["blk-1/WT_ground_close", "blk-1/WT_ground_patch"]
+size = "5.7M"
+
+exclude += freestream_surfaces + slip_wall_surfaces
+
+top_camera = TopCamera(pan_target=(1.5, 0, 0), dimension=5, dimension_dir="width")
+top_camera_slice = TopCamera(pan_target=(2.5, 0, 0), dimension=8, dimension_dir="width")
+side_camera = LeftCamera(pan_target=(1.5, 0, 0), dimension=5, dimension_dir="width")
+side_camera_slice = LeftCamera(pan_target=(2.5, 0, 1.5), dimension=8, dimension_dir="width")
+rear_camera = RearCamera(dimension=2.5, dimension_dir="width")
+front_camera = FrontCamera(dimension=2.5, dimension_dir="width")
+bottom_camera = BottomCamera(pan_target=(1.5, 0, 0), dimension=5, dimension_dir="width")
+front_left_bottom_camera = FrontLeftBottomCamera(
+ pan_target=(1.5, 0, 0), dimension=5, dimension_dir="width"
+)
+rear_right_bottom_camera = RearRightBottomCamera(
+ pan_target=(1.5, 0, 0), dimension=6, dimension_dir="width"
+)
+front_left_top_camera = FrontLeftTopCamera(
+ pan_target=(1.5, 0, 0), dimension=6, dimension_dir="width"
+)
+rear_left_top_camera = RearLeftTopCamera(pan_target=(1.5, 0, 0), dimension=6, dimension_dir="width")
+
+cameras_geo = [
+ top_camera,
+ side_camera,
+ rear_camera,
+ bottom_camera,
+ front_left_bottom_camera,
+ rear_right_bottom_camera,
+]
+
+limits_cp = [(-1, 1), (-1, 1), (-1, 1), (-0.3, 0), (-0.3, 0), (-1, 1), (-1, 1), (-1, 1)]
+cameras_cp = [
+ front_camera,
+ front_left_top_camera,
+ side_camera,
+ rear_left_top_camera,
+ rear_camera,
+ bottom_camera,
+ front_left_bottom_camera,
+ rear_right_bottom_camera,
+]
+
+avg = Average(fraction=0.1)
+CD = DataItem(data="surface_forces/totalCD", exclude=exclude, title="CD", operations=avg)
+
+CL = DataItem(data="surface_forces/totalCL", exclude=exclude, title="CL", operations=avg)
+
+CDA = DataItem(
+ data="surface_forces",
+ exclude=exclude,
+ title="CD*area",
+ variables=[Variable(name="area", data="params.reference_geometry.area")],
+ operations=[Expression(expr="totalCD * area"), avg],
+)
+
+CLf = DataItem(
+ data="surface_forces",
+ exclude=exclude,
+ title="CLf",
+ operations=[Expression(expr="1/2*totalCL + totalCMy"), avg],
+)
+
+CLr = DataItem(
+ data="surface_forces",
+ exclude=exclude,
+ title="CLr",
+ operations=[Expression(expr="1/2*totalCL - totalCMy"), avg],
+)
+
+CFy = DataItem(data="surface_forces/totalCFy", exclude=exclude, title="CS", operations=avg)
+
+statistical_data = [
+ "params/reference_geometry/area",
+ CD,
+ CDA,
+ Delta(data=CD),
+ CL,
+ CLf,
+ CLr,
+ CFy,
+ "volume_mesh/stats/n_nodes",
+ "params/time_stepping/max_steps",
+]
+statistical_table = Table(
+ data=statistical_data,
+ section_title="Statistical data",
+ formatter=[
+ (
+ None
+ if d
+ in [
+ "params/reference_geometry/area",
+ "volume_mesh/stats/n_nodes",
+ "params/time_stepping/max_steps",
+ ]
+ else ".4f"
+ )
+ for d in statistical_data
+ ],
+)
+
+geometry_screenshots = [
+ Chart3D(
+ section_title="Geometry",
+ items_in_row=2,
+ force_new_page=True,
+ show="boundaries",
+ camera=camera,
+ exclude=exclude,
+ fig_name=f"geo_{i}",
+ )
+ for i, camera in enumerate(cameras_geo)
+]
+cpt_screenshots = [
+ Chart3D(
+ section_title="Isosurface, Cpt=-1",
+ items_in_row=2,
+ force_new_page=True,
+ show="isosurface",
+ iso_field="Cpt",
+ exclude=exclude,
+ camera=camera,
+ )
+ for camera in cameras_cp
+]
+cfvec_screenshots = [
+ Chart3D(
+ section_title="CfVec",
+ items_in_row=2,
+ force_new_page=True,
+ show="boundaries",
+ field="CfVec",
+ mode="lic",
+ limits=(1e-4, 10),
+ is_log_scale=True,
+ exclude=exclude,
+ camera=camera,
+ )
+ for camera in cameras_cp
+]
+y_slices_lic_screenshots = [
+ Chart3D(
+ section_title=f"Slice velocity LIC y={y}",
+ items_in_row=2,
+ force_new_page=True,
+ show="slices",
+ include=[f"slice_y_{name}"],
+ field="velocityVec",
+ mode="lic",
+ limits=(0 * u.m / u.s, 50 * u.m / u.s),
+ camera=side_camera_slice,
+ fig_name=f"slice_y_vec_{name}",
+ )
+ for name, y in zip(["0", "0_2", "0_4", "0_6", "0_8"], [0, 0.2, 0.4, 0.6, 0.8])
+]
+y_slices_screenshots = [
+ Chart3D(
+ section_title=f"Slice velocity y={y}",
+ items_in_row=2,
+ force_new_page=True,
+ show="slices",
+ include=[f"slice_y_{name}"],
+ field="velocity",
+ limits=(0 * u.m / u.s, 50 * u.m / u.s),
+ camera=side_camera_slice,
+ fig_name=f"slice_y_{name}",
+ )
+ for name, y in zip(["0", "0_2", "0_4", "0_6", "0_8"], [0, 0.2, 0.4, 0.6, 0.8])
+]
+y_slices_lic_screenshots = [
+ Chart3D(
+ section_title=f"Slice velocity LIC y={y}",
+ items_in_row=2,
+ force_new_page=True,
+ show="slices",
+ include=[f"slice_y_{name}"],
+ field="velocityVec",
+ mode="lic",
+ limits=(0 * u.m / u.s, 50 * u.m / u.s),
+ camera=side_camera_slice,
+ fig_name=f"slice_y_vec_{name}",
+ )
+ for name, y in zip(["0", "0_2", "0_4", "0_6", "0_8"], [0, 0.2, 0.4, 0.6, 0.8])
+]
+z_slices_screenshots = [
+ Chart3D(
+ section_title=f"Slice velocity z={z}",
+ items_in_row=2,
+ force_new_page=True,
+ show="slices",
+ include=[f"slice_z_{name}"],
+ field="velocity",
+ limits=(0 * u.m / u.s, 50 * u.m / u.s),
+ camera=top_camera_slice,
+ fig_name=f"slice_z_{name}",
+ )
+ for name, z in zip(["neg0_2", "0", "0_2", "0_4", "0_6", "0_8"], [-0.2, 0, 0.2, 0.4, 0.6, 0.8])
+]
+y_plus_screenshots = [
+ Chart3D(
+ section_title="y+",
+ items_in_row=2,
+ show="boundaries",
+ field="yPlus",
+ exclude=exclude,
+ limits=(0, 5),
+ camera=camera,
+ fig_name=f"yplus_{i}",
+ )
+ for i, camera in enumerate([top_camera, bottom_camera])
+]
+cp_screenshots = [
+ Chart3D(
+ section_title="Cp",
+ items_in_row=2,
+ show="boundaries",
+ field="Cp",
+ exclude=exclude,
+ limits=limits,
+ camera=camera,
+ fig_name=f"cp_{i}",
+ )
+ for i, (limits, camera) in enumerate(zip(limits_cp, cameras_cp))
+]
+cpx_screenshots = [
+ Chart3D(
+ section_title="Cpx",
+ items_in_row=2,
+ show="boundaries",
+ field="Cpx",
+ exclude=exclude,
+ limits=(-0.3, 0.3),
+ camera=camera,
+ fig_name=f"cpx_{i}",
+ )
+ for i, camera in enumerate(cameras_cp)
+]
+wall_shear_screenshots = [
+ Chart3D(
+ section_title="Wall shear stress magnitude",
+ items_in_row=2,
+ show="boundaries",
+ field="wallShearMag",
+ exclude=exclude,
+ limits=(0 * u.Pa, 5 * u.Pa),
+ camera=camera,
+ fig_name=f"wallShearMag_{i}",
+ )
+ for i, camera in enumerate(cameras_cp)
+]
+
+report = ReportTemplate(
+ title="Aerodynamic analysis of DrivAer",
+ items=[
+ Summary(),
+ Inputs(),
+ statistical_table,
+ Chart2D(
+ x="x_slicing_force_distribution/X",
+ y="x_slicing_force_distribution/totalCumulative_CD_Curve",
+ fig_name="totalCumulative_CD_Curve",
+ background="geometry",
+ exclude=exclude,
+ ),
+ Chart2D(
+ x="surface_forces/pseudo_step",
+ y="surface_forces/totalCD",
+ section_title="Drag Coefficient",
+ fig_name="cd_fig",
+ exclude=exclude,
+ focus_x=(1 / 3, 1),
+ ),
+ *geometry_screenshots,
+ *cp_screenshots,
+ *cpx_screenshots,
+ *cpt_screenshots,
+ *y_slices_screenshots,
+ *y_slices_lic_screenshots,
+ *z_slices_screenshots,
+ *y_plus_screenshots,
+ *wall_shear_screenshots,
+ ],
+ settings=Settings(dpi=150),
+)
+
+report = report.create_in_cloud(
+ f"{size}-{len(cases)}cases-slices-using-groups-Cpt, Cpx, wallShear, dpi=default",
+ cases,
+)
+
+report.wait()
+report.download("report.pdf")
diff --git a/examples/post_processing/report/geometry_to_report.py b/examples/post_processing/report/geometry_to_report.py
new file mode 100644
index 000000000..8176d1d33
--- /dev/null
+++ b/examples/post_processing/report/geometry_to_report.py
@@ -0,0 +1,194 @@
+import flow360 as fl
+from flow360 import u
+from flow360.examples import Airplane
+from flow360.plugins.report.report import ReportTemplate
+from flow360.plugins.report.report_items import (
+ Camera,
+ Chart2D,
+ Chart3D,
+ Inputs,
+ Settings,
+ Summary,
+ Table,
+)
+from flow360.plugins.report.utils import Average, DataItem, Delta
+
+project_id = None # if running for the first time
+
+# then replace it with your project ID to avoid re-creation of projects. You can find project ID on web GUI:
+# project_id = "prj-...."
+
+if project_id is not None:
+ project = fl.Project.from_cloud(project_id)
+else:
+ project = fl.Project.from_geometry(
+ Airplane.geometry, name="Python Project (Geometry, from file) - for Report"
+ )
+
+geo = project.geometry
+geo.group_faces_by_tag("groupName")
+
+
+def simulation_params(angle_of_attack):
+ with fl.SI_unit_system:
+ far_field_zone = fl.AutomatedFarfield()
+ params = fl.SimulationParams(
+ meshing=fl.MeshingParams(
+ defaults=fl.MeshingDefaults(
+ boundary_layer_first_layer_thickness=0.001,
+ surface_max_edge_length=1,
+ ),
+ volume_zones=[far_field_zone],
+ ),
+ reference_geometry=fl.ReferenceGeometry(area=1, moment_length=1),
+ operating_condition=fl.AerospaceCondition(
+ velocity_magnitude=100,
+ alpha=angle_of_attack * fl.u.deg,
+ ),
+ time_stepping=fl.Steady(max_steps=1000),
+ models=[
+ fl.Wall(
+ surfaces=[geo["*"]],
+ ),
+ fl.Freestream(
+ surfaces=[far_field_zone.farfield],
+ ),
+ ],
+ outputs=[
+ fl.SurfaceOutput(
+ surfaces=geo["*"],
+ output_fields=[
+ "Cp",
+ "Cf",
+ "yPlus",
+ "CfVec",
+ "primitiveVars",
+ ],
+ ),
+ ],
+ )
+ return params
+
+
+cases: list[fl.Case] = []
+for alpha in [0, 2, 4]:
+ case = project.run_case(params=simulation_params(alpha), name=f"Case for report, alpha={alpha}")
+ cases.append(case)
+
+[print(case.short_description()) for case in cases]
+
+# waiting explicitly for all the cases to finish (report pipeline will not wait for cases)
+[case.wait() for case in cases]
+
+
+top_camera = Camera(
+ position=(0, 0, 1),
+ look_at=(0, 0, 0),
+ pan_target=(5, 0, 0),
+ up=(0, 1, 0),
+ dimension=15,
+ dimension_dir="width",
+)
+side_camera = Camera(
+ position=(0, -1, 0),
+ look_at=(0, 0, 0),
+ pan_target=(5, 0, 0),
+ up=(0, 0, 1),
+ dimension=12,
+ dimension_dir="width",
+)
+front_left_bottom_camera = Camera(
+ position=(-1, -1, -1),
+ look_at=(0, 0, 0),
+ pan_target=(4, 0, 0),
+ up=(0, 0, 1),
+ dimension=15,
+ dimension_dir="width",
+)
+rear_right_bottom_camera = Camera(
+ position=(1, 1, -1),
+ look_at=(0, 0, 0),
+ pan_target=(4, 0, 0),
+ up=(0, 0, 1),
+ dimension=15,
+ dimension_dir="width",
+)
+
+cameras_geo = [
+ top_camera,
+ side_camera,
+ front_left_bottom_camera,
+ rear_right_bottom_camera,
+]
+
+avg = Average(fraction=0.1)
+
+CL = DataItem(data="surface_forces/totalCL", title="CL", operations=avg)
+
+CD = DataItem(data="surface_forces/totalCD", title="CD", operations=avg)
+
+statistical_data = [
+ "params/operating_condition/alpha",
+ "params/reference_geometry/area",
+ CL,
+ Delta(data=CL),
+ CD,
+ "volume_mesh/stats/n_nodes",
+ "params/time_stepping/max_steps",
+]
+statistical_table = Table(
+ data=statistical_data,
+ section_title="Statistical data",
+ formatter=[
+ (
+ None
+ if d
+ in [
+ "params/reference_geometry/area",
+ "volume_mesh/stats/n_nodes",
+ "params/time_stepping/max_steps",
+ ]
+ else ".4f"
+ )
+ for d in statistical_data
+ ],
+)
+
+geometry_screenshots = [
+ Chart3D(
+ section_title="Geometry",
+ items_in_row=2,
+ force_new_page=True,
+ show="boundaries",
+ camera=camera,
+ fig_name=f"geo_{i}",
+ )
+ for i, camera in enumerate(cameras_geo)
+]
+
+report = ReportTemplate(
+ title="Geometry to report",
+ items=[
+ Summary(),
+ Inputs(),
+ statistical_table,
+ Chart2D(
+ x="total_forces/pseudo_step",
+ y="total_forces/CL",
+ section_title="Lift Coefficient",
+ fig_name="cl_fig",
+ focus_x=(1 / 3, 1),
+ ),
+ *geometry_screenshots,
+ ],
+ settings=Settings(dpi=150),
+)
+
+
+report = report.create_in_cloud(
+ f"Geometry to report - Report, dpi=150",
+ cases,
+)
+
+report.wait()
+report.download("report.pdf")
diff --git a/examples/post_processing/report/sweep_launch_report.py b/examples/post_processing/report/sweep_launch_report.py
new file mode 100644
index 000000000..cc32a1919
--- /dev/null
+++ b/examples/post_processing/report/sweep_launch_report.py
@@ -0,0 +1,336 @@
+"""This script is used by sweep_launch_template.py to create a report."""
+
+import pandas as pd
+
+import flow360 as fl
+from flow360.plugins.report.report import ReportTemplate
+from flow360.plugins.report.report_items import (
+ BottomCamera,
+ Camera,
+ Chart2D,
+ Chart3D,
+ FrontCamera,
+ FrontLeftTopCamera,
+ Inputs,
+ LeftCamera,
+ NonlinearResiduals,
+ PatternCaption,
+ RearCamera,
+ RearRightBottomCamera,
+ Settings,
+ SubsetLimit,
+ Summary,
+ Table,
+ TopCamera,
+)
+from flow360.plugins.report.utils import Average, DataItem
+
+
+def main():
+
+ csv_path = "PATH/TO/CSV/FILE.csv" # Replace with the actual path to your CSV file generated by sweep_launch_template.py
+
+ generate_report(
+ *csv_reader(csv_path),
+ include_geometry=True,
+ include_general_tables=True,
+ include_residuals=True,
+ include_cfl=True,
+ include_forces_moments_table=True,
+ include_forces_moments_charts=True,
+ include_forces_moments_alpha_charts=True,
+ include_forces_moments_beta_charts=True,
+ include_cf_vec=True,
+ include_cp=True,
+ include_yplus=True,
+ include_qcriterion=True,
+ )
+
+
+def csv_reader(
+ file_path,
+):
+ csv_case_specific = pd.read_csv(file_path, sep=",", skiprows=2)
+
+ case_list = []
+
+ for case_id in csv_case_specific["case_id"]:
+ case = fl.Case(case_id)
+ case_list.append(case)
+
+ params = case_list[0].params
+
+ return case_list, params
+
+
+def generate_report(
+ cases,
+ params,
+ include_geometry: bool = False,
+ include_general_tables: bool = False,
+ include_residuals: bool = False,
+ include_cfl: bool = False,
+ include_forces_moments_table: bool = False,
+ include_forces_moments_charts: bool = False,
+ include_forces_moments_alpha_charts: bool = False,
+ include_forces_moments_beta_charts: bool = False,
+ include_cf_vec: bool = False,
+ include_cp: bool = False,
+ include_yplus: bool = False,
+ include_qcriterion: bool = False,
+):
+ items = []
+
+ freestream_surfaces = ["fluid/farfield"]
+
+ exclude = freestream_surfaces
+
+ top_camera = TopCamera(pan_target=(3.5, 0, -0.5), dimension=15, dimension_dir="height")
+ bottom_camera = BottomCamera(pan_target=(3.5, 0, -0.5), dimension=15, dimension_dir="height")
+ front_camera = FrontCamera(pan_target=(3.5, 0, -0.5), dimension=15, dimension_dir="width")
+ rear_camera = RearCamera(pan_target=(3.5, 0, -0.5), dimension=15, dimension_dir="width")
+ left_camera = LeftCamera(pan_target=(3.5, 0, -0.5), dimension=10, dimension_dir="width")
+ right_camera = Camera(
+ pan_target=(3.5, 0, -0.5),
+ position=(0.0, -1.0, 0.0),
+ look_at=(0.0, 0.0, 0.0),
+ up=(0.0, 0.0, 1.0),
+ dimension=10,
+ dimension_dir="width",
+ )
+ front_left_top_camera = FrontLeftTopCamera(
+ pan_target=(3.5, 0, -0.5), dimension=15, dimension_dir="width"
+ )
+ rear_right_bottom_camera = RearRightBottomCamera(
+ pan_target=(3.5, 0, -0.5), dimension=15, dimension_dir="width"
+ )
+
+ if params.time_stepping.type_name == "Unsteady":
+ step_type = "physical_step"
+ else:
+ step_type = "pseudo_step"
+
+ geo_cameras = [
+ top_camera,
+ bottom_camera,
+ front_camera,
+ rear_camera,
+ left_camera,
+ right_camera,
+ front_left_top_camera,
+ rear_right_bottom_camera,
+ ]
+
+ geo_camera_names = [
+ "top_camera",
+ "bottom_camera",
+ "front_camera",
+ "rear_camera",
+ "left_camera",
+ "right_camera",
+ "front_left_top_camera",
+ "rear_right_bottom_camera",
+ ]
+
+ avg = Average(fraction=0.1)
+
+ force_list = [
+ "CD",
+ "CL",
+ "CFx",
+ "CFy",
+ "CFz",
+ "CMx",
+ "CMy",
+ "CMz",
+ ]
+
+ for model in params.models:
+ if model.type == "Fluid":
+ turbulence_solver = model.turbulence_model_solver.type_name
+
+ CD = DataItem(data="surface_forces/totalCD", exclude=exclude, title="CD", operations=avg)
+ CL = DataItem(data="surface_forces/totalCL", exclude=exclude, title="CL", operations=avg)
+ CFX = DataItem(data="surface_forces/totalCFx", exclude=exclude, title="CFx", operations=avg)
+ CFY = DataItem(data="surface_forces/totalCFy", exclude=exclude, title="CFy", operations=avg)
+ CFZ = DataItem(data="surface_forces/totalCFz", exclude=exclude, title="CFz", operations=avg)
+ CMX = DataItem(data="surface_forces/totalCMx", exclude=exclude, title="CMx", operations=avg)
+ CMY = DataItem(data="surface_forces/totalCMy", exclude=exclude, title="CMy", operations=avg)
+ CMZ = DataItem(data="surface_forces/totalCMz", exclude=exclude, title="CMz", operations=avg)
+
+ table_data = [
+ CD,
+ CL,
+ CFX,
+ CFY,
+ CFZ,
+ CMX,
+ CMY,
+ CMZ,
+ ]
+
+ if include_geometry:
+ geometry_screenshots = [
+ Chart3D(
+ section_title="Geometry",
+ items_in_row=2,
+ force_new_page=True,
+ show="boundaries",
+ camera=front_left_top_camera,
+ exclude=exclude,
+ fig_name="Geometry_view",
+ )
+ ]
+ items.extend(geometry_screenshots)
+
+ if include_general_tables:
+ items.append(Summary())
+ items.append(Inputs())
+
+ if include_forces_moments_table:
+ table = Table(
+ data=table_data,
+ section_title="Quantities of interest",
+ )
+ items.append(table)
+
+ if include_residuals:
+ residual_chart = NonlinearResiduals(
+ force_new_page=True, section_title="Nonlinear residuals", fig_name=f"nonlin-res_fig"
+ )
+ items.append(residual_chart)
+
+ if include_cfl and params.time_stepping.CFL.type == "adaptive":
+ cfl_chart = Chart2D(
+ x=f"cfl/{step_type}",
+ y=["cfl/0_NavierStokes_cfl", f"cfl/1_{turbulence_solver}_cfl"],
+ force_new_page=True,
+ section_title="CFL",
+ fig_name="cfl_fig",
+ y_log=True,
+ )
+ items.append(cfl_chart)
+
+ if include_forces_moments_charts:
+ force_charts = [
+ Chart2D(
+ x=f"surface_forces/{step_type}",
+ y=f"surface_forces/total{force}",
+ force_new_page=True,
+ section_title="Forces/Moments",
+ fig_name=f"{force}_fig",
+ exclude=exclude,
+ ylim=SubsetLimit(subset=(0.5, 1), offset=0.25),
+ )
+ for force in force_list
+ ]
+ items.extend(force_charts)
+
+ if include_forces_moments_alpha_charts:
+ force_alpha_charts = [
+ Chart2D(
+ x=f"params/operating_condition/alpha",
+ y=f"total_forces/averages/{force}",
+ force_new_page=True,
+ section_title="Averaged Forces/Moments against alpha",
+ fig_name=f"{force}_alpha_fig",
+ )
+ for force in force_list
+ ]
+ items.extend(force_alpha_charts)
+
+ if include_forces_moments_beta_charts:
+ force_beta_charts = [
+ Chart2D(
+ x=f"params/operating_condition/beta",
+ y=f"total_forces/averages/{force}",
+ force_new_page=True,
+ section_title="Averaged Forces/Moments against beta",
+ fig_name=f"{force}_beta_fig",
+ )
+ for force in force_list
+ ]
+ items.extend(force_beta_charts)
+
+ if include_yplus:
+ y_plus_screenshots = [
+ Chart3D(
+ caption=PatternCaption(pattern=f"y+_{camera_name}_[case.name]"),
+ show="boundaries",
+ field="yPlus",
+ exclude=exclude,
+ limits=(0, 5),
+ camera=camera,
+ fig_name=f"yplus_{camera_name}_fig",
+ fig_size=1,
+ )
+ for camera_name, camera in zip(geo_camera_names, geo_cameras)
+ ]
+ items.extend(y_plus_screenshots)
+
+ if include_cp:
+ cp_screenshots = [
+ Chart3D(
+ caption=PatternCaption(pattern=f"Cp_{camera_name}_[case.name]"),
+ show="boundaries",
+ field="Cp",
+ exclude=exclude,
+ limits=(-1, 1),
+ camera=camera,
+ fig_name=f"cp_{camera_name}_fig",
+ fig_size=1,
+ )
+ for camera_name, camera in zip(geo_camera_names, geo_cameras)
+ ]
+ items.extend(cp_screenshots)
+
+ if include_cf_vec:
+ cfvec_screenshots = [
+ Chart3D(
+ caption=PatternCaption(pattern=f"Cf_vec_{camera_name}_[case.name]"),
+ show="boundaries",
+ field="CfVec",
+ mode="lic",
+ exclude=exclude,
+ limits=(0, 0.025),
+ camera=camera,
+ fig_name=f"cfvec_{camera_name}_fig",
+ fig_size=1,
+ )
+ for camera_name, camera in zip(geo_camera_names, geo_cameras)
+ ]
+ items.extend(cfvec_screenshots)
+
+ if include_qcriterion:
+ qcriterion_screenshots = [
+ Chart3D(
+ caption=PatternCaption(pattern=f"Isosurface_q_criterion_{camera_name}_[case.name]"),
+ show="isosurface",
+ iso_field="qcriterion",
+ exclude=exclude,
+ limits=(0, 0.8),
+ camera=camera,
+ fig_name=f"qcriterion_{camera_name}_fig",
+ fig_size=1,
+ )
+ for camera_name, camera in zip(geo_camera_names, geo_cameras)
+ ]
+ items.extend(qcriterion_screenshots)
+
+ report = ReportTemplate(
+ title="Sweep Template Report",
+ items=items,
+ settings=Settings(dpi=150),
+ )
+
+ report = report.create_in_cloud(
+ "sweep-script-report",
+ cases,
+ )
+
+ report.wait()
+ report.download("report.pdf")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/post_processing/report/sweep_launch_template.py b/examples/post_processing/report/sweep_launch_template.py
new file mode 100644
index 000000000..4c70de5c5
--- /dev/null
+++ b/examples/post_processing/report/sweep_launch_template.py
@@ -0,0 +1,289 @@
+"""
+Sample Flow 360 API scripts.
+Requires a volume mesh or CAD file that you are ready to upload and run cases on.
+
+This script will:
+1:
+ Either:
+ 1.a- create a project and upload a volume mesh
+ 1.b-create a project and upload a CAD. Mesh parameters will need to be given and mesh will creation will need to be launched
+ 1.c- connect to an existing project and associate with a volume mesh from that project.
+
+2:
+ Create the directory structure on the local machine to organize the data that will be generated
+
+3:
+ -Launch all cases required for the sweep
+ -Save all the caseID and other relevant data in the directory created in step 2: above
+"""
+
+import os
+
+import pandas as pd
+from sweep_launch_report import csv_reader, generate_report
+
+import flow360 as fl
+from flow360 import u
+from flow360.examples import EVTOL
+
+# Variables we want to export in our volume and surface solution files. Many more are available.
+vol_fields = ["Mach", "Cp", "mut", "mutRatio", "primitiveVars", "qcriterion"]
+surf_fields = ["Cp", "yPlus", "Cf", "CfVec", "primitiveVars", "wallDistance"]
+
+velocity_magnitude = 100 * u.m / u.s
+
+
+######################################################################################################################
+def make_run_params(mesh_object, models):
+ """
+ Create the params object that contains all the run parameters.
+ Needs the mesh_object to get the list of surfaces.
+ """
+ with fl.SI_unit_system:
+ params = fl.SimulationParams(
+ # Dimensions can be either in inches, m, mm or many other units
+ reference_geometry=fl.ReferenceGeometry(
+ moment_center=(0, 0, 0) * u.m, moment_length=1 * u.m, area=1 * u.m * u.m
+ ),
+ operating_condition=fl.AerospaceCondition(
+ velocity_magnitude=velocity_magnitude, alpha=0 * u.deg
+ ),
+ time_stepping=fl.Steady(max_steps=5000, CFL=fl.AdaptiveCFL()),
+ models=[
+ *models,
+ fl.Fluid(
+ navier_stokes_solver=fl.NavierStokesSolver(),
+ turbulence_model_solver=fl.SpalartAllmaras(),
+ ),
+ ],
+ outputs=[
+ fl.VolumeOutput(output_format="tecplot", output_fields=vol_fields),
+ # mesh_object['*'] will select all the boundaries in the mesh and export the surface results.
+ # Regular expressions can be used to filter for certain boundaries.
+ fl.SurfaceOutput(
+ surfaces=[mesh_object["*"]], output_fields=surf_fields, output_format="tecplot"
+ ),
+ ],
+ )
+
+ # Add meshing params in case the project starts from geometry.
+ params.meshing = mesh_object.params.meshing
+
+ return params
+
+
+######################################################################################################################
+def launch_sweep(params, project, mesh_object, dir_path):
+ """
+ Launch a sweep of cases.
+ """
+
+ case_list = []
+
+ # Create the csv file where we will store all relevant sweep data.
+ os.makedirs(dir_path, exist_ok=True)
+ csv_path = os.path.join(dir_path, "sweep_saved_data.csv")
+ general_info = {
+ "Sweep name": os.path.basename(dir_path),
+ "Project name": project.metadata.name,
+ "Project ID": project.id,
+ "Volume mesh ID": mesh_object.id,
+ "Velocity magnitude": velocity_magnitude,
+ }
+ df = pd.DataFrame.from_dict([general_info])
+ df.to_csv(csv_path, index=False)
+
+ # For example let's vary alpha:
+ alphas = [-10, -5, 0, 5, 10, 12, 14] * u.deg
+
+ cases_params = []
+ for i, alpha_angle in enumerate(alphas):
+ # modify the alpha
+ params.operating_condition.alpha = alpha_angle
+
+ case = project.run_case(params=params, name=f"alpha_{alpha_angle.value}_case")
+ data = {
+ "case_id": case.id,
+ "alpha(deg)": params.operating_condition.alpha.value,
+ "beta(deg)": params.operating_condition.beta.value,
+ }
+
+ print(f"The case ID is: {case.id} with {alpha_angle=} ")
+ case_list.append(case)
+ cases_params.append(data)
+
+ # fraction used for averaging over the last % of iterations, 0.1 -> last 10%
+ fraction = 0.1
+
+ cases_forces = []
+ for i, case in enumerate(case_list):
+ case.wait()
+ results = case.results
+ avg_total_forces = results.total_forces.get_averages(fraction).to_dict()
+ forces = {
+ "CL(avg)": avg_total_forces["CL"],
+ "CD(avg)": avg_total_forces["CD"],
+ "CFx(avg)": avg_total_forces["CFx"],
+ "CFy(avg)": avg_total_forces["CFy"],
+ "CFz(avg)": avg_total_forces["CFz"],
+ "CMx(avg)": avg_total_forces["CMx"],
+ "CMy(avg)": avg_total_forces["CMy"],
+ "CMz(avg)": avg_total_forces["CMz"],
+ }
+ cases_forces.append(forces)
+
+ df_data = pd.DataFrame.from_dict(cases_params)
+ df_forces = pd.DataFrame.from_dict(cases_forces)
+ df = df_data.join(df_forces)
+ df.to_csv(csv_path, index=False, mode="a")
+
+ return csv_path
+
+
+######################################################################################################################
+def create_mesh_params(project):
+ """
+
+ Create the parameters object containing all the information required by the solver to generate the mesh
+
+ Parameters
+ ----------
+ project
+
+ Returns
+ -------
+ params object
+ """
+
+ geometry = project.geometry
+ geometry.group_faces_by_tag("faceName")
+ geometry.group_edges_by_tag("edgeName")
+ with fl.SI_unit_system:
+ params = fl.SimulationParams(
+ meshing=fl.MeshingParams(
+ defaults=fl.MeshingDefaults(
+ boundary_layer_first_layer_thickness=1e-5, surface_max_edge_length=1
+ ),
+ volume_zones=[fl.AutomatedFarfield()],
+ refinements=[
+ fl.SurfaceEdgeRefinement(
+ name="leading_edges",
+ edges=[geometry["leadingEdge"]],
+ method=fl.AngleBasedRefinement(value=2 * u.deg),
+ )
+ ],
+ )
+ )
+ return params
+
+
+def assign_boundary_conditions(project):
+
+ if project.project_tree.root.asset_type == "Geometry":
+ geo = project.geometry
+ geo.group_faces_by_tag("faceName")
+ models = [
+ fl.Wall(
+ surfaces=[
+ # "*" will select all geometry boundaries
+ geo["*"],
+ ],
+ ),
+ fl.Freestream(surfaces=fl.AutomatedFarfield().farfield),
+ ]
+ else:
+ vm = project.volume_mesh
+ models = [
+ fl.Wall(
+ surfaces=[
+ vm["fluid/fuselage"],
+ # *_pylon will select all boundaries ending with _pylon
+ vm["fluid/*_pylon"],
+ vm["fluid/left_wing"],
+ vm["fluid/right_wing"],
+ vm["fluid/h_tail"],
+ vm["fluid/v_tail"],
+ ],
+ ),
+ fl.Freestream(surfaces=vm["fluid/farfield"]),
+ ]
+ return models
+
+
+def project_from_volume_mesh():
+ EVTOL.get_files()
+ project_name = "sweep_evtol_from_mesh"
+ project = fl.Project.from_volume_mesh(
+ EVTOL.mesh_filename, # mesh could also be in ugrid format
+ name=project_name,
+ length_unit="m", # length_unit should be 'm', 'mm', 'cm', 'inch' or 'ft'
+ )
+
+ return project
+
+
+def project_from_geometry():
+ EVTOL.get_files()
+ project_name = "sweep_evtol_from_geometry"
+ project = fl.Project.from_geometry(EVTOL.geometry, name=project_name)
+ mesh_params = create_mesh_params(project)
+ project.generate_volume_mesh(params=mesh_params, name="mesh_name")
+
+ return project
+
+
+######################################################################################################################
+def main():
+ """
+ Main function that drives the functions to achieve all the steps mentioned at the top.
+ """
+
+ # Step1: Connect to an existing project and volume mesh.
+ # Chose one of two options below
+
+ # Option 1a: If you want to upload a new mesh and create a new project.
+ project = project_from_volume_mesh()
+
+ # Option 1b: If you want to upload a CAD geometry and create a new project.
+ # project = project_from_geometry()
+
+ # Option 1c: if you want to run from an existing project.
+ # project = fl.Project.from_cloud(
+ # 'prj-XXXXXXXXXXX') # where prj-XXXXXXXXXX is an ID that can be saved from a previously created project or read off the WEBUI
+
+ vm = project.volume_mesh
+ # If the project has more then one mesh then use hte line below to choose a specific mesh instead.
+ # vm = project.get_volume_mesh(asset_id='vm-XXXXXXXXXXXXXXX')
+
+ print(f"The project id is {project.id}")
+ print(f"The volume mesh contains the following boundaries:{vm.boundary_names}")
+ print(f"The volume mesh ID is: {vm.id}")
+
+ # Step 2: Create the directories to locally store relevant data.
+ dir_name = "evtol_alpha_sweep"
+
+ # Step3: Launch the cases and save the relevant data.
+ models = assign_boundary_conditions(project)
+ params = make_run_params(vm, models)
+ csv_path = launch_sweep(params, project, vm, dir_name)
+
+ generate_report(
+ *csv_reader(csv_path),
+ include_geometry=True,
+ include_general_tables=True,
+ include_residuals=True,
+ include_cfl=True,
+ include_forces_moments_table=True,
+ include_forces_moments_charts=True,
+ include_forces_moments_alpha_charts=True,
+ include_forces_moments_beta_charts=True,
+ include_cf_vec=True,
+ include_cp=True,
+ include_yplus=True,
+ include_qcriterion=True,
+ )
+
+
+######################################################################################################################
+if __name__ == "__main__":
+ main()
diff --git a/examples/post_processing/special_features/bet_disk.py b/examples/post_processing/special_features/bet_disk.py
index 2501b3e30..20903fe4e 100644
--- a/examples/post_processing/special_features/bet_disk.py
+++ b/examples/post_processing/special_features/bet_disk.py
@@ -4,6 +4,14 @@
import flow360 as fl
from flow360.examples import BETExampleData
+from flow360.plugins.report.report import ReportTemplate
+from flow360.plugins.report.report_items import (
+ Chart3D,
+ FrontCamera,
+ Inputs,
+ Settings,
+ Summary,
+)
BETExampleData.get_files()
@@ -86,4 +94,29 @@
# save converted results to a new CSV file:
results.bet_forces.to_file(os.path.join(case.name, "bet_forces_in_SI.csv"))
-# Report workflows have moved to the standalone `flow360-report` package.
+cases = [case]
+
+front_camera_slice = FrontCamera(dimension=350, dimension_dir="height")
+
+bet_slice_screenshot = Chart3D(
+ section_title="BET effective AoA",
+ items_in_row=2,
+ force_new_page=True,
+ show="slices",
+ include=["slice_x"],
+ field="betMetrics_AlphaDegrees",
+ limits=(-18, 0),
+ camera=front_camera_slice,
+ fig_name="slice_x",
+)
+
+report = ReportTemplate(
+ title="BET results screenshots",
+ items=[Summary(), Inputs(), bet_slice_screenshot],
+ settings=Settings(dpi=150),
+)
+
+report = report.create_in_cloud("BET, dpi=default", cases)
+
+report.wait()
+report.download("report.pdf")
diff --git a/examples/post_processing/special_features/heat_transfer.py b/examples/post_processing/special_features/heat_transfer.py
index d67ba3dfd..1c3e26b7b 100644
--- a/examples/post_processing/special_features/heat_transfer.py
+++ b/examples/post_processing/special_features/heat_transfer.py
@@ -1,6 +1,16 @@
import flow360 as fl
from flow360 import u
from flow360.examples import TutorialCHTSolver
+from flow360.plugins.report.report import ReportTemplate
+from flow360.plugins.report.report_items import (
+ Camera,
+ Chart3D,
+ FrontCamera,
+ Inputs,
+ LeftCamera,
+ Settings,
+ Summary,
+)
TutorialCHTSolver.get_files()
@@ -105,4 +115,61 @@
surface_heat_transfer = results.surface_heat_transfer.as_dataframe()
print(surface_heat_transfer)
-# Report generation utilities now live in the external `flow360-report` package.
+cases = [case]
+
+exclude = ["fluid/farfield", "solid/interface_fluid", "solid/adiabatic"]
+
+front_camera_slice = FrontCamera(dimension=1, dimension_dir="width")
+side_camera_slice = LeftCamera(pan_target=(0.35, 0, 0), dimension=2, dimension_dir="width")
+front_right_top_camera = Camera(
+ position=(-1, -1, 1), look_at=(0.35, 0, 0), dimension=1, dimension_dir="width"
+)
+
+x_slice_screenshot = Chart3D(
+ section_title="Slice temperature at x=0.35",
+ items_in_row=2,
+ force_new_page=True,
+ show="slices",
+ include=["slice_x"],
+ field="T",
+ limits=(285 * u.K, 395 * u.K),
+ camera=front_camera_slice,
+ fig_name="slice_x",
+)
+
+y_slice_screenshot = Chart3D(
+ section_title="Slice temperature at y=0",
+ items_in_row=2,
+ force_new_page=True,
+ show="slices",
+ include=["slice_y"],
+ field="T",
+ limits=(285 * u.K, 395 * u.K),
+ camera=side_camera_slice,
+ fig_name="slice_y",
+)
+
+surface_screenshot = Chart3D(
+ section_title="Surface temperature",
+ items_in_row=2,
+ force_new_page=True,
+ show="boundaries",
+ field="T",
+ limits=(285 * u.K, 395 * u.K),
+ exclude=exclude,
+ camera=front_right_top_camera,
+)
+
+report = ReportTemplate(
+ title="CHT results screenshots",
+ items=[Summary(), Inputs(), x_slice_screenshot, y_slice_screenshot, surface_screenshot],
+ settings=Settings(dpi=150),
+)
+
+report = report.create_in_cloud(
+ "CHT, dpi=default",
+ cases,
+)
+
+report.wait()
+report.download("report.pdf")
diff --git a/examples/tutorials/notebooks/notebook_automotive.ipynb b/examples/tutorials/notebooks/notebook_automotive.ipynb
index 175cada4a..2a1790b55 100644
--- a/examples/tutorials/notebooks/notebook_automotive.ipynb
+++ b/examples/tutorials/notebooks/notebook_automotive.ipynb
@@ -785,6 +785,41 @@
">Note: Importing units (u) here is only for the sake of convenience."
]
},
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from flow360 import u\n",
+ "from flow360.plugins.report.report import ReportTemplate\n",
+ "from flow360.plugins.report.report_items import (\n",
+ " BottomCamera,\n",
+ " Chart2D,\n",
+ " Chart3D,\n",
+ " FrontCamera,\n",
+ " FrontLeftBottomCamera,\n",
+ " FrontLeftTopCamera,\n",
+ " Inputs,\n",
+ " LeftCamera,\n",
+ " RearCamera,\n",
+ " RearLeftTopCamera,\n",
+ " RearRightBottomCamera,\n",
+ " Settings,\n",
+ " Summary,\n",
+ " Table,\n",
+ " TopCamera,\n",
+ ")\n",
+ "from flow360.plugins.report.utils import (\n",
+ " Average,\n",
+ " DataItem,\n",
+ " Delta,\n",
+ " Expression,\n",
+ " Variable,\n",
+ " GetAttribute,\n",
+ ")"
+ ]
+ },
{
"cell_type": "markdown",
"metadata": {},
@@ -994,12 +1029,308 @@
")"
]
},
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "#### Visualizations\n",
+ "\n",
+ "Here we will define separate lists of `Chart3D`, which are essentially 3D visualizations (you can think of them as screenshots of your model). These come with a variety of options that can be used to customize the way data is shown.\n",
+ "\n",
+ "One of the common things is that pretty much all of those charts contain either an exclude or include field. They provide control over what parts of the simulation domain will be excluded/included in the image.\n",
+ "\n",
+ ">Note: If you took a peek at the charts you may have noticed that list comprehension can used to iterate over camera positions."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "forces = [\n",
+ " Chart2D(\n",
+ " x=\"x_slicing_force_distribution/X\",\n",
+ " y=\"x_slicing_force_distribution/totalCumulative_CD_Curve\",\n",
+ " fig_name=\"totalCumulative_CD_Curve\",\n",
+ " background=\"geometry\",\n",
+ " exclude=exclude,\n",
+ " ),\n",
+ " Chart2D(\n",
+ " x=\"surface_forces/pseudo_step\",\n",
+ " y=\"surface_forces/totalCD\",\n",
+ " section_title=\"Drag Coefficient\",\n",
+ " fig_name=\"cd_fig\",\n",
+ " exclude=exclude,\n",
+ " focus_x=(1 / 3, 1),\n",
+ " ),\n",
+ "]\n",
+ "geometry_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=\"Geometry\",\n",
+ " items_in_row=2,\n",
+ " force_new_page=True,\n",
+ " show=\"boundaries\",\n",
+ " camera=camera,\n",
+ " exclude=exclude,\n",
+ " fig_name=f\"geo_{i}\",\n",
+ " )\n",
+ " for i, camera in enumerate(cameras_geo)\n",
+ "]\n",
+ "cpt_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=\"Isosurface, Cpt=-1\",\n",
+ " items_in_row=2,\n",
+ " force_new_page=True,\n",
+ " show=\"isosurface\",\n",
+ " iso_field=\"Cpt\",\n",
+ " exclude=exclude,\n",
+ " camera=camera,\n",
+ " )\n",
+ " for camera in cameras_cp\n",
+ "]\n",
+ "cfvec_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=\"CfVec\",\n",
+ " items_in_row=2,\n",
+ " force_new_page=True,\n",
+ " show=\"boundaries\",\n",
+ " field=\"CfVec\",\n",
+ " mode=\"lic\",\n",
+ " limits=(1e-4, 10),\n",
+ " is_log_scale=True,\n",
+ " exclude=exclude,\n",
+ " camera=camera,\n",
+ " )\n",
+ " for camera in cameras_cp\n",
+ "]\n",
+ "y_slices_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=f\"Slice velocity y={y}\",\n",
+ " items_in_row=2,\n",
+ " force_new_page=True,\n",
+ " show=\"slices\",\n",
+ " include=[f\"slice_y_{name}\"],\n",
+ " field=\"velocity\",\n",
+ " limits=(0 * u.m / u.s, 50 * u.m / u.s),\n",
+ " camera=side_camera_slice,\n",
+ " fig_name=f\"slice_y_{name}\",\n",
+ " )\n",
+ " for name, y in zip([\"0\", \"0_2\", \"0_4\", \"0_6\", \"0_8\"], [0, 0.2, 0.4, 0.6, 0.8])\n",
+ "]\n",
+ "y_slices_lic_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=f\"Slice velocity LIC y={y}\",\n",
+ " items_in_row=2,\n",
+ " force_new_page=True,\n",
+ " show=\"slices\",\n",
+ " include=[f\"slice_y_{name}\"],\n",
+ " field=\"velocityVec\",\n",
+ " mode=\"lic\",\n",
+ " limits=(0 * u.m / u.s, 50 * u.m / u.s),\n",
+ " camera=side_camera_slice,\n",
+ " fig_name=f\"slice_y_vec_{name}\",\n",
+ " )\n",
+ " for name, y in zip([\"0\", \"0_2\", \"0_4\", \"0_6\", \"0_8\"], [0, 0.2, 0.4, 0.6, 0.8])\n",
+ "]\n",
+ "z_slices_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=f\"Slice velocity z={z}\",\n",
+ " items_in_row=2,\n",
+ " force_new_page=True,\n",
+ " show=\"slices\",\n",
+ " include=[f\"slice_z_{name}\"],\n",
+ " field=\"velocity\",\n",
+ " limits=(0 * u.m / u.s, 50 * u.m / u.s),\n",
+ " camera=top_camera_slice,\n",
+ " fig_name=f\"slice_z_{name}\",\n",
+ " )\n",
+ " for name, z in zip([\"neg0_2\", \"0\", \"0_2\", \"0_4\", \"0_6\", \"0_8\"], [-0.2, 0, 0.2, 0.4, 0.6, 0.8])\n",
+ "]\n",
+ "y_plus_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=\"y+\",\n",
+ " items_in_row=2,\n",
+ " show=\"boundaries\",\n",
+ " field=\"yPlus\",\n",
+ " exclude=exclude,\n",
+ " limits=(0, 5),\n",
+ " camera=camera,\n",
+ " fig_name=f\"yplus_{i}\",\n",
+ " )\n",
+ " for i, camera in enumerate([top_camera, bottom_camera])\n",
+ "]\n",
+ "cp_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=\"Cp\",\n",
+ " items_in_row=2,\n",
+ " show=\"boundaries\",\n",
+ " field=\"Cp\",\n",
+ " exclude=exclude,\n",
+ " limits=limits,\n",
+ " camera=camera,\n",
+ " fig_name=f\"cp_{i}\",\n",
+ " )\n",
+ " for i, (limits, camera) in enumerate(zip(limits_cp, cameras_cp))\n",
+ "]\n",
+ "cpx_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=\"Cpx\",\n",
+ " items_in_row=2,\n",
+ " show=\"boundaries\",\n",
+ " field=\"Cpx\",\n",
+ " exclude=exclude,\n",
+ " limits=(-0.3, 0.3),\n",
+ " camera=camera,\n",
+ " fig_name=f\"cpx_{i}\",\n",
+ " )\n",
+ " for i, camera in enumerate(cameras_cp)\n",
+ "]\n",
+ "wall_shear_screenshots = [\n",
+ " Chart3D(\n",
+ " section_title=\"Wall shear stress magnitude\",\n",
+ " items_in_row=2,\n",
+ " show=\"boundaries\",\n",
+ " field=\"wallShearMag\",\n",
+ " exclude=exclude,\n",
+ " limits=(0 * u.Pa, 5 * u.Pa),\n",
+ " camera=camera,\n",
+ " fig_name=f\"wallShearMag_{i}\",\n",
+ " )\n",
+ " for i, camera in enumerate(cameras_cp)\n",
+ "]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "#### Report assembly\n",
+ "\n",
+ "Once we have all of the components of our report, we can create a `ReportTemplate` that will allow us to then generate the report itself. In our case, we will also add two `Chart2D`s related to drag coefficient."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 17,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "report_template = ReportTemplate(\n",
+ " title=\"Aerodynamic analysis of DrivAer\",\n",
+ " items=[\n",
+ " Summary(),\n",
+ " Inputs(),\n",
+ " statistical_table_general,\n",
+ " statistical_table_forces,\n",
+ " *forces,\n",
+ " *geometry_screenshots,\n",
+ " *cp_screenshots,\n",
+ " *cpx_screenshots,\n",
+ " *cpt_screenshots,\n",
+ " *y_slices_screenshots,\n",
+ " *y_slices_lic_screenshots,\n",
+ " *z_slices_screenshots,\n",
+ " *y_plus_screenshots,\n",
+ " *wall_shear_screenshots,\n",
+ " ],\n",
+ " settings=Settings(dpi=150),\n",
+ ")"
+ ]
+ },
{
"cell_type": "markdown",
"metadata": {},
"source": [
"All that is left now is to create the report by calling the `create_in_cloud()` function, then downloading it. To ensure that the download will only start after the report has actually been generated, we use `wait()`."
]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 18,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "application/vnd.jupyter.widget-view+json": {
+ "model_id": "87aaf851429a4b2ba59e36507a9dd1b8",
+ "version_major": 2,
+ "version_minor": 0
+ },
+ "text/plain": [
+ "Output()"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/html": [
+ "\n"
+ ],
+ "text/plain": []
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "application/vnd.jupyter.widget-view+json": {
+ "model_id": "69c8a4f4849f48898412f0dc4755f344",
+ "version_major": 2,
+ "version_minor": 0
+ },
+ "text/plain": [
+ "Output()"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/html": [
+ "\n"
+ ],
+ "text/plain": []
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/html": [
+ "[14:15:44] INFO: Saved to report.pdf \n",
+ "
\n"
+ ],
+ "text/plain": [
+ "\u001b[2;36m[14:15:44]\u001b[0m\u001b[2;36m \u001b[0m\u001b[36mINFO\u001b[0m: Saved to report.pdf \n"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/plain": [
+ "'report.pdf'"
+ ]
+ },
+ "execution_count": 18,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "report = report_template.create_in_cloud(\n",
+ " f\"{size}-{len(cases)}cases-slices-using-groups-Cpt, Cpx, wallShear, dpi=default\",\n",
+ " cases,\n",
+ ")\n",
+ "\n",
+ "report.wait()\n",
+ "report.download(\"report.pdf\")"
+ ]
}
],
"metadata": {
@@ -1023,4 +1354,4 @@
},
"nbformat": 4,
"nbformat_minor": 2
-}
\ No newline at end of file
+}
diff --git a/flow360/__init__.py b/flow360/__init__.py
index 30fe688d7..c8ad893b9 100644
--- a/flow360/__init__.py
+++ b/flow360/__init__.py
@@ -203,6 +203,7 @@
from flow360.component.surface_mesh_v2 import SurfaceMeshV2 as SurfaceMesh
from flow360.component.volume_mesh import VolumeMeshV2 as VolumeMesh
from flow360.environment import Env
+from flow360.plugins import report
from flow360.version_utils import warn_if_prerelease_version as _warn_prerelease
__all__ = [
@@ -346,6 +347,7 @@
"UserVariable",
"math",
"solution",
+ "report",
"snappy",
"ModularMeshingWorkflow",
"SeedpointVolume",
diff --git a/flow360/cloud/flow360_requests.py b/flow360/cloud/flow360_requests.py
index 4e294ebce..79410ed38 100644
--- a/flow360/cloud/flow360_requests.py
+++ b/flow360/cloud/flow360_requests.py
@@ -183,6 +183,20 @@ class NewSurfaceMeshDependencyRequest(Flow360RequestsV2):
icon: str = pd_v2.Field(default="", description="project description")
+class _Resource(Flow360RequestsV2):
+ type: Literal["Case", "Project"]
+ id: str
+
+
+class NewReportRequest(Flow360RequestsV2):
+ "New report request"
+
+ name: str
+ resources: List[_Resource]
+ config_json: str
+ solver_version: str
+
+
class DraftCreateRequest(Flow360RequestsV2):
"""Data model for draft create request"""
diff --git a/flow360/component/project.py b/flow360/component/project.py
index cab7a6c55..ce4f632e4 100644
--- a/flow360/component/project.py
+++ b/flow360/component/project.py
@@ -80,6 +80,7 @@
Flow360WebError,
)
from flow360.log import log
+from flow360.plugins.report.report import get_default_report_summary_template
from flow360.version import __solver_version__
AssetOrResource = Union[type[AssetBase], type[Flow360Resource]]
@@ -2214,4 +2215,10 @@ def run_case(
draft = case_or_draft
return draft
case = case_or_draft
+ report_template = get_default_report_summary_template()
+ report_template.create_in_cloud(
+ name=f"{name}-summary",
+ cases=[case],
+ solver_version=solver_version if solver_version else self.solver_version,
+ )
return case
diff --git a/flow360/component/simulation/services.py b/flow360/component/simulation/services.py
index c341a7540..b4e7d8c44 100644
--- a/flow360/component/simulation/services.py
+++ b/flow360/component/simulation/services.py
@@ -94,6 +94,7 @@
Flow360TranslationError,
Flow360ValueError,
)
+from flow360.plugins.report.report import get_default_report_summary_template
from flow360.version import __version__
# Required for correct global scope initialization
@@ -1181,6 +1182,19 @@ def translate_xfoil_c81_bet_disk(
return bet_dict_list, errors
+def get_default_report_config() -> dict:
+ """
+ Get the default report config
+ Returns
+ -------
+ dict
+ default report config
+ """
+ return get_default_report_summary_template().model_dump(
+ exclude_none=True,
+ )
+
+
def _parse_root_item_type_from_simulation_json(*, param_as_dict: dict):
"""[External] Deduct the root item entity type from simulation.json"""
try:
diff --git a/flow360/plugins/__init__.py b/flow360/plugins/__init__.py
deleted file mode 100644
index 205e11b5b..000000000
--- a/flow360/plugins/__init__.py
+++ /dev/null
@@ -1,22 +0,0 @@
-"""
-Flow360 plugin namespace.
-
-Report-related functionality has moved to the standalone `flow360-report` package.
-Install it via `pip install flow360-report` if you need reporting utilities.
-"""
-
-from typing import Any
-
-_REPORT_HINT = (
- "flow360 reporting utilities now live in the `flow360-report` package. "
- "Install it via `pip install flow360-report` and import from `flow360_report.plugins.report`."
-)
-
-
-def __getattr__(name: str) -> Any:
- if name == "report":
- raise ImportError(_REPORT_HINT)
- raise AttributeError(f"module 'flow360.plugins' has no attribute '{name}'")
-
-
-__all__: list[str] = []
diff --git a/flow360/plugins/report/README.md b/flow360/plugins/report/README.md
new file mode 100644
index 000000000..23ea80864
--- /dev/null
+++ b/flow360/plugins/report/README.md
@@ -0,0 +1,311 @@
+# Report Plugin
+
+The **Report Plugin** provides automated PDF report generation for simulation results. It integrates with Flow360 (or similar frameworks) to pull data from simulation cases, produce tables and charts, and optionally render 3D images or screenshots. Users can easily configure how the PDF is structured, which items to include (e.g., summaries, inputs, tables, 2D and 3D charts), and how to style each item.
+
+---
+
+## Table of Contents
+- [Report Plugin](#report-plugin)
+ - [Table of Contents](#table-of-contents)
+ - [Overview](#overview)
+ - [Features](#features)
+ - [Folder and File Structure](#folder-and-file-structure)
+ - [Installation](#installation)
+ - [Usage](#usage)
+ - [1. Create or Load Simulation Cases](#1-create-or-load-simulation-cases)
+ - [2. Prepare a Report Configuration](#2-prepare-a-report-configuration)
+ - [3. Invoke the Plugin](#3-invoke-the-plugin)
+ - [Configuration and Customization](#configuration-and-customization)
+ - [Generating Screenshots](#generating-screenshots)
+ - [Camera controls:](#camera-controls)
+ - [Key Camera Attributes](#key-camera-attributes)
+ - [Camera Examples](#camera-examples)
+ - [Examples](#examples)
+ - [Minimal Example](#minimal-example)
+
+---
+
+## Overview
+
+This plugin:
+- Loads simulation data from one or more **Case** objects.
+- Extracts relevant metrics, such as velocities, forces, boundaries, and other fields.
+- Creates custom sections (e.g. *Summary*, *Inputs*, *Tables*, *Charts*) and assembles them into a single LaTeX-based PDF document.
+- Can optionally include 3D images or screenshots of the geometry, surfaces, or isosurfaces for an at-a-glance view of simulation geometry or results.
+
+---
+
+## Features
+
+1. **Section-Based Reporting**
+ - Easily add sections like `Summary`, `Inputs`, and custom sections with specialized content.
+
+2. **Tables**
+ - Collect data from one or multiple simulation cases and display in tabular form using the `Table` class.
+ - Built-in support for custom formatting (e.g., `.5g` or specialized formatting functions).
+
+3. **2D Charts**
+ - Plot data such as forces, residuals, or general x-y plots with `Chart2D`.
+ - Supports logarithmic scaling if needed (e.g., for residual plots).
+ - Can combine multiple cases into one plot or generate separate plots per case.
+
+4. **3D Visualization**
+ - Automatically generate (or embed) images of your 3D geometry (e.g., surfaces, isosurfaces, different camera angles).
+ - Users can opt to generate screenshots of simulation geometry in various positions (requires an external service or local tool to produce the images; see [Generating Screenshots](#generating-screenshots) below).
+
+5. **Flexible Layout**
+ - Choose how items are arranged (one item per page, multiple items per row, etc.).
+ - Control figure sizes, captions, new pages, etc.
+
+---
+
+## Folder and File Structure
+
+A high-level view of the relevant files:
+
+flow360/plugins/report/
+├── report.py # Main file that defines the ReportTemplate class
+├── report_items.py # Contains classes for different report "items" like Summary, Table, Chart2D, Chart3D, etc.
+├── report_context.py # (Imported by others) Manages the context in which the report is generated
+├── utils.py # Utility functions for data extraction, data formatting, etc.
+└── uvf_shutter.py # (Optional) Helper for generating 3D geometry screenshots
+
+Example files in the repo:
+
+examples/
+└── automotive_example_in_cloud.py # Shows how to configure and instantiate a report
+
+## Installation
+
+1. Make sure you have Python 3.8+ installed.
+2. Install flow360 package:
+ ```bash
+ pip install flow360
+ ```
+
+
+
+
+---
+
+## Usage
+
+### 1. Create or Load Simulation Cases
+
+You need one or more **Case** objects that contain all relevant simulation data. The plugin references fields in these cases to build tables and charts.
+
+### 2. Prepare a Report Configuration
+
+Typically, you have a JSON or Python-based config specifying which `ReportItem` objects you want in your report, e.g.:
+
+```python
+report = ReportTemplate(
+ title="Aerodynamic analysis of DrivAer",
+ items=[
+ Summary(text="Short summary..."),
+ Inputs(),
+ Table(
+ data=[
+ "params/reference_geometry/area",
+ DataItem(data="surface_forces/totalCD", operations=Average(fraction=0.1)),
+ "params/time_stepping/max_steps",
+ ],
+ section_title="Statistical data",
+ ),
+ Chart2D(
+ x="surface_forces/pseudo_step",
+ y="surface_forces/totalCD",
+ section_title="Drag Coefficient",
+ fig_name="cd_fig",
+ )
+ ]
+)
+report.to_file('path/to/reportTemplate.json"')
+```
+(This might be stored in a file like reportTemplate.json.)
+
+```JSON
+{
+ "include_case_by_case": false,
+ "items": [
+ {
+ "text": "Short summary...",
+ "type_name": "Summary"
+ },
+ {
+ "type_name": "Inputs"
+ },
+ {
+ "data": [
+ "params/reference_geometry/area",
+ {
+ "data": "surface_forces/totalCD",
+ "operations": [
+ {
+ "fraction": 0.1,
+ "type_name": "Average"
+ }
+ ],
+ "type_name": "DataItem"
+ },
+ "params/time_stepping/max_steps"
+ ],
+ "section_title": "Statistical data",
+ "type_name": "Table"
+ },
+ {
+ "fig_name": "cd_fig",
+ "section_title": "Drag Coefficient",
+ "type_name": "Chart2D",
+ "x": "surface_forces/pseudo_step",
+ "y": "surface_forces/totalCD"
+ }
+ ],
+ "title": "Aerodynamic analysis of DrivAer"
+}
+```
+
+
+
+### 3. Invoke the Plugin
+Use the main ReportTemplate class (from report.py) to build and export your PDF. For example (similar to automotive_example_in_cloud.py):
+
+```python
+from flow360.plugins.report.report import ReportTemplate
+from flow360.component.case import Case
+
+# Suppose you have a list of Case objects
+cases = [...]
+
+# Point to your config:
+report = ReportTemplate(filename="path/to/reportTemplate.json")
+
+# Generate the PDF:
+report.create_pdf(
+ output_folder="my_report_output",
+ cases=cases
+)
+```
+
+
+## Configuration and Customization
+
+- **Report Items**: The core building blocks, each corresponding to a section or figure in the PDF.
+ - *Summary*: Adds a textual overview.
+ - *Inputs*: Collects key input parameters from your cases (e.g., velocity, time-stepping).
+ - *Table*: Aggregates data from multiple cases into one table.
+ - *Chart2D*: Produces an XY plot from data paths in your case(s).
+ - *Chart3D*: Optionally display geometry or color-field surfaces (like `Cp`, `yPlus`, etc.).
+
+- **Custom Data Paths**: Many items accept `data` arrays where each entry references a JSON path inside each case, e.g. `"params/operating_condition/velocity_magnitude"`.
+ - If the plugin finds that path in each case’s data, it extracts the values and populates the table/plot.
+
+- **Formatting**:
+ - Use built-in format specifiers or pass a custom function to format numeric data.
+ - For tables, set `formatter` as a string (e.g. `".5g"`) or a callable for specialized formatting.
+
+- **Multiple Cases**: If you provide multiple cases in a single run, the plugin can:
+ - Combine them side by side in tables.
+ - Overlay them on the same chart.
+ - Generate separate pages or subplots (use `separate_plots=True` or `items_in_row=...` to configure layout).
+
+
+
+## Generating Screenshots
+
+The plugin can produce screenshots of your simulation geometry or results. You can activate this in `Chart3D` items by specifying a field or object type to display. The actual screenshot generation leverages an external tool, but the plugin manages how the images are embedded in the final PDF.
+
+
+### Camera controls:
+
+The `Camera` class specifies a 3D viewpoint and zoom for rendering geometry or visualizing simulation results. By adjusting properties such as `position`, `look_at`, and `dimension`, users can control the angle, orientation, and scale of the view. Below are the attributes you can configure (note that all lengths are in the same units used in your geometry or volume mesh):
+
+
+### Key Camera Attributes
+
+- **Position**
+ The camera’s eye position in 3D space. Typically, you can think of it as a point on a sphere, looking inward toward `look_at`. Adjusting `position` can rotate the view around the object of interest.
+
+- **Up**
+ A vector that determines which way is “up” in the final image. Changing this can rotate the view around the axis from the camera’s position to the `look_at` point.
+
+- **Look At**
+ The point at which the camera is aimed. By default, if unspecified, it’s often the bounding-box center of your model.
+
+- **Pan Target**
+ A specific point to which you want to pan your camera’s center. If left unset, `look_at` remains the default center of view.
+
+- **Dimension & Dimension Direction**
+ Together, these control the zoom level. For example, if `dimension_dir` is `"width"` and `dimension` is `2.0`, the rendered view’s width represents 2 model units. Similarly, use `"height"` or `"diagonal"` to scale in those directions.
+
+
+---
+
+### Camera Examples
+
+
+
+See how changing `position` and `look_at` affects the orientation of the camera.
+
+
+
+See how `pan_target` changes the view.
+
+
+
+See the effect of `dimension` and `dimension_dir` on zoom level.
+
+
+
+
+## Examples
+
+### Minimal Example
+
+```python
+from flow360.plugins.report.report import ReportTemplate
+from flow360.plugins.report.report_items import *
+
+cases = [...] # Load or define your cases
+
+report = ReportTemplate(
+ title="Aerodynamic analysis of DrivAer",
+ items=[
+ Summary(text="Short summary..."),
+ Inputs(),
+ Table(
+ data=[
+ "params/reference_geometry/area",
+ DataItem(data="surface_forces/totalCD", operations=Average(fraction=0.1)),
+ "params/time_stepping/max_steps",
+ ],
+ section_title="Statistical data",
+ ),
+ Chart2D(
+ x="surface_forces/pseudo_step",
+ y="surface_forces/totalCD",
+ section_title="Drag Coefficient",
+ fig_name="cd_fig",
+ )
+ ]
+)
+
+# Save the JSON config or pass it directly:
+report.create_pdf(
+ "my_report",
+ cases
+)
+report.wait()
+report.download("my_report.pdf")
+```
+
+
+After running, check the my_report.pdf for your compiled PDF.
+
+More Advanced
+See `automotive_example_in_cloud.py` for more advanced usage (multiple 3D fields, custom cameras, integration with a pipeline, etc.).
+
+
+---
+
+**Enjoy creating automated simulation reports with the Report Plugin!**
diff --git a/flow360/plugins/report/__init__.py b/flow360/plugins/report/__init__.py
new file mode 100644
index 000000000..e3dd44434
--- /dev/null
+++ b/flow360/plugins/report/__init__.py
@@ -0,0 +1,69 @@
+"""Utilities for creating reports"""
+
+from flow360.plugins.report.report import ReportTemplate
+from flow360.plugins.report.report_items import (
+ Chart2D,
+ Chart3D,
+ FixedRangeLimit,
+ Inputs,
+ ManualLimit,
+ NonlinearResiduals,
+ PatternCaption,
+ Settings,
+ SubsetLimit,
+ Summary,
+ Table,
+)
+from flow360.plugins.report.utils import (
+ Average,
+ DataItem,
+ Delta,
+ Expression,
+ GetAttribute,
+ Grouper,
+ Variable,
+)
+from flow360.plugins.report.uvf_shutter import (
+ BottomCamera,
+ Camera,
+ FrontCamera,
+ FrontLeftBottomCamera,
+ FrontLeftTopCamera,
+ LeftCamera,
+ RearCamera,
+ RearLeftTopCamera,
+ RearRightBottomCamera,
+ TopCamera,
+)
+
+__all__ = [
+ "Average",
+ "BottomCamera",
+ "Camera",
+ "Chart2D",
+ "Chart3D",
+ "DataItem",
+ "Delta",
+ "Expression",
+ "FixedRangeLimit",
+ "FrontCamera",
+ "FrontLeftBottomCamera",
+ "FrontLeftTopCamera",
+ "GetAttribute",
+ "Grouper",
+ "Inputs",
+ "LeftCamera",
+ "ManualLimit",
+ "NonlinearResiduals",
+ "PatternCaption",
+ "RearCamera",
+ "RearLeftTopCamera",
+ "RearRightBottomCamera",
+ "ReportTemplate",
+ "Settings",
+ "SubsetLimit",
+ "Summary",
+ "Table",
+ "TopCamera",
+ "Variable",
+]
diff --git a/flow360/plugins/report/fonts/TWKEverett-Bold.otf b/flow360/plugins/report/fonts/TWKEverett-Bold.otf
new file mode 100644
index 000000000..d66f27fa1
Binary files /dev/null and b/flow360/plugins/report/fonts/TWKEverett-Bold.otf differ
diff --git a/flow360/plugins/report/fonts/TWKEverett-BoldItalic.otf b/flow360/plugins/report/fonts/TWKEverett-BoldItalic.otf
new file mode 100644
index 000000000..4fd2b81ae
Binary files /dev/null and b/flow360/plugins/report/fonts/TWKEverett-BoldItalic.otf differ
diff --git a/flow360/plugins/report/fonts/TWKEverett-Regular.otf b/flow360/plugins/report/fonts/TWKEverett-Regular.otf
new file mode 100644
index 000000000..d2ee751da
Binary files /dev/null and b/flow360/plugins/report/fonts/TWKEverett-Regular.otf differ
diff --git a/flow360/plugins/report/fonts/TWKEverett-RegularItalic.otf b/flow360/plugins/report/fonts/TWKEverett-RegularItalic.otf
new file mode 100644
index 000000000..163880ce2
Binary files /dev/null and b/flow360/plugins/report/fonts/TWKEverett-RegularItalic.otf differ
diff --git a/flow360/plugins/report/img/FC_logo.pdf b/flow360/plugins/report/img/FC_logo.pdf
new file mode 100644
index 000000000..b0062eb7e
Binary files /dev/null and b/flow360/plugins/report/img/FC_logo.pdf differ
diff --git a/flow360/plugins/report/img/Flow360-logo.svg b/flow360/plugins/report/img/Flow360-logo.svg
new file mode 100644
index 000000000..1504a911e
--- /dev/null
+++ b/flow360/plugins/report/img/Flow360-logo.svg
@@ -0,0 +1,157 @@
+
+
+
diff --git a/flow360/plugins/report/img/Flow360_logo.pdf b/flow360/plugins/report/img/Flow360_logo.pdf
new file mode 100644
index 000000000..9a796f502
Binary files /dev/null and b/flow360/plugins/report/img/Flow360_logo.pdf differ
diff --git a/flow360/plugins/report/img/background.pdf b/flow360/plugins/report/img/background.pdf
new file mode 100644
index 000000000..8660b5909
Binary files /dev/null and b/flow360/plugins/report/img/background.pdf differ
diff --git a/flow360/plugins/report/img/colorbar_rainbow_banded_25.jpeg b/flow360/plugins/report/img/colorbar_rainbow_banded_25.jpeg
new file mode 100644
index 000000000..083bb3476
Binary files /dev/null and b/flow360/plugins/report/img/colorbar_rainbow_banded_25.jpeg differ
diff --git a/flow360/plugins/report/img/colorbar_rainbow_banded_30.png b/flow360/plugins/report/img/colorbar_rainbow_banded_30.png
new file mode 100644
index 000000000..00e99896b
Binary files /dev/null and b/flow360/plugins/report/img/colorbar_rainbow_banded_30.png differ
diff --git a/flow360/plugins/report/img/colorbar_rainbow_smooth.png b/flow360/plugins/report/img/colorbar_rainbow_smooth.png
new file mode 100644
index 000000000..34fb1a08c
Binary files /dev/null and b/flow360/plugins/report/img/colorbar_rainbow_smooth.png differ
diff --git a/flow360/plugins/report/img/cover_logo.pdf b/flow360/plugins/report/img/cover_logo.pdf
new file mode 100644
index 000000000..83f8b02c9
Binary files /dev/null and b/flow360/plugins/report/img/cover_logo.pdf differ
diff --git a/flow360/plugins/report/img/flow360.png b/flow360/plugins/report/img/flow360.png
new file mode 100644
index 000000000..bbdf43975
Binary files /dev/null and b/flow360/plugins/report/img/flow360.png differ
diff --git a/flow360/plugins/report/img/flow360_logo_grey.pdf b/flow360/plugins/report/img/flow360_logo_grey.pdf
new file mode 100644
index 000000000..97fa742ab
Binary files /dev/null and b/flow360/plugins/report/img/flow360_logo_grey.pdf differ
diff --git a/flow360/plugins/report/report.py b/flow360/plugins/report/report.py
new file mode 100644
index 000000000..0f597f562
--- /dev/null
+++ b/flow360/plugins/report/report.py
@@ -0,0 +1,365 @@
+"""
+Report generation interface
+"""
+
+import os
+from typing import Annotated, Callable, List, Optional, Set, Union
+
+import pydantic as pd
+
+# this plugin is optional, thus pylatex is not required: TODO add handling of installation of pylatex
+# pylint: disable=import-error
+from pylatex import Section, Subsection
+
+from flow360.cloud.flow360_requests import NewReportRequest
+from flow360.cloud.rest_api import RestApi
+from flow360.component.case import Case
+from flow360.component.interfaces import ReportInterface
+from flow360.component.resource_base import AssetMetaBaseModel, Flow360Resource
+from flow360.component.simulation.framework.base_model import Flow360BaseModel
+from flow360.component.utils import validate_type
+from flow360.plugins.report.report_context import ReportContext
+from flow360.plugins.report.report_doc import ReportDoc
+from flow360.plugins.report.report_items import (
+ Chart,
+ Chart2D,
+ Chart3D,
+ FileNameStr,
+ Inputs,
+ NonlinearResiduals,
+ Settings,
+ Summary,
+ Table,
+)
+from flow360.plugins.report.utils import (
+ Average,
+ DataItem,
+ RequirementItem,
+ get_requirements_from_data_path,
+)
+from flow360.plugins.report.uvf_shutter import ShutterBatchService
+from flow360.version import __solver_version__
+
+
+class Report(Flow360Resource):
+ """
+ Report component for interacting with cloud
+ """
+
+ # pylint: disable=redefined-builtin
+ def __init__(self, id: str):
+ super().__init__(
+ interface=ReportInterface,
+ meta_class=AssetMetaBaseModel,
+ id=id,
+ )
+
+ @classmethod
+ def _from_meta(cls, meta: AssetMetaBaseModel):
+ validate_type(meta, "meta", AssetMetaBaseModel)
+ report = cls(id=meta.id)
+ report._set_meta(meta)
+ return report
+
+ def download(self, file_name, to_file=None, to_folder=".", overwrite: bool = True):
+ """
+ Download the file to the specified location.
+
+ Parameters
+ ----------
+ file_name : str
+ File name to download.
+ to_file : str, optional
+ The name of the file after downloading.
+ to_folder : str, optional
+ The folder where the file will be downloaded.
+ overwrite : bool, optional
+ Flag indicating whether to overwrite existing files.
+ """
+ # pylint: disable=no-member
+ return self._download_file(
+ file_name="results/" + file_name,
+ to_file=to_file,
+ to_folder=to_folder,
+ overwrite=overwrite,
+ )
+
+
+# pylint: disable=too-few-public-methods
+class ReportDraft:
+ """
+ ReportDraft interface
+ """
+
+ _webapi = RestApi(ReportInterface.endpoint)
+
+ # pylint: disable=too-many-arguments
+ @classmethod
+ def submit(
+ cls,
+ name: str,
+ case_ids: List[str],
+ config: str,
+ landscape: bool = True, # pylint: disable=unused-argument
+ solver_version: str = None,
+ ):
+ """
+ Submits a new report request.
+
+ Parameters
+ ----------
+ name : str
+ The name of the report.
+ case_ids : List[str]
+ List of case IDs to include in the report.
+ config : str
+ JSON configuration for report settings.
+ landscape : bool, default=True
+ Whether the report should be landscape-oriented (unused argument).
+ solver_version : str, optional
+ Version of the solver for report generation.
+
+ Returns
+ -------
+ Response
+ The response object from the web API post request.
+ """
+
+ request = NewReportRequest(
+ name=name,
+ resources=[{"type": "Case", "id": id} for id in case_ids],
+ config_json=config,
+ solver_version=solver_version,
+ )
+ resp = cls._webapi.post(json=request.dict())
+ return Report(resp["id"])
+
+
+ReportItemTypes = Annotated[
+ Union[Summary, Inputs, Table, NonlinearResiduals, Chart2D, Chart3D],
+ pd.Field(discriminator="type_name"),
+]
+
+
+class ReportTemplate(Flow360BaseModel):
+ """
+ A model representing a report containing various components such as summaries, inputs, tables,
+ and charts in both 2D and 3D.
+ """
+
+ title: Optional[str] = pd.Field(None, description="Title of report, shown on the first page.")
+ items: List[ReportItemTypes] = pd.Field(
+ description="A list of report items, each of which can be a summary, input data, table, 2D chart, or 3D chart."
+ )
+ include_case_by_case: bool = pd.Field(
+ False,
+ description="Flag indicating whether to include a case-by-case analysis in the report.",
+ )
+ settings: Optional[Settings] = Settings()
+
+ @pd.model_validator(mode="after")
+ def check_fig_names(self):
+ """Validate and assign unique fig_names to report items."""
+ used_fig_names: Set[str] = set()
+ for idx, item in enumerate(self.items):
+ if hasattr(item, "fig_name"):
+ fig_name = getattr(item, "fig_name", None)
+ if not fig_name:
+ class_name = item.__class__.__name__
+ fig_name = f"{class_name}_{idx}"
+ item.fig_name = fig_name
+ else:
+ fig_name = item.fig_name
+ if fig_name in used_fig_names:
+ raise ValueError(
+ f"Duplicate fig_name '{fig_name}' found in item at index {idx}"
+ )
+ used_fig_names.add(fig_name)
+ return self
+
+ # pylint: disable=protected-access
+ def _generate_shutter_screenshots(self, context: ReportContext):
+ service = ShutterBatchService()
+
+ for chart in self.items: # pylint: disable=not-an-iterable
+ if isinstance(chart, Chart3D):
+ for case in context.cases:
+ if not chart._fig_exist(case.id, context.data_storage):
+ req = chart._get_shutter_request(case)
+ service.add_request(req)
+ elif isinstance(chart, Chart2D):
+ chart3d, reference_case = chart.get_background_chart3d(context.cases)
+ if chart3d is not None:
+ if not chart3d._fig_exist(reference_case.id, context.data_storage):
+ req = chart3d._get_shutter_request(reference_case)
+ if req is not None:
+ service.add_request(req)
+
+ service.process_requests(context)
+
+ def _get_baseline_requirements(self):
+ return get_requirements_from_data_path(
+ ["volume_mesh", "surface_mesh", "geometry", "params"]
+ )
+
+ def get_requirements(self) -> List[RequirementItem]:
+ """
+ Collects and returns unique requirements from all items.
+
+ This method iterates over all items, retrieves each item's requirements,
+ and aggregates them into a unique list.
+
+ Returns
+ -------
+ list
+ A list of unique requirements aggregated from all items.
+ """
+
+ requirements = set()
+ for item in self.items: # pylint: disable=not-an-iterable
+ for req in item.get_requirements():
+ requirements.add(req)
+ for req in self._get_baseline_requirements():
+ requirements.add(req)
+ return list(requirements)
+
+ # pylint: disable=unused-argument
+ def create_in_cloud(
+ self,
+ name: str,
+ cases: list[Case],
+ landscape: bool = False,
+ solver_version: str = __solver_version__,
+ ):
+ """
+ Creates a report in the cloud for a specified set of cases.
+
+ Parameters
+ ----------
+ name : str
+ The name of the report to create.
+ cases : list[Case]
+ A list of `Case` instances to include in the report.
+ landscape : bool, default=False
+ Orientation of the report, where `True` represents landscape.
+ solver_version : str, optional
+ Version of the solver for report generation.
+
+ Returns
+ -------
+ Response
+ The response from the Report API submission.
+ """
+
+ return ReportDraft.submit(
+ name=name,
+ case_ids=[case.id for case in cases],
+ config=self.model_dump_json(),
+ solver_version=solver_version,
+ )
+
+ # pylint: disable=too-many-arguments
+ @pd.validate_call(config={"arbitrary_types_allowed": True})
+ def create_pdf(
+ self,
+ filename: FileNameStr,
+ cases: list[Case],
+ landscape: bool = True,
+ data_storage: str = ".",
+ shutter_url: str = None,
+ shutter_access_token: str = None,
+ shutter_screenshot_process_function: Callable = None,
+ process_screenshot_in_parallel: bool = True,
+ ) -> None:
+ """
+ Generates a PDF report for a specified set of cases.
+
+ Parameters
+ ----------
+ filename : str
+ The name of the output PDF file.
+ cases : list[Case]
+ A list of `Case` instances to include in the PDF report.
+ landscape : bool, default=False
+ Orientation of the report, where `True` represents landscape.
+ data_storage : str, default="."
+ Directory where the PDF file will be saved.
+
+ Returns
+ -------
+ None
+ """
+ os.makedirs(data_storage, exist_ok=True)
+ report_doc = ReportDoc(title=self.title, landscape=landscape)
+
+ context = ReportContext(
+ cases=cases,
+ doc=report_doc.doc,
+ data_storage=data_storage,
+ process_screenshot_in_parallel=process_screenshot_in_parallel,
+ shutter_url=shutter_url,
+ shutter_access_token=shutter_access_token,
+ shutter_screenshot_process_function=shutter_screenshot_process_function,
+ )
+ case_context = context.model_copy(
+ update={
+ "section_func": Subsection,
+ "case_by_case": True,
+ }
+ )
+
+ self._generate_shutter_screenshots(context)
+
+ for item in self.items: # pylint: disable=not-an-iterable
+ item.get_doc_item(context, self.settings)
+
+ if self.include_case_by_case is True:
+ with report_doc.doc.create(Section("Appendix", numbering=False)):
+ for case in cases:
+ with report_doc.doc.create(Section(f"Case: {case.id}")):
+ case_context = case_context.model_copy(update={"cases": [case]})
+ for item in self.items: # pylint: disable=not-an-iterable
+ if isinstance(item, Chart) and item.select_indices is not None:
+ selected_case_ids = [cases[i].id for i in item.select_indices]
+ if case.id not in selected_case_ids:
+ continue
+
+ item.get_doc_item(case_context, self.settings)
+
+ report_doc.generate_pdf(os.path.join(data_storage, filename))
+
+
+def get_default_report_summary_template() -> ReportTemplate:
+ """
+ Returns default report template for result summary.
+ """
+ avg = Average(fraction=0.1)
+
+ data = [
+ "volume_mesh/bounding_box/length",
+ "volume_mesh/bounding_box/height",
+ "volume_mesh/bounding_box/width",
+ "params/reference_geometry/moment_length",
+ "params/reference_geometry/area",
+ DataItem(data="surface_forces/totalCL", title="CL", operations=avg),
+ DataItem(data="surface_forces/totalCD", title="CD", operations=avg),
+ DataItem(data="surface_forces/totalCFy", title="CFy", operations=avg),
+ DataItem(data="surface_forces/totalCMx", title="CMx", operations=avg),
+ DataItem(data="surface_forces/totalCMy", title="CMy", operations=avg),
+ DataItem(data="surface_forces/totalCMz", title="CMz", operations=avg),
+ ]
+ headers = [
+ "OAL",
+ "OAH",
+ "OAW",
+ "Reference Length",
+ "Reference Area",
+ "CL",
+ "CD",
+ "CFy",
+ "CMx",
+ "CMy",
+ "CMz",
+ ]
+ table = Table(data=data, section_title="result_summary", headers=headers)
+ return ReportTemplate(items=[table], settings=Settings(dump_table_csv=True))
diff --git a/flow360/plugins/report/report_context.py b/flow360/plugins/report/report_context.py
new file mode 100644
index 000000000..dd558d9bd
--- /dev/null
+++ b/flow360/plugins/report/report_context.py
@@ -0,0 +1,31 @@
+"""
+Module for ReportContext to hold shared configurations between Report and ReportItem
+"""
+
+from typing import Callable, List, Optional, Type, Union
+
+import pydantic as pd
+
+# pylint: disable=import-error
+from pylatex import Document, Section, Subsection
+
+from flow360.component.case import Case
+
+
+class ReportContext(pd.BaseModel):
+ """
+ Context for report data to be used in conjunction with report item.
+ """
+
+ cases: List[Case]
+ doc: Document = Document()
+ section_func: Union[Type[Section], Type[Subsection]] = Section
+ case_by_case: bool = False
+ data_storage: str = "."
+ process_screenshot_in_parallel: bool = True
+
+ shutter_url: Optional[str] = None
+ shutter_access_token: Optional[str] = None
+ shutter_screenshot_process_function: Optional[Callable] = None
+
+ model_config = pd.ConfigDict(arbitrary_types_allowed=True)
diff --git a/flow360/plugins/report/report_doc.py b/flow360/plugins/report/report_doc.py
new file mode 100644
index 000000000..04cba13f7
--- /dev/null
+++ b/flow360/plugins/report/report_doc.py
@@ -0,0 +1,247 @@
+"""
+Report DOC representation
+"""
+
+import os
+import posixpath
+
+# this plugin is optional, thus pylatex is not required: TODO add handling of installation of pylatex
+# pylint: disable=import-error
+from pylatex import (
+ Center,
+ Document,
+ Foot,
+ HugeText,
+ LargeText,
+ MediumText,
+ MiniPage,
+ NewPage,
+ NoEscape,
+ Package,
+ PageStyle,
+ StandAloneGraphic,
+)
+from pylatex.utils import bold, escape_latex
+
+from flow360.log import log
+from flow360.plugins.report.utils import detect_latex_compiler, font_definition
+
+
+class ReportDoc:
+ """
+ ReportDoc
+ """
+
+ def __init__(self, title, landscape=True) -> None:
+ self.compiler, self.compiler_args = detect_latex_compiler()
+
+ self.use_xelatex = self.compiler == "xelatex"
+ if self.use_xelatex:
+ log.info("Using 'xelatex' as the LaTeX compiler.") # preferred for styling
+ else:
+ log.warning(f"Using '{self.compiler}' as the LaTeX compiler.")
+ log.warning(
+ "Warning: 'xelatex' is not available. Some font-related features may be disabled."
+ )
+
+ self._doc = Document(document_options=["10pt"])
+ self._define_preamble(self._doc, landscape)
+ self._create_custom_page_style(self._doc)
+ self._title_page_style(self._doc)
+ self._make_title(self._doc, title)
+ self.doc.change_document_style("customstyle")
+
+ @property
+ def doc(self) -> Document:
+ """
+ Get current pylatex document
+
+ Returns
+ -------
+ Document
+ Current pylatex document
+ """
+ return self._doc
+
+ def _define_preamble(self, doc, landscape):
+ # Package info
+ geometry_options = ["a4paper", "margin=0.5in", "bottom=0.7in", "includefoot"]
+ if landscape:
+ geometry_options.append("landscape")
+
+ packages = [
+ Package("float"),
+ Package("caption"),
+ Package("graphicx"),
+ Package("placeins"),
+ Package("xcolor", options="table"),
+ Package("geometry", options=geometry_options),
+ Package("tikz"),
+ Package("colortbl"),
+ Package("array"),
+ NoEscape(r"\usepackage{eso-pic}"),
+ Package("fancyhdr"),
+ ]
+ if self.use_xelatex:
+ packages.append(Package("fontspec"))
+
+ for package in packages:
+ doc.packages.append(package)
+
+ doc.preamble.append(NoEscape(r"\definecolor{customgray}{HTML}{E0E2E7}"))
+ doc.preamble.append(NoEscape(r"\definecolor{labelgray}{HTML}{F4F5F7}"))
+
+ doc.preamble.append(
+ NoEscape(r"\DeclareCaptionLabelFormat{graybox}{\colorbox{labelgray}{}}")
+ )
+ doc.preamble.append(
+ NoEscape(
+ r"\captionsetup[figure]{position=bottom, font=large, labelformat=graybox, "
+ r"labelsep=none, justification=raggedright, singlelinecheck=false}"
+ )
+ )
+ doc.preamble.append(
+ NoEscape(r"\captionsetup[subfigure]{labelformat=empty, justification=centering}")
+ )
+
+ if self.use_xelatex:
+ doc.preamble.append(NoEscape(font_definition))
+
+ self._table_settings(doc)
+ self._background(doc)
+
+ def _table_settings(self, doc):
+ doc.preamble.append(NoEscape(r"\setlength{\tabcolsep}{12pt}"))
+ doc.preamble.append(NoEscape(r"\renewcommand{\arraystretch}{2}"))
+ doc.append(NoEscape(r"\arrayrulecolor{customgray}"))
+ doc.preamble.append(
+ NoEscape(
+ r"""
+ \newcolumntype{C}{>{\columncolor{white}}c}
+ """
+ )
+ )
+
+ def _background(self, doc):
+ background_file = posixpath.join(
+ os.path.dirname(__file__), "img", "background.pdf"
+ ).replace("\\", "/")
+ if not os.path.isfile(background_file):
+ raise FileNotFoundError(f"Background image not found at path: {background_file}")
+
+ background_latex = (
+ r"""
+ \AddToShipoutPictureBG{
+ \begin{tikzpicture}[remember picture, overlay]
+ \node[anchor=north east] at (current page.north east) {
+ \includegraphics[width=\textwidth]{"""
+ + background_file
+ + r"""}
+ };
+ \end{tikzpicture}
+ }
+ """
+ )
+ doc.preamble.append(NoEscape(background_latex))
+
+ def _create_custom_page_style(self, doc) -> PageStyle:
+ page_style = PageStyle("customstyle")
+ padding = r"\vspace{10pt}"
+
+ doc.preamble.append(NoEscape(r"\setlength{\footskip}{40pt}"))
+
+ with page_style.create(Foot("C")) as footer:
+ footer.append(NoEscape(r"\textcolor{customgray}{\rule{\textwidth}{0.5pt}}"))
+ footer.append(NoEscape(r"\\"))
+ footer.append(NoEscape(padding))
+ with footer.create(
+ MiniPage(width=NoEscape(r"\textwidth"), align="c")
+ ) as footer_content:
+ with footer_content.create(
+ MiniPage(width=NoEscape(r"0.33\textwidth"), align="l")
+ ) as url:
+ url.append(NoEscape(r"\hspace{1em}"))
+ url.append(NoEscape(r"FLEXCOMPUTE.COM"))
+ url.append(NoEscape(r"\hspace{1em}"))
+
+ with footer_content.create(
+ MiniPage(width=NoEscape(r"0.33\textwidth"), align="c")
+ ) as logo1:
+ logo1.append(
+ StandAloneGraphic(
+ image_options="height=18pt",
+ filename=posixpath.join(
+ os.path.dirname(__file__), "img", "flow360_logo_grey.pdf"
+ ).replace("\\", "/"),
+ )
+ )
+
+ with footer_content.create(
+ MiniPage(width=NoEscape(r"0.33\textwidth"), align="r")
+ ) as page_num:
+ page_num.append(NoEscape(r"\thepage"))
+ footer.append(NoEscape(padding))
+ doc.preamble.append(page_style)
+
+ def _title_page_style(self, doc) -> PageStyle:
+ page_style = PageStyle("titlestyle")
+ with page_style.create(Foot("C")) as footer:
+ with footer.create(
+ MiniPage(width=NoEscape(r"\textwidth"), align="c")
+ ) as footer_content:
+ footer_content.append(
+ StandAloneGraphic(
+ image_options="height=25pt",
+ filename=posixpath.join(
+ os.path.dirname(__file__), "img", "cover_logo.pdf"
+ ).replace("\\", "/"),
+ )
+ )
+ doc.preamble.append(page_style)
+
+ def _make_title(self, doc, title: str = None):
+ # pylint: disable=invalid-name
+ NewLine = NoEscape(r"\\") # pylatex NewLine() is causing problems with centering
+ doc.append(NoEscape(r"\thispagestyle{titlestyle}"))
+
+ doc.append(NoEscape(r"\vspace*{\fill}"))
+
+ with doc.create(Center()):
+ doc.append(HugeText(bold("Flow360 Report")))
+ doc.append(NewLine)
+ doc.append(NoEscape(r"\vspace{1cm}"))
+
+ if title is not None:
+ doc.append(LargeText(NoEscape(r"\textcolor{gray}{" + escape_latex(title) + "}")))
+ doc.append(NewLine)
+ doc.append(NoEscape(r"\vspace{2cm}"))
+
+ doc.append(MediumText(NoEscape(r"\textcolor{gray}{\today}")))
+ doc.append(NewLine)
+
+ doc.append(NoEscape(r"\vspace*{\fill}"))
+ doc.append(NewPage())
+
+ def generate_pdf(self, filename: str):
+ """
+ Generates PDF from ReportTemplate and Cases
+
+ Parameters
+ ----------
+ filename : str
+ Filename for PDF
+ """
+ pdf_ext = ".pdf"
+ name_without_ext, file_ext = os.path.splitext(filename)
+ if file_ext.lower() != pdf_ext:
+ name_without_ext = filename
+ filename = name_without_ext + pdf_ext
+
+ self.doc.generate_pdf(
+ name_without_ext,
+ compiler=self.compiler,
+ compiler_args=self.compiler_args,
+ clean_tex=False,
+ )
+
+ log.info(f"PDF '{filename}' generated successfully using '{self.compiler}'.")
diff --git a/flow360/plugins/report/report_items.py b/flow360/plugins/report/report_items.py
new file mode 100644
index 000000000..b87e533b9
--- /dev/null
+++ b/flow360/plugins/report/report_items.py
@@ -0,0 +1,2184 @@
+"""
+Module containg detailed report items
+"""
+
+# pylint: disable=too-many-lines
+from __future__ import annotations
+
+import os
+from abc import ABCMeta, abstractmethod
+from collections.abc import Iterable
+from typing import Annotated, List, Literal, Optional, Tuple, Union
+
+import numpy as np
+import pydantic as pd
+import unyt
+from pydantic import (
+ BaseModel,
+ Field,
+ NonNegativeInt,
+ StringConstraints,
+ field_validator,
+ model_validator,
+)
+
+# this plugin is optional, thus pylatex is not required: TODO add handling of installation of pylatex
+# pylint: disable=import-error
+from pylatex import Command, Document, Figure, NewPage, NoEscape, SubFigure
+
+# pylint: disable=import-error
+from pylatex.utils import bold, escape_latex
+
+from flow360.component.case import Case
+from flow360.component.simulation.framework.base_model import Flow360BaseModel
+from flow360.component.simulation.outputs.output_fields import (
+ IsoSurfaceFieldNames,
+ SurfaceFieldNames,
+ get_unit_for_field,
+)
+from flow360.component.simulation.simulation_params import SimulationParams
+from flow360.component.simulation.time_stepping.time_stepping import Unsteady
+from flow360.component.simulation.unit_system import (
+ DimensionedTypes,
+ is_flow360_unit,
+ unyt_quantity,
+)
+from flow360.exceptions import Flow360ValidationError
+from flow360.log import log
+from flow360.plugins.report.report_context import ReportContext
+from flow360.plugins.report.utils import (
+ DataItem,
+ Delta,
+ Grouper,
+ OperationTypes,
+ RequirementItem,
+ Tabulary,
+ data_from_path,
+ downsample_image_to_relative_width,
+ generate_colorbar_from_image,
+ get_requirements_from_data_path,
+ path_variable_name,
+ split_path,
+)
+from flow360.plugins.report.uvf_shutter import (
+ ActionPayload,
+ BottomCamera,
+ Camera,
+ FocusPayload,
+ FrontCamera,
+ FrontLeftBottomCamera,
+ FrontLeftTopCamera,
+ LeftCamera,
+ RearCamera,
+ RearLeftTopCamera,
+ RearRightBottomCamera,
+ ResetFieldPayload,
+ Resource,
+ Scene,
+ ScenesData,
+ SetCameraPayload,
+ SetFieldPayload,
+ SetLICPayload,
+ SetObjectVisibilityPayload,
+ Shutter,
+ ShutterObjectTypes,
+ TakeScreenshotPayload,
+ TopCamera,
+ make_shutter_context,
+)
+
+here = os.path.dirname(os.path.abspath(__file__))
+
+
+FileNameStr = Annotated[str, StringConstraints(pattern=r"^[a-zA-Z0-9._-]+$")]
+
+FIG_ASPECT_RATIO = 16 / 9
+
+
+class Settings(Flow360BaseModel):
+ """
+ Settings for controlling output properties.
+ """
+
+ # pylint: disable=fixme
+ # TODO: Create a setting class for each type of report items.
+ dpi: Optional[pd.PositiveInt] = Field(
+ 300,
+ description="The resolution in dots per inch (DPI) for generated images in report (A4 assumed).",
+ )
+ dump_table_csv: Optional[pd.StrictBool] = Field(
+ False, description="If ``True``, :class:``Table`` data will be dumped into a csv file."
+ )
+
+
+class ReportItem(Flow360BaseModel):
+ """
+ Base class for for all report items.
+ """
+
+ _requirements: List[str] = None
+
+ # pylint: disable=unused-argument,too-many-arguments
+ def get_doc_item(self, context: ReportContext, settings: Settings = None) -> None:
+ """
+ returns doc item for report item
+ """
+ with context.doc.create(context.section_func(self.__class__.__name__)):
+ context.doc.append(f"this is {self.__class__.__name__}")
+
+ def get_requirements(self):
+ """
+ Returns requirements for this item
+ """
+ if self._requirements is not None:
+ return self._requirements
+ raise NotImplementedError(
+ f"Internal error: get_requirements() not implemented for {self.__class__.__name__}"
+ )
+
+
+class Summary(ReportItem):
+ """
+ Represents a summary item in a report.
+ """
+
+ text: Optional[str] = Field(None, description="The main content or text of the summary.")
+ type_name: Literal["Summary"] = Field("Summary", frozen=True)
+ _requirements: List[str] = []
+
+ # pylint: disable=too-many-arguments
+ def get_doc_item(self, context: ReportContext, settings: Settings = None) -> None:
+ """
+ Returns doc item for report item.
+ """
+ section = context.section_func("Summary")
+ context.doc.append(section)
+ if self.text is not None:
+ context.doc.append(f"{self.text}\n")
+ Table(data=["name", "id"], section_title=None, headers=["Case Name", "Id"]).get_doc_item(
+ context
+ )
+
+
+class Inputs(ReportItem):
+ """
+ Inputs is a wrapper for a specific Table setup that details key inputs from the simulation.
+ """
+
+ type_name: Literal["Inputs"] = Field("Inputs", frozen=True)
+ _requirements: List[RequirementItem] = [RequirementItem.from_data_key(data_key="params")]
+
+ # pylint: disable=too-many-arguments
+ def get_doc_item(self, context: ReportContext, settings: Settings = None) -> None:
+ """
+ Returns doc item for inputs.
+ """
+ Table(
+ data=[
+ "params/operating_condition/velocity_magnitude",
+ "params/time_stepping/type_name",
+ ],
+ section_title="Inputs",
+ headers=[
+ "Velocity",
+ "Time stepping",
+ ],
+ ).get_doc_item(context)
+
+
+def human_readable_formatter(value):
+ """
+ Custom formatter that uses k/M suffixes with a human-readable style.
+ For large numbers, it attempts to show a concise representation without
+ scientific notation:
+
+ - For millions, it will show something like 225M (no decimals if >100),
+ 22.5M (one decimal if between 10 and 100), or 2.3M (two decimals if <10).
+ - For thousands, it follows a similar pattern for k.
+ - For numbers < 1000, it shows up to two decimal places if needed.
+ """
+ if not isinstance(value, (int, float)):
+ return str(value)
+
+ abs_value = abs(value)
+
+ def strip_trailing_zeros(s):
+ if "." in s:
+ s = s.rstrip("0").rstrip(".")
+ return s
+
+ if abs_value >= 1e6:
+ scale = 1e6
+ symbol = "M"
+ elif abs_value >= 1e3:
+ scale = 1e3
+ symbol = "k"
+ else:
+ return str(value)
+
+ scaled = value / scale
+ if abs(scaled) < 10:
+ # e.g., 2.3M
+ formatted = f"{scaled:.1f}"
+ elif abs(scaled) < 100:
+ # e.g., 23M
+ formatted = f"{scaled:.0f}"
+ else:
+ # e.g., 225M
+ formatted = f"{scaled:.0f}"
+ formatted = strip_trailing_zeros(formatted)
+ return formatted + symbol
+
+
+_SPECIAL_FORMATING_MAP = {"volume_mesh/stats/n_nodes": human_readable_formatter}
+
+
+class Table(ReportItem):
+ """
+ Represents a table within a report, with configurable data and headers.
+ """
+
+ data: List[Union[str, Delta, DataItem]] = Field(
+ description="A list of table data entries, which can be either strings or `Delta` objects."
+ )
+ section_title: Union[str, None] = Field(description="The title of the table section.")
+ headers: Union[list[str], None] = Field(
+ None, description="List of column headers for the table, default is None."
+ )
+ type_name: Literal["Table"] = Field("Table", frozen=True)
+ select_indices: Optional[List[NonNegativeInt]] = Field(
+ None, description="Specific indices to select for the chart."
+ )
+ formatter: Optional[Union[str, List[Union[str, None]]]] = Field(
+ None,
+ description='Formatter can be a single str (e.g. ".4g") or a list of str of the same length as ``data``',
+ )
+
+ @model_validator(mode="before")
+ @classmethod
+ def _process_formatter(cls, values):
+ if not isinstance(values, dict):
+ return values
+ data = values.get("data")
+ if data is None:
+ return values
+
+ formatter = values.get("formatter")
+
+ if isinstance(formatter, str) or formatter is None:
+ formatter = [formatter for _ in data]
+
+ if len(formatter) != len(data):
+ raise ValueError("List of formatters must match the length of data, or ")
+ values["formatter"] = formatter
+
+ return values
+
+ @model_validator(mode="after")
+ def _check_custom_heading_count(self) -> None:
+ if self.headers is not None:
+ if len(self.data) != len(self.headers):
+ raise ValueError(
+ "Supplied `headers` must be the same length as `data`: "
+ f"{len(self.headers)} instead of {len(self.data)}"
+ )
+ return self
+
+ # pylint: disable=unsupported-assignment-operation
+ def _get_formatters(self):
+ formatters = self.formatter
+ for i, (fmt, data) in enumerate(zip(formatters, self.data)):
+ if fmt is None:
+ if isinstance(data, str) and data in _SPECIAL_FORMATING_MAP:
+ formatters[i] = _SPECIAL_FORMATING_MAP[data]
+ else:
+ formatters[i] = ".5g"
+
+ def make_callable(fmt):
+ if callable(fmt):
+ return fmt
+ if fmt == "bool":
+ return lambda x: f"{bool(x)}"
+ return lambda x, ff=fmt: f"{x:{ff}}"
+
+ formatters = [make_callable(f) for f in formatters] # pylint: disable=not-an-iterable
+ return formatters
+
+ def get_requirements(self):
+ """
+ Returns requirements for this item
+ """
+ return get_requirements_from_data_path(self.data)
+
+ def calculate_table_data(self, context: ReportContext) -> Tuple[List[str], List[List]]:
+ """
+ Calculate raw table data (headers + rows) without formatting.
+
+ Returns:
+ (headers, rows)
+ headers: list of column names (strings)
+ rows: list of rows, each row is a list of cell values
+ """
+
+ headers = ["Case No."]
+ if self.headers is None:
+ for path in self.data:
+ if isinstance(path, (Delta, DataItem)):
+ field_label = str(path)
+ else:
+ field_label = split_path(path)[-1]
+ headers.append(field_label)
+ else:
+ headers.extend(self.headers)
+
+ rows = []
+ for idx, case in enumerate(context.cases):
+ # pylint: disable=unsupported-membership-test
+ if self.select_indices and idx not in self.select_indices:
+ continue
+ raw_values = []
+ for path in self.data:
+ value = data_from_path(
+ case,
+ path,
+ context.cases,
+ case_by_case=context.case_by_case,
+ )
+ raw_values.append(value)
+
+ row_values = [str(idx + 1)] + raw_values
+ rows.append(row_values)
+
+ return (headers, rows)
+
+ def to_dataframe(self, context: ReportContext):
+ """
+ Convert calculated data into a Pandas DataFrame for unit-testing
+ or external usage.
+ """
+ from pandas import DataFrame # pylint: disable=import-outside-toplevel
+
+ headers, rows = self.calculate_table_data(context)
+ df = DataFrame(rows, columns=headers)
+ return df
+
+ def get_doc_item(self, context: ReportContext, settings: Settings = None) -> None:
+ """
+ Returns a LaTeX doc item (Tabulary) for the table,
+ using previously calculated data.
+ """
+ if self.section_title is not None:
+ section = context.section_func(self.section_title)
+ context.doc.append(section)
+
+ headers, rows = self.calculate_table_data(context)
+
+ num_columns = len(headers)
+ with context.doc.create(Tabulary("|C" * num_columns + "|", width=num_columns)) as table:
+ table.add_hline()
+
+ table.append(Command("rowcolor", "labelgray"))
+ table.add_row(headers)
+ table.add_hline()
+
+ formatters = self._get_formatters()
+ for row_values in rows:
+
+ formatted = [row_values[0]]
+ for i, val in enumerate(row_values[1:], 1):
+ fmt = formatters[i - 1]
+ if isinstance(val, (int, float)):
+ formatted.append(fmt(val))
+ else:
+ formatted.append(str(val))
+
+ table.add_row(formatted)
+ table.add_hline()
+
+ if settings is not None and settings.dump_table_csv:
+ df = self.to_dataframe(context=context)
+ df.to_csv(f"{self.section_title}.csv", index=False)
+
+
+class PatternCaption(Flow360BaseModel):
+ """
+ Class for setting up chart caption.
+ """
+
+ pattern: str = Field(
+ default="[case.name]",
+ description="The caption pattern containing placeholders like [case.name] and [case.id]."
+ + " These placeholders will be replaced with the actual case name and ID when resolving the caption."
+ + ' For example, "The case is [case.name] with ID [case.id]". Defaults to ``"[case.name]"``.',
+ )
+ type_name: Literal["PatternCaption"] = Field("PatternCaption", frozen=True)
+
+ # pylint: disable=no-member
+ def resolve(self, case: "Case") -> str:
+ """
+ Resolves the pattern to the actual caption string using the provided case object.
+
+ Parameters
+ ----------
+ case : Case
+ The case object containing `name` and `id` attributes.
+
+ Returns
+ -------
+ str
+ The resolved caption string with placeholders replaced by actual values.
+
+ Examples
+ --------
+ >>> caption = PatternCaption(pattern="The case is [case.name] with ID [case.id]")
+ >>> case = Case(name="Example", id=123)
+ >>> caption.resolve(case)
+ 'The case is Example with ID 123'
+ """
+ caption = self.pattern.replace("[case.name]", case.name)
+ caption = caption.replace("[case.id]", str(case.id))
+ return caption
+
+
+class Chart(ReportItem):
+ """
+ Represents a chart in a report, with options for layout and display properties.
+ """
+
+ section_title: Optional[str] = Field(None, description="The title of the chart section.")
+ fig_name: Optional[FileNameStr] = Field(
+ None,
+ description="Name of the figure file or identifier for the chart (). Only '^[a-zA-Z0-9._-]+$' allowed.",
+ )
+ fig_size: float = Field(
+ 0.7, description="Relative size of the figure as a fraction of text width."
+ )
+ items_in_row: Union[int, None] = Field(
+ None, description="Number of items to display in a row within the chart section."
+ )
+ select_indices: Optional[List[NonNegativeInt]] = Field(
+ None, description="Specific indices to select for the chart."
+ )
+ separate_plots: Optional[bool] = Field(
+ None, description="If True, display as multiple plots; otherwise single plot."
+ )
+ force_new_page: bool = Field(
+ False, description="If True, starts the chart on a new page in the report."
+ )
+ caption: Optional[Union[str, List[str], PatternCaption]] = Field(
+ "", description="Caption to be shown for figures."
+ )
+
+ @model_validator(mode="after")
+ def _check_chart_args(self) -> None:
+ if self.items_in_row is not None and self.items_in_row != -1:
+ if self.items_in_row < 1:
+ raise ValueError(
+ "`Items_in_row` should be greater than 1. Use -1 to include all "
+ "cases on a single row. Use `None` to disable the argument."
+ )
+ if self.items_in_row is not None:
+ if self.separate_plots is False:
+ raise ValueError(
+ "`Items_in_row` and `separate_plots=False` cannot be used together."
+ )
+ if self.separate_plots is None:
+ self.separate_plots = True
+ if isinstance(self.caption, List):
+ raise ValueError("List of captions and items_in_row cannot be used together.")
+ if isinstance(self.caption, PatternCaption):
+ raise ValueError("PatternCaption and items_in_row cannot be used together.")
+ return self
+
+ def _check_caption_validity(self, cases):
+ if isinstance(self.caption, List):
+ if len(self.caption) != len(cases):
+ raise ValueError("Caption list is not the same length as the list of cases.")
+
+ def _handle_title(self, doc, section_func):
+ if self.section_title is not None:
+ section = section_func(self.section_title)
+ doc.append(section)
+
+ def _handle_new_page(self, doc):
+ if self.force_new_page:
+ doc.append(NewPage())
+
+ def _handle_grid_input(self, cases):
+ # Change items in row to be the number of cases if higher number is supplied
+ if self.items_in_row is not None:
+ if self.items_in_row > len(cases) or self.items_in_row == -1:
+ self.items_in_row = len(cases)
+
+ def _filter_input_cases(self, cases, case_by_case):
+ # Reduce the case list by the selected IDs
+ # pylint: disable=not-an-iterable
+ if case_by_case is False:
+ cases = (
+ [cases[i] for i in self.select_indices]
+ if self.select_indices is not None
+ else cases
+ )
+
+ return cases
+
+ def _fig_exist(self, resource_id, data_storage="."):
+ img_folder = os.path.join(data_storage, resource_id)
+ img_name = self.fig_name + ".png"
+ img_full_path = os.path.join(img_folder, img_name)
+ if os.path.exists(img_full_path):
+ log.debug(f"File: {img_name=} exists in cache, reusing.")
+ return True
+ return False
+
+ def _downsample_png(self, img: str, relative_width=1, dpi=None):
+ if dpi is not None and img.lower().endswith(".png"):
+ downsampled_img = os.path.splitext(img)[0] + f"_dpi{dpi}.png"
+ downsample_image_to_relative_width(
+ img, downsampled_img, relative_width=relative_width, dpi=dpi
+ )
+ img = downsampled_img
+ return img
+
+ # pylint: disable=too-many-arguments
+ def _add_figure(self, doc: Document, file_name, caption, legend_filename=None, dpi=None):
+
+ file_name = self._downsample_png(file_name, dpi=dpi)
+
+ if legend_filename is None:
+ fig = Figure(position="!ht")
+ fig.add_image(file_name, width=NoEscape(rf"{self.fig_size}\textwidth"))
+ fig.add_caption(caption)
+ doc.append(fig)
+ else:
+ doc.append(NoEscape(r"\begin{figure}[!ht]"))
+
+ sub_fig = SubFigure(position="t", width=NoEscape(r"\textwidth"))
+ sub_fig.add_image(
+ file_name,
+ width=NoEscape(rf"{self.fig_size}\textwidth"),
+ placement=NoEscape(r"\centering"),
+ )
+ doc.append(sub_fig)
+ doc.append(NoEscape(r"\\"))
+ fig = self._add_legend(legend_filename=legend_filename)
+ doc.append(fig)
+
+ doc.append(NoEscape(r"\caption{" + escape_latex(caption) + "}"))
+ doc.append(NoEscape(r"\end{figure}"))
+
+ def _add_legend(self, legend_filename: str, minipage_width=1, legend_width=0.45):
+ sub_fig = SubFigure(position="t", width=NoEscape(rf"{minipage_width}\textwidth"))
+ sub_fig.add_image(
+ filename=legend_filename,
+ width=NoEscape(rf"{legend_width}\textwidth"),
+ placement=NoEscape(r"\centering"),
+ )
+ return sub_fig
+
+ # pylint: disable=too-many-arguments,too-many-locals
+ def _add_row_figure(
+ self,
+ doc: Document,
+ img_list: list[str],
+ fig_caption: str,
+ sub_fig_captions: List[str] = None,
+ legend_filename=None,
+ dpi=None,
+ ):
+ """
+ Build a figure from SubFigures which displays images in rows
+
+ Using Doc manually here may be unnecessary - but it does allow for more control
+ """
+
+ # Smaller than 1 to avoid overflowing
+ minipage_size = 0.86 / self.items_in_row if self.items_in_row != 1 else 0.8
+
+ if sub_fig_captions is None:
+ sub_fig_captions = range(1, len(img_list) + 1)
+
+ figures = []
+ for img, caption in zip(img_list, sub_fig_captions):
+ sub_fig = SubFigure(position="t", width=NoEscape(rf"{minipage_size}\textwidth"))
+
+ img = self._downsample_png(img, relative_width=minipage_size, dpi=dpi)
+ sub_fig.add_image(
+ filename=img, width=NoEscape(r"\textwidth"), placement=NoEscape(r"\centering")
+ )
+
+ # Stop caption for single subfigures - happens when include_case_by_case
+ if self.items_in_row != 1 and caption is not None:
+ sub_fig.add_caption(caption)
+ figures.append(sub_fig)
+
+ if legend_filename is not None:
+ img_list.append(legend_filename)
+ legend_width = 0.9 if self.items_in_row != 1 else 0.45
+ sub_fig = self._add_legend(
+ legend_filename=legend_filename,
+ minipage_width=minipage_size,
+ legend_width=legend_width,
+ )
+ figures.append(sub_fig)
+
+ # Build list of indices to combine into rows
+ indices = list(range(len(img_list)))
+ idx_list = [
+ indices[i : i + self.items_in_row] for i in range(0, len(indices), self.items_in_row)
+ ]
+
+ for row_idx in idx_list:
+ doc.append(NoEscape(r"\begin{figure}[h!]"))
+ for idx in row_idx:
+ doc.append(figures[idx])
+ doc.append(NoEscape(r"\hfill"))
+ doc.append(NoEscape(r"\\"))
+ if row_idx == idx_list[-1]:
+ doc.append(NoEscape(r"\caption{" + escape_latex(fig_caption) + "}"))
+ doc.append(NoEscape(r"\end{figure}"))
+
+
+# pylint: disable=no-member
+class PlotModel(BaseModel):
+ """
+ PlotModel that stores series data and configuration required to render
+ a matplotlib ``Figure``.
+ """
+
+ x_data: Union[List[float], List[List[float]]] = Field(
+ description="Values for the primary x-axis. Accepts a single list (one series)"
+ + " or a list of lists (multiple series)."
+ )
+ y_data: Union[List[float], List[List[float]]] = Field(
+ description="Values for the primary y-axis, matching the shape of ``x_data``."
+ )
+ x_label: str = Field(description="Text label for the primary x-axis.")
+ y_label: str = Field(description="Text label for the primary y-axis.")
+ secondary_x_data: Optional[Union[List[float], List[List[float]]]] = Field(
+ None, description="Alternate x-axis values used when plotting against a secondary axis."
+ )
+ secondary_x_label: Optional[str] = Field(
+ None,
+ description="Label for the secondary x-axis (shown only if ``secondary_x_data`` is set).",
+ )
+ legend: Optional[List[str]] = Field(
+ None,
+ description="Series names to appear in the plot legend. The length should equal the number of plotted series.",
+ )
+ is_log: bool = Field(
+ False, description="If ``True``, the y-axis is drawn on a logarithmic scale."
+ )
+ style: str = Field(
+ "-",
+ description='Matplotlib style or format string (e.g. ``"-"`` or ``"o--"``) applied to all data series.',
+ )
+ backgroung_png: Optional[str] = Field(
+ None, description="Path to a PNG file placed behind the plot as a background image."
+ )
+ xlim: Optional[Tuple[float, float]] = Field(
+ None, description="Axis limits for the x-axis as ``(xmin, xmax)``."
+ )
+ ylim: Optional[Tuple[float, float]] = Field(
+ None, description="Axis limits for the y-axis as ``(ymin, ymax)``."
+ )
+ grid: Optional[bool] = Field(
+ True, description="Show grid lines if ``True``, hide them if ``False``."
+ )
+
+ @field_validator("x_data", "y_data", mode="before")
+ @classmethod
+ def _ensure_y_data_is_list_of_lists(cls, v):
+ if isinstance(v, list):
+ if all(isinstance(item, list) for item in v):
+ return v
+ return [v]
+ raise ValueError("x_data/y_data must be a list")
+
+ @field_validator("secondary_x_data", mode="before")
+ @classmethod
+ def _ensure_secondary_x_data_identical(cls, v):
+ if isinstance(v, list):
+ if all((item == v[0]) for item in v):
+ return v
+ raise ValueError("Every series in secondary_x_data must be the same.")
+ return v
+
+ @model_validator(mode="after")
+ def _check_lengths(self):
+ if len(self.x_data) == 1:
+ self.x_data = [self.x_data[0] for _ in self.y_data]
+ if len(self.x_data) != len(self.y_data):
+ raise ValueError(
+ "Number of x_data series but be one or equal to number of y_data series."
+ )
+ for idx, (x_series, y_series) in enumerate(zip(self.x_data, self.y_data)):
+ if len(x_series) != len(y_series):
+ raise ValueError(
+ f"Length of y_data series at index {idx} ({len(y_series)})"
+ + f" does not match length of x_data ({len(x_series)})"
+ )
+ if self.legend is not None:
+ if len(self.legend) != len(self.y_data):
+ raise ValueError(
+ f"Length of legend ({len(self.legend)}) must match number of y_data series ({len(self.y_data)})"
+ )
+
+ return self
+
+ @model_validator(mode="after")
+ def _check_x_label_use(self):
+ if (self.secondary_x_data is None) and (self.secondary_x_label is not None):
+ raise ValueError(
+ "Cannot define secondary x label when there is no data on secondary x axis."
+ )
+ return self
+
+ @property
+ def x_data_as_np(self):
+ """
+ returns X data as list of numpy arrays
+ """
+ return [np.array(x_series) for x_series in self.x_data]
+
+ # pylint: disable=not-an-iterable
+ @property
+ def secondary_x_data_as_np(self):
+ """
+ returns secondary X data as list of numpy arrays
+ """
+ if self.secondary_x_data is not None:
+ return [np.array(x_series) for x_series in self.secondary_x_data]
+ return None
+
+ @property
+ def y_data_as_np(self):
+ """
+ returns Y data as list of numpy arrays
+ """
+ return [np.array(y_series) for y_series in self.y_data]
+
+ def _get_extent_for_background(self):
+ """
+ calculates good extend for background image
+ """
+ extent = [
+ np.min(self.x_data_as_np[0]),
+ np.max(self.x_data_as_np[0]),
+ np.min(np.concatenate(self.y_data_as_np)),
+ np.max(np.concatenate(self.y_data_as_np)),
+ ]
+ y_extent = extent[3] - extent[2]
+ extent[2] -= y_extent * 0.1
+ extent[3] += y_extent * 0.1
+ return extent
+
+ def _calcuate_secondary_labels(self):
+ locations = []
+ labels = []
+
+ curr_secondary = None
+
+ for x_entry, sec_x_entry in zip(self.x_data_as_np[0], self.secondary_x_data_as_np[0]):
+ if sec_x_entry != curr_secondary:
+ locations.append(x_entry)
+ labels.append(f"{sec_x_entry:g}")
+ curr_secondary = sec_x_entry
+
+ return locations, labels
+
+ # pylint: disable=too-many-locals
+ def get_plot(self):
+ """
+ Generates a matplotlib plot based on the provided x and y data.
+
+ Returns
+ -------
+ matplotlib.figure.Figure
+ A matplotlib Figure object containing the generated plot.
+
+ Notes
+ -----
+ - If a background image is provided (`self.backgroung_png`), it is overlaid on the plot
+ with adjusted transparency and aspect ratio.
+ - The function supports both regular and logarithmic y-axis scales based on the
+ `self.is_log` attribute.
+ - Data series from `self.x_data` and `self.y_data` are plotted using the specified
+ style (`self.style`), and legends are included if provided (`self.legend`).
+
+ Examples
+ --------
+ >>> plot_model = PlotModel(
+ ... x_data=[[1, 2, 3], [1, 2, 3]],
+ ... y_data=[[4, 5, 6], [7, 8, 9]],
+ ... x_label="Time (s)",
+ ... y_label="Value",
+ ... legend=["Series A", "Series B"],
+ ... is_log=False,
+ ... style="o-"
+ ... )
+ >>> fig = plot_model.get_plot()
+ >>> fig.show()
+ """
+
+ import matplotlib.image as mpimg # pylint: disable=import-outside-toplevel
+ import matplotlib.pyplot as plt # pylint: disable=import-outside-toplevel
+ from matplotlib.ticker import ( # pylint: disable=import-outside-toplevel
+ FuncFormatter,
+ )
+
+ figsize = 8
+ fig, ax = plt.subplots(figsize=(figsize, figsize / FIG_ASPECT_RATIO))
+ num_series = len(self.y_data)
+
+ if self.backgroung_png is not None:
+ background_img = mpimg.imread(self.backgroung_png)
+ extent = self._get_extent_for_background()
+ ax.imshow(background_img, extent=extent, aspect="auto", alpha=0.7, zorder=0)
+ ax.grid(True)
+
+ for idx in range(num_series):
+ x_series = self.x_data_as_np[idx]
+ y_series = self.y_data_as_np[idx]
+ # pylint: disable=unsubscriptable-object
+ label = (
+ self.legend[idx] if self.legend and idx < len(self.legend) else f"Series {idx+1}"
+ )
+
+ if self.grid:
+ ax.grid(True)
+ if self.is_log:
+ ax.semilogy(x_series, y_series, self.style, label=label)
+ else:
+ ax.plot(x_series, y_series, self.style, label=label)
+
+ if self.secondary_x_data is not None:
+ sec_xax = ax.secondary_xaxis(location="top")
+ locations, labels = self._calcuate_secondary_labels()
+ sec_xax.set_xticks(locations, labels)
+ if self.secondary_x_label is not None:
+ sec_xax.set_xlabel(self.secondary_x_label)
+
+ ax.xaxis.set_major_formatter(FuncFormatter(lambda x, pos: format(x, "g")))
+
+ if self.xlim is not None:
+ ax.set_xlim(self.xlim)
+ if self.ylim is not None:
+ ax.set_ylim(self.ylim)
+
+ ax.set_xlabel(self.x_label)
+ ax.set_ylabel(self.y_label)
+ if self.legend:
+ ax.legend()
+
+ return fig
+
+
+class ManualLimit(Flow360BaseModel):
+ """
+ Class for setting up xlim and ylim in Chart2D by providing
+ a lower and upper value of the limits.
+ """
+
+ lower: float = Field(description="Absolute value of the lower limit of an axis.")
+ upper: float = Field(description="Absolute value of the upper limit of an axis.")
+ type_name: Literal["ManualLimit"] = Field("ManualLimit", frozen=True)
+
+
+class SubsetLimit(Flow360BaseModel):
+ """
+ Class for setting up ylim in Chart2D by providing
+ a subset of values and an offset, which will be applied
+ to the range of y values.
+ """
+
+ subset: Tuple[pd.NonNegativeFloat, pd.NonNegativeFloat] = Field(
+ description="Tuple of fractions between 0 and 1 describing the lower"
+ + " and upper range of the subset of values that will be used to calculate the ylim."
+ )
+ offset: float = Field(
+ description='"Padding" that will be added to the top and bottom of the charts y_range.'
+ + " It scales with with calculated range of y values. For example, if range of y value is 10,"
+ + ' an offset=0.3 will "expand" the range by 0.3*10 on both sides,'
+ + " resulting in a final range of y values equal to 16."
+ )
+ type_name: Literal["SubsetLimit"] = Field("SubsetLimit", frozen=True)
+
+ @pd.model_validator(mode="after")
+ def check_subset_values(self):
+ """
+ Ensure that correct subset values are provided.
+ """
+ lower, upper = self.subset
+ if not lower < 1 or not upper <= 1:
+ raise ValueError("Subset values need to be between 0 and 1 (inclusive).")
+ if not lower <= upper:
+ raise ValueError("Lower fraction of the subset cannot be higher than upper fraction.")
+ return self
+
+
+class FixedRangeLimit(Flow360BaseModel):
+ """
+ Class for setting up ylim in Chart2D by providing
+ a fixed range of y values and strategy for centering.
+ """
+
+ fixed_range: float = Field(
+ description="Range of absolute y values that will be visible on the chart."
+ + " For example, fixed_range=3 means that y_max - y_min = 3."
+ )
+ center_strategy: Literal["last", "last_percent"] = Field(
+ "last",
+ description="Describes which values will be considered for calculating ylim."
+ + ' "last" means that the last value will be the center. "last_percent"'
+ + " means that the middle point between max and min y values"
+ + " in the specified center_fraction will be the center.",
+ )
+ center_fraction: Optional[pd.PositiveFloat] = Field(
+ None,
+ description='Used alongside center_strategy="last_percent",'
+ + " describes values that will be taken into account for calculating ylim."
+ + " For example, center_fraction=0.3 means that the last 30% of data will be used.",
+ )
+ type_name: Literal["FixedRangeLimit"] = Field("FixedRangeLimit", frozen=True)
+
+ @pd.model_validator(mode="after")
+ def check_center_fraction(self):
+ """Ensure that correct center fraction value is provided."""
+ if self.center_strategy == "last_percent" and self.center_fraction >= 1:
+ raise ValueError("Center fraction value needs to be between 0 and 1 (exclusive).")
+ return self
+
+
+class BaseChart2D(Chart, metaclass=ABCMeta):
+ """
+ Base class for Chart2D like objects - does not contain data.
+ """
+
+ operations: Optional[Union[List[OperationTypes], OperationTypes]] = Field(
+ None, description="List of operations to perform on the data."
+ )
+ focus_x: Optional[
+ Annotated[
+ Tuple[float, float],
+ Field(
+ deprecated="focus_x is deprecated, your input was converted to a corresponding SubsetLimit. "
+ + "Please use ylim=SubsetLimit instead in the future.",
+ ),
+ ]
+ ] = None
+ xlim: Optional[Union[ManualLimit, Tuple[float, float]]] = Field(
+ None, description="Defines the range of x values that will be displayed on the chart."
+ )
+ ylim: Optional[Union[ManualLimit, SubsetLimit, FixedRangeLimit, Tuple[float, float]]] = Field(
+ None,
+ description="Defines the range of y values that will be displayed on the chart."
+ + " This helps with highlighting a desired portion of the chart.",
+ )
+ y_log: Optional[bool] = Field(
+ False, description="Sets the y axis to logarithmic scale. Defaults to ``False``."
+ )
+ show_grid: Optional[bool] = Field(
+ True, description="Turns the gridlines on. Defaults to ``True``."
+ )
+
+ def is_log_plot(self):
+ """
+ Determines if the plot is logarithmic.
+
+ Returns
+ -------
+ bool
+ """
+ return self.y_log is True
+
+ # pylint: disable=unpacking-non-sequence
+ @pd.model_validator(mode="after")
+ def _handle_deprecated_focus_x(self):
+ """
+ Ensures that scripts containing deprecated focus_x will still work.
+ """
+ if self.focus_x is not None:
+ if self.ylim is not None:
+ raise ValueError("Fields ylim and focus_x cannot be used together.")
+ lower, upper = self.focus_x
+ self.focus_x = None
+ self.ylim = SubsetLimit(subset=(lower, upper), offset=0.25)
+ return self
+
+ @pd.model_validator(mode="after")
+ def _check_caption_separate_plots(self):
+ if self.separate_plots is not True:
+ if isinstance(self.caption, List):
+ raise ValueError(
+ "List of captions is only supported for Chart2D when separate_plots is True."
+ )
+ if isinstance(self.caption, PatternCaption):
+ raise ValueError(
+ "PatternCaption is only supported for Chart2D when separate_plots is True."
+ )
+ return self
+
+ def _check_dimensions_consistency(self, data):
+ if any(isinstance(d, unyt.unyt_array) for d in data):
+ for d in data:
+ if d is None:
+ continue
+ if not isinstance(d, unyt.unyt_array):
+ raise ValueError(
+ f"data: {data} contains data with units and without, cannot create plot."
+ )
+
+ dimesions = {v.units.dimensions for v in data if data is not None}
+ if len(dimesions) > 1:
+ raise ValueError(
+ f"{data} contains data with different dimensions {dimesions=}, cannot create plot."
+ )
+ units = [d.units for d in data if d is not None][0]
+ data = [d.to(units) for d in data if data]
+ return True
+ return False
+
+ def _is_multiline_data(self, x_data: list, y_data: list):
+ return (
+ len(x_data) == 1
+ and isinstance(x_data[0], list)
+ and len(y_data) == 1
+ and isinstance(y_data[0], list)
+ )
+
+ @abstractmethod
+ def _get_background_chart(self, _):
+ pass
+
+ def _handle_xlimits(self) -> Tuple[Optional[float], Optional[float]]:
+ """
+ Make sure that xlim is always passed
+ as a tuple of floats to the plotting tool.
+ """
+ xlim = self.xlim
+ if xlim is None:
+ return None
+
+ if isinstance(xlim, ManualLimit):
+ return (xlim.lower, xlim.upper)
+
+ return xlim
+
+ def _calculate_subset(self, x_series_list, y_series_list, start_frac, end_frac):
+ """
+ Based on provided data series and fraction start and end,
+ calculate the corresponding subset of data.
+ """
+ all_subset_y = []
+
+ for xs, ys in zip(x_series_list, y_series_list):
+ xs_np = np.array(xs)
+ ys_np = np.array(ys)
+
+ start_idx = int(len(xs_np) * start_frac)
+ end_idx = int(len(xs_np) * end_frac)
+
+ if end_idx > start_idx:
+ subset_y = ys_np[start_idx:end_idx]
+ else:
+ subset_y = ys_np
+
+ if len(subset_y) > 0:
+ all_subset_y.extend(subset_y.tolist())
+
+ return all_subset_y
+
+ def _calculate_y_min_max(
+ self, all_subset_y, type_name: Literal["SubsetLimit", "FixedRangeLimit"]
+ ) -> Tuple[float, float]:
+ """
+ Given a subset of data and ylim type,
+ calculate min and max y values.
+ """
+ subset_y_min = float(min(all_subset_y))
+ subset_y_max = float(max(all_subset_y))
+
+ if type_name == "SubsetLimit":
+ y_range = subset_y_max - subset_y_min
+ y_min = subset_y_min - self.ylim.offset * y_range
+ y_max = subset_y_max + self.ylim.offset * y_range
+
+ elif type_name == "FixedRangeLimit":
+ y_center = (subset_y_max + subset_y_min) / 2
+ y_min = y_center - 0.5 * self.ylim.fixed_range
+ y_max = y_center + 0.5 * self.ylim.fixed_range
+ else:
+ raise ValueError(f"Unknown type_name: {type_name}.")
+
+ return (y_min, y_max)
+
+ def _calculate_ylimits(
+ self, x_series_list: List[List[float]], y_series_list: List[List[float]]
+ ) -> Tuple[Optional[float], Optional[float]]:
+ """
+ Calculate ylim based on provided input.
+ """
+ ylim = self.ylim
+
+ if ylim is None:
+ return None
+
+ if isinstance(ylim, Tuple):
+ return ylim
+
+ if isinstance(ylim, ManualLimit):
+ y_range = (ylim.lower, ylim.upper)
+
+ elif isinstance(ylim, SubsetLimit):
+ start_frac, end_frac = ylim.subset
+
+ all_subset_y = self._calculate_subset(
+ x_series_list, y_series_list, start_frac, end_frac
+ )
+
+ if not all_subset_y:
+ return (None, None)
+
+ y_range = self._calculate_y_min_max(all_subset_y, ylim.type_name)
+
+ else:
+ if ylim.center_strategy == "last":
+ all_last_y = []
+ for ys in y_series_list:
+ last_y = ys[-1]
+ all_last_y.append(last_y)
+
+ else:
+ start_frac = 1 - ylim.center_fraction
+ end_frac = 1
+ all_last_y = self._calculate_subset(
+ x_series_list, y_series_list, start_frac, end_frac
+ )
+
+ if not all_last_y:
+ return (None, None)
+
+ y_range = self._calculate_y_min_max(all_last_y, ylim.type_name)
+
+ return y_range
+
+ @abstractmethod
+ def _load_data(self, cases):
+ pass
+
+ @abstractmethod
+ def _handle_legend(self, cases, x_data, y_data):
+ pass
+
+ def _handle_plot_style(self, x_data, y_data):
+ if self._is_multiline_data(x_data, y_data):
+ style = "o-"
+ else:
+ style = "-"
+
+ return style
+
+ def _cumulate_pseudo_step(self, pseudo_steps):
+ cumulative = []
+ last = 0
+ for step in pseudo_steps:
+ if (step == 0) and cumulative:
+ last = cumulative[-1] + 1
+ cumulative.append(step + last)
+
+ return cumulative
+
+ def _handle_transient_pseudo_step(self, cases, x_data, x_label):
+ """
+ Converts pseudo_step to cumulative pseudo_step.
+ """
+ if x_label == "pseudo_step" and any(
+ isinstance(case.params.time_stepping, Unsteady) for case in cases
+ ):
+ for idx, x_series in enumerate(x_data):
+ x_data[idx] = self._cumulate_pseudo_step(x_series)
+
+ def _handle_secondary_x_axis(self, cases, x_data, x_lim, x_label):
+ """
+ Creates physical_step array to use on the secondary axis
+ when the primary axis is pseudo_step, and the number of physical_steps visible
+ within x axis limits is less or equal than 5.
+ """
+ if x_label == "pseudo_step" and any(
+ isinstance(case.params.time_stepping, Unsteady) for case in cases
+ ):
+ if len(cases) == 1:
+ path_to_physical_step = self.x.rstrip("pseudo_step") + "physical_step"
+ sec_x_data = data_from_path(cases[0], path_to_physical_step, [])
+ x_min = min(x_data[0])
+ x_max = max(x_data[0])
+ lower_idx = x_data[0].index(max(x_min, x_lim[0] if x_lim is not None else -np.inf))
+ upper_idx = x_data[0].index(min(x_max, x_lim[1] if x_lim is not None else np.inf))
+ physical_steps_to_show = sec_x_data[upper_idx] - sec_x_data[lower_idx]
+ if physical_steps_to_show <= 5:
+ return [sec_x_data] * len(x_data), "physical_step"
+ else:
+ log.warning("Does not show physical step with multiple cases plotted.")
+ return None, None
+
+ def _remove_empty_series(self, x_data, y_data, legend):
+ to_pop = []
+ for idx, x_series in enumerate(x_data):
+ if not x_series:
+ to_pop.append(idx)
+
+ x_data = [series for series in x_data if series]
+ y_data = [series for series in y_data if series]
+ legend = [item for idx, item in enumerate(legend) if idx not in to_pop]
+
+ return x_data, y_data, legend
+
+ def get_data(self, cases: List[Case], context: ReportContext) -> PlotModel:
+ """
+ Loads and processes data for creating a 2D plot model.
+
+ Parameters
+ ----------
+ cases : List[Case]
+ A list of simulation cases to extract data from.
+ context : ReportContext
+ The report context providing additional configuration and case-specific data.
+
+ Returns
+ -------
+ PlotModel
+ A `PlotModel` instance containing the processed x and y data, axis labels,
+ legend, and optional background image for plotting.
+
+ Notes
+ -----
+ - Handles data with physical units and ensures dimensional consistency.
+ - Supports optional background images for geometry-related plots.
+ - Automatically determines y-axis limits if `focus_x` is specified.
+
+ Examples
+ --------
+ >>> chart = Chart2D(
+ ... x="x_slicing_force_distribution/X",
+ ... y="x_slicing_force_distribution/totalCumulative_CD_Curve",
+ ... background="geometry"
+ ... )
+ >>> plot_model = chart.get_data(cases, context)
+ >>> fig = plot_model.get_plot()
+ >>> fig.show()
+ """
+ x_data, y_data, x_label, y_label = self._load_data(cases)
+
+ background = self._get_background_chart(x_data)
+ background_png = None
+ if background is not None:
+ # pylint: disable=protected-access
+ background_png = background._get_images([cases[0]], context)[0]
+
+ legend = self._handle_legend(cases, x_data, y_data)
+
+ if not self._is_multiline_data(x_data, y_data):
+ x_data, y_data, legend = self._remove_empty_series(x_data, y_data, legend)
+
+ style = self._handle_plot_style(x_data, y_data)
+
+ xlim = self._handle_xlimits()
+ ylim = self._calculate_ylimits(x_data, y_data)
+
+ self._handle_transient_pseudo_step(x_data=x_data, x_label=x_label, cases=cases)
+
+ secondary_x_data, seondary_x_label = self._handle_secondary_x_axis(
+ x_lim=xlim, x_data=x_data, x_label=x_label, cases=cases
+ )
+
+ return PlotModel(
+ x_data=x_data,
+ y_data=y_data,
+ x_label=x_label,
+ y_label=y_label,
+ legend=legend,
+ style=style,
+ is_log=self.is_log_plot(),
+ backgroung_png=background_png,
+ xlim=xlim,
+ ylim=ylim,
+ grid=self.show_grid,
+ secondary_x_data=secondary_x_data,
+ secondary_x_label=seondary_x_label,
+ )
+
+ def _get_figures(self, cases, context: ReportContext):
+
+ import matplotlib.pyplot as plt # pylint: disable=import-outside-toplevel
+
+ file_names = []
+ case_by_case, data_storage = context.case_by_case, context.data_storage
+ cbc_str = "_cbc_" if case_by_case else "_"
+ if self.separate_plots:
+ for case in cases:
+ file_name = os.path.join(data_storage, self.fig_name + cbc_str + case.id + ".pdf")
+ data = self.get_data([case], context)
+ fig = data.get_plot()
+ fig.savefig(file_name, format="pdf", bbox_inches="tight")
+ file_names.append(file_name)
+ plt.close()
+
+ else:
+ file_name = os.path.join(data_storage, self.fig_name + cbc_str + "all_cases" + ".pdf")
+ data = self.get_data(cases, context)
+ fig = data.get_plot()
+ fig.savefig(file_name, format="pdf", bbox_inches="tight")
+ file_names.append(file_name)
+ plt.close()
+
+ return file_names, data.x_label, data.y_label
+
+ # pylint: disable=too-many-return-statements
+ def _handle_2d_caption(
+ self, case: Case = None, x_lab: str = None, y_lab: str = None, case_number: int = None
+ ):
+ """
+ Handle captions for Chart2D.
+ """
+
+ if self.caption == "":
+ if self.items_in_row is not None:
+ return f"{bold(y_lab)} against {bold(x_lab)}."
+ if self.separate_plots is True:
+ return f"{bold(y_lab)} against {bold(x_lab)} for {bold(case.name)}."
+ if self.select_indices is not None:
+ return f"{bold(y_lab)} against {bold(x_lab)} for {bold('selected cases')}."
+ return f"{bold(y_lab)} against {bold(x_lab)} for {bold('all cases')}."
+ if self.separate_plots is True:
+ if isinstance(self.caption, List):
+ return escape_latex(self.caption[case_number])
+ if isinstance(self.caption, PatternCaption):
+ return escape_latex(self.caption.resolve(case))
+ return self.caption
+
+ # pylint: disable=too-many-arguments,too-many-locals
+ def get_doc_item(self, context: ReportContext, settings: Settings = None) -> None:
+ """
+ Returns doc item for chart.
+ """
+ self._handle_new_page(context.doc)
+ self._handle_grid_input(context.cases)
+ self._handle_title(context.doc, context.section_func)
+ cases = self._filter_input_cases(context.cases, context.case_by_case)
+ self._check_caption_validity(cases)
+
+ file_names, x_lab, y_lab = self._get_figures(cases, context)
+
+ if self.items_in_row is not None:
+ caption = NoEscape(self._handle_2d_caption(x_lab=x_lab, y_lab=y_lab))
+ self._add_row_figure(context.doc, file_names, caption, [case.name for case in cases])
+ else:
+ if self.separate_plots is True:
+ for case_number, (case, file_name) in enumerate(zip(cases, file_names)):
+ caption = NoEscape(
+ self._handle_2d_caption(
+ case=case, x_lab=x_lab, y_lab=y_lab, case_number=case_number
+ )
+ )
+ self._add_figure(context.doc, file_name, caption)
+ else:
+ caption = NoEscape(self._handle_2d_caption(x_lab=x_lab, y_lab=y_lab))
+ self._add_figure(context.doc, file_names[-1], caption)
+
+ context.doc.append(NoEscape(r"\FloatBarrier"))
+ context.doc.append(NoEscape(r"\clearpage"))
+
+
+class Chart2D(BaseChart2D):
+ """
+ Represents a 2D chart within a report, plotting x and y data.
+
+ Example
+ -------
+
+ - Create a chart of CL for an alpha sweep case, different turbulence models
+
+ >>> Chart2D(
+ ... x="params/operating_condition/beta",
+ ... y=DataItem(data="total_forces/CL", operations=[Average(fraction=0.1)]),
+ ... section_title="CL vs alpha",
+ ... fig_name="cl_vs_alpha",
+ ... group_by=Grouper(group_by="params/models/Fluid/turbulence_model_solver/type_name"),
+ ... )
+
+ ====
+ """
+
+ x: Union[DataItem, Delta, str] = Field(
+ description="The data source for the x-axis, which can be a string path, 'DataItem', a 'Delta' object."
+ )
+ y: Union[DataItem, Delta, str, List[DataItem], List[Delta], List[str]] = Field(
+ description="The data source for the y-axis, which can be a string path,"
+ + " 'DataItem', a 'Delta' object or their list."
+ )
+ group_by: Optional[Union[str, Grouper]] = Field(
+ Grouper(group_by=None),
+ description="A grouper object or a string leading to the data by which the grouping should be done.",
+ )
+ include: Optional[
+ Annotated[
+ List[str],
+ Field(
+ deprecated="Include and exclude are deprecated as Chart2D options, use DataItem instead."
+ ),
+ ]
+ ] = Field(
+ None,
+ description="List of boundaries to include in data. Applicable to:"
+ + " x_slicing_force_distribution, y_slicing_force_distribution, surface_forces.",
+ )
+ exclude: Optional[
+ Annotated[
+ List[str],
+ Field(
+ deprecated="Include and exclude are deprecated as Chart2D options, use DataItem instead."
+ ),
+ ]
+ ] = Field(
+ None,
+ description="List of boundaries to exclude from data. Applicable to:"
+ + " x_slicing_force_distribution, y_slicing_force_distribution, surface_forces.",
+ )
+ background: Union[Literal["geometry"], None] = Field(
+ None,
+ description='Background type for the chart; set to "geometry" or None. Defaults to ``None``.',
+ )
+ type_name: Literal["Chart2D"] = Field("Chart2D", frozen=True)
+
+ @pd.model_validator(mode="after")
+ def _handle_deprecated_include_exclude(self):
+ include = self.include
+ exclude = self.exclude
+ if (include is not None) or (exclude is not None):
+ object.__setattr__(self, "include", None)
+ object.__setattr__(self, "exclude", None)
+ self.x = self._overload_include_exclude(include, exclude, self.x)
+ if isinstance(self.y, List):
+ new_value = []
+ for data_variable in self.y:
+ new_value.append(
+ self._overload_include_exclude(include, exclude, data_variable)
+ )
+ self.y = new_value
+ else:
+ self.y = self._overload_include_exclude(include, exclude, self.y)
+ return self
+
+ @pd.model_validator(mode="after")
+ def _create_grouper(self):
+ if isinstance(self.group_by, str):
+ self.group_by = Grouper(group_by=self.group_by)
+ return self
+
+ @classmethod
+ def _overload_include_exclude(cls, include, exclude, data_variable):
+ if isinstance(data_variable, Delta):
+ raise Flow360ValidationError(
+ "Delta can not be used with exclude/include options. "
+ + "Specify the Delta data using DataItem."
+ )
+ if not isinstance(data_variable, DataItem):
+ data_variable = DataItem(data=data_variable, include=include, exclude=exclude)
+ else:
+ data_variable.include = include
+ data_variable.exclude = exclude
+ return data_variable
+
+ def get_requirements(self):
+ """
+ Returns requirements for this item.
+ """
+ if isinstance(self.y, list):
+ return get_requirements_from_data_path([self.x, *self.y])
+ return get_requirements_from_data_path([self.x, self.y])
+
+ # pylint: disable=no-member
+ def _handle_data_with_units(self, x_data, y_data, x_label, y_label):
+ for idx, (x_series, y_series) in enumerate(zip(x_data, y_data)):
+ united_array_x = unyt.unyt_array(x_series)
+ united_array_y = unyt.unyt_array(y_series)
+ if united_array_x.units != unyt.dimensionless:
+ x_data[idx] = united_array_x
+ if united_array_y.units != unyt.dimensionless:
+ y_data[idx] = united_array_y
+
+ if self._check_dimensions_consistency(x_data) is True:
+ x_unit = x_data[0].units
+ x_data = [data.value.tolist() for data in x_data]
+ x_label += f" [{x_unit}]"
+
+ if self._check_dimensions_consistency(y_data) is True:
+ y_unit = y_data[0].units
+ y_data = [data.value.tolist() for data in y_data]
+ if not isinstance(self.y, list):
+ y_label += f" [{y_unit}]"
+
+ return x_data, y_data, x_label, y_label
+
+ def _handle_legend(self, cases, x_data, y_data):
+ if not self._is_series_data(cases[0], self.x):
+ return self.group_by.arrange_legend()
+
+ if self._is_multiline_data(x_data, y_data):
+ legend = None
+ elif isinstance(self.y, list) and (len(self.y) > 1):
+ legend = []
+ for case in cases:
+ for y in self.y:
+ if len(cases) > 1:
+ legend.append(f"{case.name} - {path_variable_name(str(y))}")
+ else:
+ legend.append(f"{path_variable_name(str(y))}")
+ else:
+ legend = [case.name for case in cases]
+
+ return legend
+
+ def _is_series_data(self, example_case, variable):
+ data_point = data_from_path(example_case, variable, None)
+ if isinstance(data_point, Iterable):
+ if isinstance(data_point, unyt_quantity) and data_point.shape == ():
+ return False
+ return True
+ return False
+
+ def _validate_variable_format(self, example_case, x_variable, y_variables):
+ series = self._is_series_data(example_case, x_variable)
+
+ for y in y_variables:
+ if series != self._is_series_data(example_case, y):
+ raise AttributeError(
+ "Variables incompatible - cannot plot point and series data on the same plot."
+ )
+
+ def _load_series(self, cases, x_label, y_variables):
+ x_data = []
+ y_data = []
+ for case in cases:
+ filter_physical_steps = isinstance(case.params.time_stepping, Unsteady) and (
+ x_label in ["time", "physical_step"]
+ )
+ for y in y_variables:
+ x_data.append(
+ data_from_path(
+ case, self.x, cases, filter_physical_steps_only=filter_physical_steps
+ )
+ )
+ y_data.append(
+ data_from_path(case, y, cases, filter_physical_steps_only=filter_physical_steps)
+ )
+
+ return x_data, y_data
+
+ def _load_points(self, cases, y_variables):
+ x_data, y_data = self.group_by.initialize_arrays(cases, y_variables)
+ for case in cases:
+ for y in y_variables:
+ x_data_point = data_from_path(case, self.x, cases)
+ y_data_point = data_from_path(case, y, cases)
+ x_data, y_data = self.group_by.arrange_data(
+ case, x_data, y_data, x_data_point, y_data_point, y
+ )
+
+ return x_data, y_data
+
+ def _load_data(self, cases):
+ x_label = path_variable_name(str(self.x))
+
+ if not isinstance(self.y, list):
+ y_label = path_variable_name(str(self.y))
+ y_variables = [self.y]
+ else:
+ y_label = "value"
+ y_variables = self.y.copy()
+
+ self._validate_variable_format(cases[0], self.x, y_variables)
+
+ if self._is_series_data(cases[0], self.x):
+ x_data, y_data = self._load_series(cases, x_label, y_variables)
+ else:
+ x_data, y_data = self._load_points(cases, y_variables)
+
+ x_data, y_data, x_label, y_label = self._handle_data_with_units(
+ x_data, y_data, x_label, y_label
+ )
+
+ return x_data, y_data, x_label, y_label
+
+ def _get_background_chart(self, x_data):
+ if self.background == "geometry":
+ dimension = np.amax(x_data[0]) - np.amin(x_data[0])
+ if isinstance(self.x, (DataItem, Delta)):
+ x_path = self.x.data
+ else:
+ x_path = self.x
+
+ if x_path.startswith("results/"):
+ x_path = x_path[len("results/") :]
+
+ include = None
+ exclude = None
+ if x_path == "x_slicing_force_distribution/X":
+ log.warning(
+ "First case is used as a background image with dimensions matched to the extent of X data"
+ )
+ camera = Camera(
+ position=(0, -1, 0), up=(0, 0, 1), dimension=dimension, dimension_dir="width"
+ )
+ include = self.x.include
+ exclude = self.x.exclude
+ elif x_path == "y_slicing_force_distribution/Y":
+ log.warning(
+ "First case is used as a background image with dimensions matched to the extent of X data"
+ )
+ camera = Camera(
+ position=(-1, 0, 0), up=(0, 0, 1), dimension=dimension, dimension_dir="width"
+ )
+ include = self.y.include
+ exclude = self.y.exclude
+ else:
+ raise ValueError(
+ f"background={self.background} can be only used with x == x_slicing_force_distribution/X"
+ + " OR x == y_slicing_force_distribution/Y"
+ )
+ background = Chart3D(
+ show="boundaries",
+ camera=camera,
+ fig_name="background_" + self.fig_name,
+ include=include,
+ exclude=exclude,
+ )
+ return background
+ return None
+
+ def get_background_chart3d(self, cases) -> Tuple[Chart3D, Case]:
+ """
+ Returns Chart3D for background.
+ """
+ # pylint: disable=unsubscriptable-object
+ reference_case_idx = self.select_indices[0] if self.select_indices is not None else 0
+ reference_case = cases[reference_case_idx]
+ x_data, _, _, _ = self._load_data([reference_case])
+ return self._get_background_chart(x_data), reference_case
+
+
+class NonlinearResiduals(BaseChart2D):
+ """
+ Residuals is an object for showing the solution history of nonlinear residuals.
+ """
+
+ show_grid: Optional[bool] = Field(
+ True, description="If ``True``, grid lines are displayed on the plot. Defaults to ``True``."
+ )
+ separate_plots: Optional[bool] = Field(
+ True, description="If ``True``, each residual component is plotted in a separate subplot."
+ )
+ xlim: Optional[Union[ManualLimit, Tuple[float, float]]] = Field(
+ None,
+ description="Limits for the *x*-axis. Can be a tuple ``(xmin, xmax)`` or a `ManualLimit`.",
+ )
+ section_title: Literal["Nonlinear residuals"] = Field("Nonlinear residuals", frozen=True)
+ x: Literal["nonlinear_residuals/pseudo_step"] = Field(
+ "nonlinear_residuals/pseudo_step", frozen=True
+ )
+ y_log: Literal[True] = Field(True, frozen=True)
+ _requirements: List[RequirementItem] = [
+ RequirementItem.from_data_key(data_key="nonlinear_residuals")
+ ]
+ type_name: Literal["NonlinearResiduals"] = Field("NonlinearResiduals", frozen=True)
+
+ def get_requirements(self):
+ """
+ Returns requirements for this item.
+ """
+ return self._requirements
+
+ def _get_background_chart(self, _):
+ return None
+
+ def _handle_legend(self, cases, _, y_data):
+ cols_exclude = cases[0].results.nonlinear_residuals.x_columns
+ legend = []
+ for case in cases:
+ y_variables = [
+ f"nonlinear_residuals/{res}"
+ for res in case.results.nonlinear_residuals.as_dict().keys()
+ if res not in cols_exclude
+ ]
+ legend += [
+ (
+ f"{case.name} - {path_variable_name(y)}"
+ if len(cases) > 1
+ else f"{path_variable_name(y)}"
+ )
+ for y in y_variables
+ ]
+
+ return legend
+
+ def _handle_secondary_x_axis(self, cases, x_data, x_lim, x_label):
+ secondary_x_data, seondary_x_label = super()._handle_secondary_x_axis(
+ cases, x_data, x_lim, x_label
+ )
+ if secondary_x_data is not None:
+ return np.array(secondary_x_data)[:, 1:].tolist(), seondary_x_label
+ return secondary_x_data, seondary_x_label
+
+ def _load_data(self, cases):
+ cols_exclude = cases[0].results.nonlinear_residuals.x_columns
+ x_label = path_variable_name(self.x)
+ y_label = "residual values"
+
+ x_data = []
+ y_data = []
+
+ for case in cases:
+ y_variables = [
+ f"nonlinear_residuals/{res}"
+ for res in case.results.nonlinear_residuals.as_dict().keys()
+ if res not in cols_exclude
+ ]
+ for y in y_variables:
+ x_data.append(data_from_path(case, self.x, cases)[1:])
+ y_data.append(data_from_path(case, y, cases)[1:])
+
+ return x_data, y_data, x_label, y_label
+
+
+class Chart3D(Chart):
+ """
+ Represents a 3D chart within a report, displaying a specific surface field.
+ """
+
+ field: Optional[Union[SurfaceFieldNames, str]] = Field(
+ None, description="The name of the field to display in the chart."
+ )
+ camera: Optional[
+ Union[
+ Camera,
+ BottomCamera,
+ FrontCamera,
+ FrontLeftBottomCamera,
+ FrontLeftTopCamera,
+ LeftCamera,
+ RearCamera,
+ RearLeftTopCamera,
+ RearRightBottomCamera,
+ TopCamera,
+ ]
+ ] = pd.Field(
+ default=Camera(), description="Specify how the view will be set up.", discriminator="type"
+ )
+ limits: Optional[Union[Tuple[float, float], Tuple[DimensionedTypes, DimensionedTypes]]] = Field(
+ None, description="Limits for the field values, specified as a tuple (min, max)."
+ )
+ is_log_scale: bool = Field(
+ False, description="Applies a logarithmic scale to the colormap. Defaults to ``False``."
+ )
+ show: ShutterObjectTypes = Field(
+ description="Type of object to display in the 3D chart. Note: ``qcriterion`` refers to an iso-surface"
+ + " that is created by default, whereas ``isosurface`` refers to iso-surfaces specified in simulation outputs."
+ )
+ iso_field: Optional[Union[IsoSurfaceFieldNames, str]] = Field(
+ None,
+ description="Iso-surface fields to be displayed when ``isosurface`` is selected in ``show``.",
+ )
+ mode: Optional[Literal["contour", "lic"]] = Field(
+ "contour", description="Field display mode, lic stands for line integral convolution."
+ )
+ include: Optional[List[str]] = Field(
+ None, description="Boundaries to be included in the chart."
+ )
+ exclude: Optional[List[str]] = Field(
+ None, description="Boundaries to be excluded from the chart."
+ )
+ type_name: Literal["Chart3D"] = Field("Chart3D", frozen=True)
+
+ # pylint: disable=unsubscriptable-object
+ def _get_limits(self, case: Case):
+ if self.limits is not None and not isinstance(self.limits[0], float):
+ params: SimulationParams = case.params
+ if is_flow360_unit(self.limits[0]):
+ return (self.limits[0].value, self.limits[1].value)
+
+ if isinstance(self.limits[0], unyt_quantity):
+ _, unit_system = get_unit_for_field(self.field)
+ target_system = "flow360"
+ if unit_system is not None:
+ target_system = unit_system
+ min_val = params.convert_unit(self.limits[0], target_system=target_system)
+ max_val = params.convert_unit(self.limits[1], target_system=target_system)
+ return (float(min_val.value), float(max_val.value))
+
+ return self.limits
+
+ def _get_shutter_exclude_visibility(self):
+ if self.exclude is not None:
+ return [
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(object_ids=self.exclude, visibility=False),
+ )
+ ]
+ return []
+
+ def _get_shutter_include_visibility(self):
+ if self.include is not None:
+ return [
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(object_ids=self.include, visibility=True),
+ )
+ ]
+ return []
+
+ def _get_shutter_qcriterion_script(
+ self,
+ script: List = None,
+ field: str = None,
+ limits: Tuple[float, float] = None,
+ is_log_scale: bool = None,
+ ):
+ if script is None:
+ script = []
+
+ script += [
+ ActionPayload(
+ action="reset-field",
+ payload=ResetFieldPayload(
+ object_id="boundaries",
+ ),
+ ),
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(
+ object_ids=["slices", "isosurfaces"], visibility=False
+ ),
+ ),
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(
+ object_ids=["qcriterion", "boundaries"], visibility=True
+ ),
+ ),
+ ]
+ script += self._get_shutter_exclude_visibility()
+ script += [
+ ActionPayload(
+ action="set-field",
+ payload=SetFieldPayload(
+ object_id="qcriterion",
+ field_name=field,
+ min_max=limits,
+ is_log_scale=is_log_scale,
+ ),
+ ),
+ ]
+ return script
+
+ # pylint: disable=too-many-arguments
+ def _get_shutter_isosurface_script(
+ self,
+ iso_field: str,
+ script: List = None,
+ field: str = None,
+ limits: Tuple[float, float] = None,
+ is_log_scale: bool = None,
+ ):
+ if script is None:
+ script = []
+
+ if iso_field != "qcriterion":
+ iso_field = f"isosurface-{iso_field.lower()}"
+
+ script += [
+ ActionPayload(
+ action="reset-field",
+ payload=ResetFieldPayload(
+ object_id="boundaries",
+ ),
+ ),
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(
+ object_ids=["slices", "isosurfaces"], visibility=False
+ ),
+ ),
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(
+ object_ids=[iso_field, "boundaries"], visibility=True
+ ),
+ ),
+ ]
+ script += self._get_shutter_include_visibility()
+ script += self._get_shutter_exclude_visibility()
+
+ if field is not None:
+ script += [
+ ActionPayload(
+ action="set-field",
+ payload=SetFieldPayload(
+ object_id=iso_field,
+ field_name=field,
+ min_max=limits,
+ is_log_scale=is_log_scale,
+ ),
+ ),
+ ]
+ return script
+
+ def _get_shutter_screenshot_script(self, script, screenshot_name):
+ script += [
+ ActionPayload(
+ action="take-screenshot",
+ payload=TakeScreenshotPayload(file_name=screenshot_name, type="png"),
+ )
+ ]
+ return script
+
+ def _get_shutter_set_camera(self, script, camera: Camera):
+ script += [
+ ActionPayload(
+ action="set-camera",
+ payload=SetCameraPayload(**camera.model_dump(exclude_none=True, exclude=["type"])),
+ )
+ ]
+ return script
+
+ def _get_focus_camera(self, script):
+ script += [
+ ActionPayload(action="focus", payload=FocusPayload(object_ids=["boundaries"], zoom=1.5))
+ ]
+ return script
+
+ def _get_shutter_boundary_script(
+ self,
+ script: List = None,
+ field: str = None,
+ limits: Tuple[float, float] = None,
+ is_log_scale: bool = None,
+ ):
+ if script is None:
+ script = []
+
+ if self.include is not None:
+ script += self._get_shutter_include_visibility()
+ else:
+ script += [
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(object_ids=["boundaries"], visibility=True),
+ )
+ ]
+ script += [
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(
+ object_ids=["slices", "isosurfaces"], visibility=False
+ ),
+ )
+ ]
+ script += self._get_shutter_exclude_visibility()
+
+ if field is None:
+ pass
+ # get geometry id?
+ else:
+ script += [
+ ActionPayload(
+ action="set-field",
+ payload=SetFieldPayload(
+ object_id="boundaries",
+ field_name=field,
+ min_max=limits,
+ is_log_scale=is_log_scale,
+ ),
+ )
+ ]
+ script += [
+ ActionPayload(
+ action="set-lic",
+ payload=SetLICPayload(object_id="boundaries", visibility=self.mode == "lic"),
+ )
+ ]
+
+ return script
+
+ def _get_shutter_slice_script(
+ self,
+ script: List = None,
+ field: str = None,
+ limits: Tuple[float, float] = None,
+ is_log_scale: bool = None,
+ ):
+ if script is None:
+ script = []
+
+ script += [
+ ActionPayload(
+ action="set-object-visibility",
+ payload=SetObjectVisibilityPayload(
+ object_ids=["boundaries", "isosurfaces", "slices"], visibility=False
+ ),
+ ),
+ ]
+ script += self._get_shutter_include_visibility()
+ script += self._get_shutter_exclude_visibility()
+
+ if field is None:
+ pass
+ # get geometry id?
+ else:
+ script += [
+ ActionPayload(
+ action="set-field",
+ payload=SetFieldPayload(
+ object_id="slices",
+ field_name=field,
+ min_max=limits,
+ is_log_scale=is_log_scale,
+ ),
+ )
+ ]
+ if self.include is not None:
+ script += [
+ ActionPayload(
+ action="set-lic",
+ payload=SetLICPayload(object_id=slice, visibility=self.mode == "lic"),
+ )
+ for slice in self.include # pylint: disable=not-an-iterable
+ ]
+
+ return script
+
+ def _get_shutter_request(self, case: Case):
+
+ if self.show == "qcriterion":
+ script = self._get_shutter_qcriterion_script(
+ field=self.field, limits=self._get_limits(case), is_log_scale=self.is_log_scale
+ )
+ elif self.show == "isosurface":
+ script = self._get_shutter_isosurface_script(
+ iso_field=self.iso_field,
+ field=self.field,
+ limits=self._get_limits(case),
+ is_log_scale=self.is_log_scale,
+ )
+ elif self.show == "boundaries":
+ script = self._get_shutter_boundary_script(
+ field=self.field, limits=self._get_limits(case), is_log_scale=self.is_log_scale
+ )
+ elif self.show == "slices":
+ script = self._get_shutter_slice_script(
+ field=self.field, limits=self._get_limits(case), is_log_scale=self.is_log_scale
+ )
+ else:
+ raise ValueError(f'"{self.show}" is not corect type for 3D chart.')
+
+ script = self._get_shutter_set_camera(script, self.camera)
+ if self.camera.dimension is None: # pylint: disable=no-member
+ script = self._get_focus_camera(script)
+
+ script = self._get_shutter_screenshot_script(script=script, screenshot_name=self.fig_name)
+
+ scene = Scene(name="my-scene", script=script)
+ path_prefix = case.get_cloud_path_prefix()
+ if self.field is None and self.show == "boundaries":
+ log.debug(
+ "Not implemented: getting geometry resource for showing geometry. Currently using case resource."
+ )
+ resource = Resource(path_prefix=path_prefix, id=case.id)
+ scenes_data = ScenesData(scenes=[scene], resource=resource)
+ return scenes_data
+
+ def get_requirements(self):
+ """get requirements"""
+ return []
+
+ def _get_images(self, cases: List[Case], context: ReportContext):
+ shutter_requests = []
+ for case in cases:
+ shutter_requests.append(self._get_shutter_request(case))
+
+ img_files = Shutter(**make_shutter_context(context)).get_images(
+ self.fig_name, shutter_requests, regenerate_if_not_found=False
+ )
+ # taking "first" image from returned images as UVF-shutter
+ # supports many screenshots generation on one call
+ img_list = [img_files[case.id][0] for case in cases if img_files[case.id] is not None]
+ return img_list
+
+ def _get_legend(self, context: ReportContext):
+ if self.field is not None:
+ legend_filename = os.path.join(context.data_storage, f"{self.fig_name}_legend.png")
+ field = self.field
+ limits = self.limits
+ if isinstance(self.limits[0], unyt_quantity):
+ field += f" [{self.limits[0].units}]"
+ limits = (float(self.limits[0].value), float(self.limits[1].value))
+ generate_colorbar_from_image(
+ limits=limits,
+ output_filename=legend_filename,
+ field_name=field,
+ is_log_scale=self.is_log_scale,
+ )
+ return legend_filename
+ return None
+
+ def _handle_3d_caption(self, case: Case = None, case_number: int = None):
+ """Handle captions for Chart3D."""
+
+ if isinstance(self.caption, List):
+ caption = self.caption[case_number]
+ elif isinstance(self.caption, PatternCaption):
+ caption = self.caption.resolve(case)
+ else:
+ caption = self.caption
+
+ return caption
+
+ # pylint: disable=too-many-arguments
+ def get_doc_item(self, context: ReportContext, settings: Settings = None):
+ """
+ returns doc item for 3D chart
+ """
+ self._handle_new_page(context.doc)
+ self._handle_grid_input(context.cases)
+ self._handle_title(context.doc, context.section_func)
+ cases = self._filter_input_cases(context.cases, context.case_by_case)
+ self._check_caption_validity(cases)
+
+ img_list = self._get_images(cases, context)
+ legend_filename = self._get_legend(context)
+
+ dpi = None
+ if settings is not None:
+ dpi = settings.dpi
+
+ if self.items_in_row is not None:
+ caption = self._handle_3d_caption()
+ self._add_row_figure(
+ context.doc,
+ img_list,
+ caption,
+ sub_fig_captions=[case.name for case in cases],
+ legend_filename=legend_filename,
+ dpi=dpi,
+ )
+ else:
+ for case_number, (case, filename) in enumerate(zip(cases, img_list)):
+ caption = self._handle_3d_caption(case=case, case_number=case_number)
+ self._add_figure(
+ context.doc, filename, caption, legend_filename=legend_filename, dpi=dpi
+ )
+
+ # Stops figures floating away from their sections
+ context.doc.append(NoEscape(r"\FloatBarrier"))
+ context.doc.append(NoEscape(r"\clearpage"))
diff --git a/flow360/plugins/report/utils.py b/flow360/plugins/report/utils.py
new file mode 100644
index 000000000..4bec8e116
--- /dev/null
+++ b/flow360/plugins/report/utils.py
@@ -0,0 +1,1216 @@
+"""
+report utils, utils.py
+"""
+
+# pylint: disable=too-many-lines
+from __future__ import annotations
+
+import ast
+import math
+import os
+import posixpath
+import re
+import shutil
+import uuid
+from abc import ABCMeta, abstractmethod
+from numbers import Number
+from typing import Annotated, Any, ClassVar, List, Literal, Optional, Tuple, Union
+
+import numpy as np
+import pydantic as pd
+
+# this plugin is optional, thus pylatex is not required: TODO add handling of installation of pylatex
+# pylint: disable=import-error
+from pylatex import NoEscape, Package, Tabular
+
+from flow360.component.case import Case, CaseMetaV2
+from flow360.component.results import base_results, case_results
+from flow360.component.simulation.framework.base_model import (
+ Conflicts,
+ Flow360BaseModel,
+)
+from flow360.component.volume_mesh import VolumeMeshDownloadable, VolumeMeshV2
+from flow360.log import log
+
+here = os.path.dirname(os.path.abspath(__file__))
+
+
+class RequirementItem(pd.BaseModel):
+ """
+ RequirementItem
+ """
+
+ resource_type: Literal["case", "volume_mesh", "surface_mesh", "geometry"] = "case"
+ filename: str
+
+ model_config = {"frozen": True}
+
+ _base_case_attributes: ClassVar[list] = CaseMetaV2.model_fields.keys()
+
+ # pylint: disable=protected-access
+ _requirements_mapping: ClassVar[dict] = {
+ "params": {"resource_type": "case", "filename": "simulation.json"},
+ "cfl": {
+ "resource_type": "case",
+ "filename": case_results.CFLResultCSVModel()._remote_path(),
+ },
+ "total_forces": {
+ "resource_type": "case",
+ "filename": case_results.TotalForcesResultCSVModel()._remote_path(),
+ },
+ "surface_forces": {
+ "resource_type": "case",
+ "filename": case_results.SurfaceForcesResultCSVModel()._remote_path(),
+ },
+ "linear_residuals": {
+ "resource_type": "case",
+ "filename": case_results.LinearResidualsResultCSVModel()._remote_path(),
+ },
+ "nonlinear_residuals": {
+ "resource_type": "case",
+ "filename": case_results.NonlinearResidualsResultCSVModel()._remote_path(),
+ },
+ "x_slicing_force_distribution": {
+ "resource_type": "case",
+ "filename": case_results.XSlicingForceDistributionResultCSVModel()._remote_path(),
+ },
+ "y_slicing_force_distribution": {
+ "resource_type": "case",
+ "filename": case_results.YSlicingForceDistributionResultCSVModel()._remote_path(),
+ },
+ "volume_mesh": {"resource_type": "volume_mesh", "filename": "simulation.json"},
+ "volume_mesh/stats": {
+ "resource_type": "volume_mesh",
+ "filename": VolumeMeshV2._mesh_stats_file,
+ },
+ "volume_mesh/bounding_box": {
+ "resource_type": "volume_mesh",
+ "filename": VolumeMeshDownloadable.BOUNDING_BOX.value,
+ },
+ "surface_mesh": {"resource_type": "surface_mesh", "filename": "simulation.json"},
+ "geometry": {"resource_type": "geometry", "filename": "simulation.json"},
+ "bet_forces": {
+ "resource_type": "case",
+ "filename": case_results.BETForcesResultCSVModel()._remote_path(),
+ },
+ "bet_forces_radial_distribution": {
+ "resource_type": "case",
+ "filename": case_results.BETForcesRadialDistributionResultCSVModel()._remote_path(),
+ },
+ "actuator_disks": {
+ "resource_type": "case",
+ "filename": case_results.ActuatorDiskResultCSVModel()._remote_path(),
+ },
+ "aeroacoustics": {
+ "resource_type": "case",
+ "filename": case_results.AeroacousticsResultCSVModel()._remote_path(),
+ },
+ "surface_heat_transfer": {
+ "resource_type": "case",
+ "filename": case_results.SurfaceHeatTransferResultCSVModel()._remote_path(),
+ },
+ }
+
+ _named_results_mapping: ClassVar[dict] = {
+ "monitors": {
+ "resource_type": "case",
+ "pattern": case_results.CaseDownloadable.MONITOR_PATTERN.value,
+ },
+ "user_defined_dynamics": {
+ "resource_type": "case",
+ "pattern": case_results.CaseDownloadable.USER_DEFINED_DYNAMICS_PATTERN.value,
+ },
+ }
+
+ @classmethod
+ @pd.validate_call
+ def from_data_key(cls, data_key: str, results_name: Optional[str] = None):
+ """
+ Return a RequirementItem object based on the data key (a type of data that is required).
+
+ Examples
+ --------
+ >>> RequirementItem.from_data_key(data_key="nonlinear_residuals")
+ >>> RequirementItem.from_data_key(data_key="surface_mesh")
+ >>> RequirementItem.from_data_key(data_key="monitors", results_name="massFluxExhaust")
+ """
+ if data_key in cls._base_case_attributes:
+ return None
+
+ if data_key in cls._requirements_mapping:
+ return cls(
+ resource_type=cls._requirements_mapping.get(data_key).get("resource_type"),
+ filename=cls._requirements_mapping.get(data_key).get("filename"),
+ )
+ if data_key in cls._named_results_mapping:
+ if results_name is None:
+ raise ValueError(f"Results name is required for {data_key}.")
+ return cls(
+ resource_type=cls._named_results_mapping.get(data_key).get("resource_type"),
+ filename="results/"
+ + cls._named_results_mapping.get(data_key)
+ .get("pattern")
+ .replace("(.+)", results_name),
+ )
+ raise NotImplementedError(
+ f"Unknown data key: {data_key}. Can not use this data for report generation yet"
+ + " or wrong data key was specified."
+ )
+
+
+def get_requirements_from_data_path(data_path: List) -> List[RequirementItem]:
+ """
+ Retrieves requirements based on data path entries by mapping root paths
+ to their corresponding requirements.
+
+ Parameters
+ ----------
+ data_path : iterable
+ An iterable containing data path entries to be checked.
+
+ Returns
+ -------
+ list
+ A list of unique requirements derived from the data path.
+
+ Raises
+ ------
+ ValueError
+ If a root path in the data path does not have a corresponding requirement.
+ """
+
+ requirements = set()
+ for item in data_path:
+ root_path = get_root_path(item)
+ root_path = split_path(root_path)
+ results_name = None
+ if root_path[0] == "results":
+ data_key = root_path[1]
+ results_name = root_path[2]
+ elif root_path[0] == "volume_mesh" and len(root_path) > 1:
+ data_key = root_path[0] + "/" + root_path[1]
+ else:
+ data_key = root_path[0]
+
+ requirement = RequirementItem.from_data_key(data_key=data_key, results_name=results_name)
+ requirements.add(requirement)
+ return list(requirements)
+
+
+def detect_latex_compiler():
+ """
+ Detects available LaTeX compilers on the system.
+ Returns:
+ compiler (str), compiler_args (list[str]): Name of the LaTeX compiler ('xelatex', 'latexmk', 'pdflatex').
+ Raises:
+ RuntimeError: If no LaTeX compiler is found.
+ """
+ preferred_compilers = [("xelatex", []), ("latexmk", ["--pdf"]), ("pdflatex", [])]
+ for compiler, compiler_args in preferred_compilers:
+ if shutil.which(compiler):
+ return compiler, compiler_args
+ # If no compiler is found, raise an error
+ raise RuntimeError(
+ "No LaTeX compiler found. Please install a LaTeX distribution (e.g., TeX Live, MiKTeX)."
+ )
+
+
+def check_landscape(doc):
+ """
+ Checks if a document is in landscape orientation based on geometry package options.
+
+ Parameters
+ ----------
+ doc : Document
+ The LaTeX document to check for landscape orientation.
+
+ Returns
+ -------
+ bool
+ True if the document is in landscape orientation, False otherwise.
+ """
+
+ for package in doc.packages:
+ if "geometry" in str(package.arguments):
+ return "landscape" in str(package.options)
+ return False
+
+
+def get_case_from_id(case_id: str, cases: list[Case]) -> Case:
+ """
+ Retrieves a case by its unique identifier from a list of cases.
+
+ Parameters
+ ----------
+ case_id : str
+ The unique identifier of the case to retrieve.
+ cases : list[Case]
+ A list of `Case` objects to search.
+
+ Returns
+ -------
+ Case
+ The `Case` object matching the specified `case_id`.
+
+ Raises
+ ------
+ ValueError
+ If no cases are provided or the specified `case_id` is not found.
+ """
+ if len(cases) == 0:
+ raise ValueError("No cases provided for `get_case_from_id`.")
+ for case in cases:
+ if case.id == case_id:
+ return case
+ raise ValueError(f"{case_id=} not found in {cases=}")
+
+
+def get_root_path(data_path):
+ """
+ Extracts the root path from a given data path.
+
+ If the provided `data_path` is of type `Delta`, the function retrieves
+ the path from `data_path.data`.
+
+ Parameters
+ ----------
+ data_path : str or Delta or None
+ The data path to parse or a `Delta` object containing a data path.
+
+ Returns
+ -------
+ str or None
+ The root path as a string if `data_path` is valid, otherwise `None`.
+ """
+
+ if data_path is not None:
+ if isinstance(data_path, (Delta, DataItem)):
+ data_path = data_path.data
+ if isinstance(data_path, DataItem):
+ data_path = data_path.data
+ return data_path
+ return None
+
+
+def split_path(path):
+ """
+ Split the path using both '/' and '.' as separators
+ """
+ path_components = [comp for comp in re.split(r"[/.]", path) if comp]
+ return path_components
+
+
+def path_variable_name(path):
+ """
+ Get the last component of the path.
+ """
+ return split_path(path)[-1]
+
+
+# pylint: disable=too-many-return-statements,too-many-branches
+def search_path(case: Case, component: str) -> Any:
+ """
+ Case starts as a `Case` object but changes as it recurses through the path components
+ """
+
+ # Check if component is an attribute
+ try:
+ return getattr(case, component)
+ except AttributeError:
+ pass
+
+ # Check if component is an attribute of case.results
+ # Convenience feature so the user doesn't have to include "results" in path
+ try:
+ return getattr(case.results, component)
+ except AttributeError:
+ pass
+
+ # Check if component is a key for a dictionary
+ try:
+ case = case[component]
+ # Have to test for int or str here otherwise...
+ if isinstance(case, (int, str)):
+ return case
+ # .. this raises a KeyError.
+ # This is a convenience that may be removed for if people want something other than the value
+ if "value" in case:
+ return case["value"]
+ return case
+ except TypeError:
+ pass
+
+ # Check if case is a list
+ # E.g. in user defined functions
+ if isinstance(case, list):
+ for obj in case:
+ try:
+ if obj.name == component:
+ return obj
+ if obj.type_name == component:
+ return obj
+ except AttributeError:
+ pass
+
+ if type(obj).__name__ == component:
+ return obj
+
+ # interpret component as an int index
+ try:
+ return case[int(component)]
+ except (ValueError, IndexError):
+ pass
+
+ # Check if case is a number
+ if isinstance(case, Number):
+ return case
+
+ # Check if component is a key of a value
+ try:
+ return case.values[component]
+ except KeyError as err:
+ raise ValueError(
+ f"Could not find path component: '{component}', available: {case.values.keys()}"
+ ) from err
+ except AttributeError:
+ log.warning(f"unknown value for path: {case=}, {component=}")
+
+ return None
+
+
+def data_from_path(
+ case: Case,
+ path: str,
+ cases: list[Case] = None,
+ case_by_case: bool = False,
+ filter_physical_steps_only: bool = False,
+) -> Any:
+ """
+ Retrieves data from a specified path within a `Case` object, with optional delta calculations.
+
+ Parameters
+ ----------
+ case : Case
+ The primary `Case` object to search.
+ path : str
+ The path string indicating the nested attributes or dictionary keys.
+ cases : list[Case], optional
+ List of additional cases for delta calculations, default is an empty list.
+ case_by_case : bool, default=False
+ Flag for enabling case-by-case delta calculation when `path` is a `Delta` object.
+ filter_physical_steps_only: bool
+ Whether to return data asociated only with the converged physical steps (last pseudo_step in a time step).
+
+ Returns
+ -------
+ Any
+ The data extracted from the specified path within the `Case` object or calculated delta.
+
+ Raises
+ ------
+ ValueError
+ If a specified path component is not found or cannot be accessed.
+
+ Notes
+ -----
+ This function splits the path into components and recursively searches through attributes,
+ dictionary keys, or list indices as indicated in each component. Supports delta calculation
+ using `Delta` objects and error handling for invalid paths.
+ """
+ if cases is None:
+ cases = []
+
+ if isinstance(path, Delta):
+ if case_by_case:
+ return path.model_copy(update={"ref_index": None}).calculate(case, cases)
+ return path.calculate(case, cases)
+
+ if isinstance(path, DataItem):
+ return path.calculate(case, cases)
+
+ # Split path into components
+ path_components = split_path(path)
+
+ # Case variable is slightly misleading as this is only a case on the first iteration
+ for component in path_components:
+ if component == "time":
+ case.reload_data(include_time=True)
+
+ if filter_physical_steps_only and (component == path_components[-1]):
+ case.reload_data(filter_physical_steps_only=True)
+
+ case = search_path(case, component)
+
+ return case
+
+
+def results_from_path(
+ case, path
+) -> tuple[Union[base_results.ResultBaseModel, None], Union[str, None]]:
+ """
+ Returns the last ResultsBaseModel object on the path.
+
+ Parameters
+ ----------
+ path : str
+ The path string indicating the nested attributes or dictionary keys.
+
+ Returns
+ -------
+
+ returned_case, returned_component: tuple[Union[base_results.ResultBaseModel, None], Union[str, None]]
+ returned_case - the last ResultsBaseModel object on the path,
+ returned_component - component of the returned case or None if the case was a last part of the path
+
+ """
+ path_components = split_path(path)
+ returned_case = None
+ returned_component = None
+ for component in path_components:
+ returned_component = component
+ case = search_path(case, component)
+ if isinstance(case, base_results.ResultBaseModel):
+ returned_case = case
+ returned_component = None
+ return returned_case, returned_component
+
+
+class GenericOperation(Flow360BaseModel, metaclass=ABCMeta):
+ """
+ Abstraction for operations
+ """
+
+ @abstractmethod
+ def calculate(
+ self, data, case, cases, variables, new_variable_name
+ ): # pylint: disable=too-many-arguments
+ """
+ evaluate operation
+ """
+
+
+class GetAttribute(GenericOperation):
+ """
+ Retrieve an attribute from a data object.
+
+ This operation extracts the attribute specified by `attr_name` from the provided data object
+ using Python's built-in `getattr` function. If the attribute is not found, an `AttributeError`
+ is raised, providing a clear error message.
+ """
+
+ attr_name: str = pd.Field(
+ description="The name of the attribute to retrieve from the data object."
+ )
+ type_name: Literal["GetAttribute"] = pd.Field("GetAttribute", frozen=True)
+
+ def calculate(
+ self, data, case, cases, variables, new_variable_name
+ ): # pylint: disable=too-many-arguments
+ """
+ Retrieves the attribute specified by `attr_name` from the given data object.
+ Returns a tuple containing the original data, the cases list, and the extracted attribute value.
+ """
+
+ try:
+ result = getattr(data, self.attr_name)
+ except AttributeError as err:
+ raise AttributeError(f"Attribute {self.attr_name} not found in {type(data)=}") from err
+
+ return data, cases, result
+
+
+class Average(GenericOperation):
+ """
+ Represents an averaging operation on simulation results.
+
+ This operation calculates the average of a given data set over a specified range of steps, time,
+ or fraction of the dataset.
+
+ Raises
+ ------
+ NotImplementedError
+ If the method of averaging (e.g., step-based or time-based) is not implemented or the data type is unsupported.
+
+ Example
+ -------
+ avg = Average(fraction=0.1)
+ result = avg.calculate(data, case, cases, variables, new_variable_name)
+ """
+
+ start_step: Optional[pd.NonNegativeInt] = pd.Field(
+ None,
+ description="The starting step for averaging. If not specified, averaging starts from the beginning.",
+ )
+ end_step: Optional[pd.NonNegativeInt] = pd.Field(
+ None,
+ description="The ending step for averaging. If not specified, averaging continues to the end.",
+ )
+ start_time: Optional[pd.NonNegativeFloat] = pd.Field(
+ None,
+ description="The starting time for averaging. If not specified, averaging starts from the beginning.",
+ )
+ end_time: Optional[pd.NonNegativeFloat] = pd.Field(
+ None,
+ description="The ending time for averaging. If not specified, averaging continues to the end.",
+ )
+ fraction: Optional[pd.PositiveFloat] = pd.Field(
+ None,
+ le=1,
+ description="The fraction of the dataset to be averaged, ranging from 0 to 1."
+ + " Only the fraction-based method is implemented.",
+ )
+ type_name: Literal["Average"] = pd.Field("Average", frozen=True)
+
+ model_config = pd.ConfigDict(
+ conflicting_fields=[
+ Conflicts(field1="start_step", field2="start_time"),
+ Conflicts(field1="start_step", field2="fraction"),
+ Conflicts(field1="start_time", field2="fraction"),
+ Conflicts(field1="end_step", field2="end_time"),
+ Conflicts(field1="end_step", field2="fraction"),
+ Conflicts(field1="end_time", field2="fraction"),
+ ],
+ require_one_of=["start_step", "start_time", "fraction"],
+ )
+
+ def calculate(
+ self, data, case, cases, variables, new_variable_name
+ ): # pylint: disable=too-many-arguments
+ """
+ Performs the averaging operation on the provided data.
+ """
+ if isinstance(data, case_results.ResultCSVModel):
+ if self.fraction is None:
+ raise NotImplementedError('Only "fraction" average method implemented.')
+ averages = data.get_averages(average_fraction=self.fraction)
+ return data, cases, averages[new_variable_name]
+
+ raise NotImplementedError(
+ f"{self.__class__.__name__} not implemented for data type: {type(data)=}"
+ )
+
+
+class Variable(Flow360BaseModel):
+ """
+ Variable model used in expressions
+ """
+
+ name: str = pd.Field(description="Name of the variable.")
+ data: str = pd.Field(description="Data contained within the variable.")
+
+
+class Expression(GenericOperation):
+ """
+ Represents a mathematical expression to be evaluated on simulation result data.
+
+ This operation allows for defining and calculating custom expressions using
+ variables extracted from simulation results. The results of the expression
+ evaluation can be added as a new column to a dataframe for further analysis.
+
+ Example
+ -------
+ expr = Expression(expr="totalCD * area")
+ result = expr.calculate(data, case, cases, variables, new_variable_name)
+
+ Raises
+ ------
+ ValueError
+ If variables in the expression are missing from the dataframe or if the
+ expression cannot be evaluated due to syntax or other issues.
+ NotImplementedError
+ If the data type is unsupported by the `calculate` method.
+ """
+
+ expr: str = pd.Field(
+ description="The mathematical expression to evaluate. It should be written in a syntax compatible"
+ + " with the `numexpr` library, using variable names that correspond to"
+ + " columns in the dataframe or user-defined variables."
+ )
+ type_name: Literal["Expression"] = pd.Field("Expression", frozen=True)
+
+ @classmethod
+ def get_variables(cls, expr):
+ """
+ Parses the given expression and returns a set of variable names used in it.
+ """
+ tree = ast.parse(expr, mode="eval")
+
+ class VariableVisitor(ast.NodeVisitor):
+ """
+ A custom NodeVisitor class that visits nodes in an abstract syntax tree (AST)
+ to collect variable names that are not part of known functions.
+ """
+
+ # pylint: disable=invalid-name
+ def __init__(self):
+ self.variables = set()
+ self.known_functions = {name for name in dir(math) if callable(getattr(math, name))}
+
+ def visit_Name(self, node):
+ """
+ Visit a Name node and add the variable name to the variables set if it's not
+ a known function.
+
+ Args:
+ node (ast.Name): The Name node to visit.
+ """
+
+ if isinstance(node.ctx, ast.Load) and node.id not in self.known_functions:
+ self.variables.add(node.id)
+
+ def visit_Call(self, node):
+ """
+ Visit a Call node and recursively visit its arguments and keyword arguments
+ to find any additional variable names.
+
+ Args:
+ node (ast.Call): The Call node to visit.
+ """
+ for arg in node.args:
+ self.visit(arg)
+ for keyword in node.keywords:
+ self.visit(keyword.value)
+
+ visitor = VariableVisitor()
+ visitor.visit(tree)
+
+ return visitor.variables
+
+ @classmethod
+ def evaluate_expression(
+ cls, df, expr, variables: List[Variable], new_variable_name, case
+ ): # pylint: disable=too-many-arguments
+ """
+ Evaluates the given expression on the provided dataframe, using the specified variables.
+ The result is added as a new column in the dataframe.
+ """
+
+ import numexpr as ne # pylint: disable=import-outside-toplevel
+
+ expr_variables = cls.get_variables(expr)
+ missing_vars = expr_variables - set(df.columns)
+ found_variables = set()
+ for missing_var in missing_vars:
+ try:
+ if variables is not None:
+ for v in variables:
+ if missing_var == v.name:
+ df[missing_var] = data_from_path(case, v.data)
+ found_variables.add(missing_var)
+ except (ValueError, KeyError) as e:
+ log.warning(e)
+ missing_vars -= found_variables
+ if missing_vars:
+ raise ValueError(
+ f"The following variables are missing in the dataframe: {', '.join(missing_vars)}"
+ )
+
+ local_dict = {var: df[var].values for var in expr_variables}
+ try:
+ result = ne.evaluate(expr, local_dict)
+ except Exception as e:
+ raise ValueError(f"Error evaluating expression: {e}") from e
+
+ df[new_variable_name] = result
+ return df
+
+ def calculate(
+ self, data, case, cases, variables, new_variable_name
+ ): # pylint: disable=too-many-arguments
+ """
+ Executes the expression evaluation for the given simulation data and returns the result.
+ """
+ log.debug(f"evaluating expression {self.expr}, {case.id=}")
+
+ if isinstance(data, case_results.ResultCSVModel):
+ df = self.evaluate_expression(
+ data.as_dataframe(), self.expr, variables, new_variable_name, case
+ )
+ data.update(df)
+ return data, cases, data.values[new_variable_name]
+
+ raise NotImplementedError(
+ f"{self.__class__.__name__} not implemented for data type: {type(data)=}"
+ )
+
+
+OperationTypes = Annotated[
+ Union[Average, Expression, GetAttribute], pd.Field(discriminator="type_name")
+]
+
+
+# pylint: disable=no-member
+class DataItem(Flow360BaseModel):
+ """
+ Represents a retrievable data item that can be post-processed.
+
+ The `DataItem` class retrieves data from a specified path within a `Case` and allows for:
+ - Excluding specific boundaries (if applicable).
+ - Applying one or more post-processing operations (e.g., mathematical expressions, averaging).
+ Averaging should be applied as the last expression, accessing variables through `/averages` in path will
+ automatically append an averaging operation to the object's operations.
+ - Introducing additional variables for use in these operations.
+ """
+
+ data: str = pd.Field(
+ description="Path to the data item to retrieve from a `Case`."
+ + ' The path can include nested attributes and dictionary keys (e.g., "results.surface_forces").'
+ )
+ title: Optional[str] = pd.Field(
+ None,
+ description="A human-readable title for this data item."
+ + " If omitted, the title defaults to the last component of the `data` path.",
+ )
+ include: Optional[List[str]] = pd.Field(
+ None,
+ description="Boundaries to be included in the retrieved data (e.g., certain surfaces)."
+ + " Only applicable to some data types, such as surface forces or slicing force distributions.",
+ )
+ exclude: Optional[List[str]] = pd.Field(
+ None,
+ description="Boundaries to be excluded from the retrieved data (e.g., certain surfaces)."
+ + " Only applicable to some data types, such as surface forces or slicing force distributions.",
+ )
+ operations: Optional[List[OperationTypes]] = pd.Field(
+ None,
+ description="A list of operations to apply to the retrieved data."
+ + " Supported operations include: `Expression` and `Average`.",
+ )
+ variables: Optional[List[Variable]] = pd.Field(
+ None,
+ description="Additional user-defined variables that may be referenced in the `Expression` operations.",
+ )
+ type_name: Literal["DataItem"] = pd.Field("DataItem", frozen=True)
+
+ @pd.model_validator(mode="before")
+ @classmethod
+ def _validate_operations(cls, values):
+ if not isinstance(values, dict):
+ raise ValueError("Invalid input structure.")
+ operations = values.get("operations")
+ if operations is None:
+ values["operations"] = []
+ elif not isinstance(operations, list):
+ values["operations"] = [operations]
+ return values
+
+ @pd.model_validator(mode="after")
+ def _check_for_averages(self):
+ components = split_path(self.data)
+ if "averages" in components:
+ self.operations.append(Average(fraction=0.1))
+ components.remove("averages")
+ self.data = "/".join(components)
+ return self
+
+ def _preprocess_data(self, source, component):
+
+ if isinstance(source, case_results.ResultCSVModel):
+ new_variable_name = "opr_" + uuid.uuid4().hex[:8]
+ if component is not None:
+ self.operations.insert(0, Expression(expr=component))
+ return source, new_variable_name
+
+ raise NotImplementedError(
+ f"{self.__class__.__name__} not implemented for data type: data={self.data}, {type(source)=}"
+ )
+
+ def calculate(self, case: Case, cases: List[Case]) -> float:
+ """
+ Calculates the DataItem values based on specified operations.
+
+ Parameters
+ ----------
+ case : Case
+ The target case for which the delta is calculated.
+ cases : List[Case]
+ A list of available cases, including the reference case.
+
+ Returns
+ -------
+ float
+ The computed data array.
+
+ """
+
+ source, component = results_from_path(case, self.data)
+
+ if isinstance(source, base_results.ResultCSVModel):
+ if self.exclude is not None or self.include is not None:
+ if isinstance(source, case_results.PerEntityResultCSVModel):
+ source.filter(include=self.include, exclude=self.exclude)
+ else:
+ raise AttributeError(
+ "Include and exclude can be used only with some data types,"
+ + " such as surface forces or slicing force distributions."
+ )
+ source, new_variable_name = self._preprocess_data(source=source, component=component)
+ if len(self.operations) > 0:
+ for opr in self.operations: # pylint: disable=not-an-iterable
+ source, cases, result = opr.calculate(
+ source, case, cases, self.variables, new_variable_name
+ )
+ return result
+
+ return source
+
+ raise NotImplementedError(
+ f"{self.__class__.__name__} not implemented for data type: {type(source)=}"
+ )
+
+ def __str__(self):
+ if self.title is not None:
+ return self.title
+ return path_variable_name(self.data)
+
+
+class Delta(Flow360BaseModel):
+ """
+ Represents a delta calculation between a reference case and a target case based on specified data.
+ """
+
+ data: Union[str, DataItem] = pd.Field(
+ description="Path to the data item used for delta calculation."
+ )
+ ref_index: Optional[pd.NonNegativeInt] = pd.Field(
+ 0, description="Index of the reference case in the list of cases for comparison."
+ )
+ type_name: Literal["Delta"] = pd.Field("Delta", frozen=True)
+
+ def calculate(self, case: Case, cases: List[Case]) -> float:
+ """
+ Calculates the delta between the specified case and the reference case.
+
+ Parameters
+ ----------
+ case : Case
+ The target case for which the delta is calculated.
+ cases : List[Case]
+ A list of available cases, including the reference case.
+
+ Returns
+ -------
+ float
+ The computed delta value between the case and reference case data.
+
+ Raises
+ ------
+ ValueError
+ If `ref_index` is out of bounds or `None`, indicating a missing reference.
+ """
+
+ if self.ref_index is None or self.ref_index >= len(cases):
+ return "Ref not found."
+ ref = cases[self.ref_index]
+ case_result = data_from_path(case, self.data)
+ ref_result = data_from_path(ref, self.data)
+ return case_result - ref_result
+
+ def __str__(self):
+ if isinstance(self.data, str):
+ data_str = path_variable_name(self.data)
+ else:
+ data_str = str(self.data)
+ return f"Delta {data_str}"
+
+
+# pylint: disable=too-few-public-methods
+class Tabulary(Tabular):
+ """
+ The `tabulary` package works better than the existing pylatex implementations so this includes it in pylatex
+ """
+
+ packages = [Package("tabulary")]
+
+ def __init__(self, *args, width_argument=NoEscape(r"\linewidth"), **kwargs):
+ """
+ Args
+ ----
+ width_argument:
+ The width of the table. By default the table is as wide as the
+ text.
+ """
+ super().__init__(*args, start_arguments=width_argument, **kwargs)
+
+
+class Grouper(Flow360BaseModel):
+ """
+ Class for objects responsible for grouping data into series in Chart2D.
+
+ Example
+ -------
+ - Data will be grouped by each turbulence model and then by the first tag,
+ if the first tag is "a" or "b" the data point will be assigned to group "bucket0",
+ if the first tag is "c" the data point will be assigned to "bucket1"
+
+ >>> Grouper(
+ ... group_by=["params/models/Fluid/turbulence_model_solver/type_name", "info/tags/0"],
+ ... buckets=[None, {"bucket0": ["a", "b"], "bucket1": ["c"]}],
+ ... )
+
+ ====
+ """
+
+ group_by: Union[str, List[str], None, List[None]] = pd.Field(
+ description="The path to the data attribute (or paths to attributes in case of multi-level grouping)"
+ + " by which the grouping should be done."
+ )
+ buckets: Optional[Union[dict[str, List], List[Union[dict[str, List], None]]]] = pd.Field(
+ None,
+ description="Dictionaries where key represents the name of the group and value is the list of values,"
+ + " that belong to the group. If all the values should be unique, enter None for the corresponding bucket.",
+ )
+ _series_assignments: List[List[str]] = pd.PrivateAttr(default=None)
+
+ @pd.model_validator(mode="after")
+ def _handle_singular_inputs(self):
+ if not isinstance(self.group_by, List):
+ self.group_by = [self.group_by]
+ if not isinstance(self.buckets, List):
+ self.buckets = [self.buckets] * len(self.group_by)
+ return self
+
+ @pd.model_validator(mode="after")
+ def _check_argument_lengths(self):
+ if self.buckets is not None and len(self.group_by) != len(self.buckets):
+ raise pd.ValidationError(
+ "group_by and buckets must be the same length. "
+ + "If a category should not be grouped into buckets enter None in the bucket's place."
+ )
+ return self
+
+ def _get_possible_assignments(self, category, cases):
+ assignments = []
+ for case in cases:
+ assignment = data_from_path(case, category, cases)
+ if assignment not in assignments:
+ assignments.append(assignment)
+ return assignments
+
+ def initialize_arrays(self, cases, y_variables):
+ """
+ Initializes data structures for x_data and y_data.
+ """
+ self._series_assignments = [[path_variable_name(str(y))] for y in y_variables]
+
+ if self.group_by != [None]:
+ for category, bucket in zip(self.group_by, self.buckets):
+ if bucket is not None:
+ grouping_attributes = bucket.keys()
+ else:
+ grouping_attributes = self._get_possible_assignments(category, cases)
+
+ new_assignments = []
+ for assignment in self._series_assignments:
+ for attribute in grouping_attributes:
+ new_assignments.append(assignment + [attribute])
+
+ self._series_assignments = new_assignments
+
+ x_data = [[] for _ in range(len(self._series_assignments))]
+ y_data = [[] for _ in range(len(self._series_assignments))]
+ return x_data, y_data
+
+ # pylint: disable=inconsistent-return-statements
+ def _is_in_bucket(self, bucket_criteria, attribute) -> bool:
+ for criterion in bucket_criteria:
+ if attribute == criterion:
+ return True
+ if callable(criterion):
+ crit_result = criterion(attribute)
+ if isinstance(crit_result, bool):
+ return crit_result
+ raise AttributeError(
+ f"Bucket criterion must return bool, current returned is {type(crit_result)}."
+ )
+
+ # pylint: disable=too-many-arguments
+ def arrange_data(self, case, x_data, y_data, x_data_point, y_data_point, y_variable):
+ """
+ Sorts the data into appropriate series based on the case.
+ """
+
+ point_attributes = [path_variable_name(str(y_variable))]
+
+ if self.group_by != [None]:
+ for category, bucket in zip(self.group_by, self.buckets):
+ attribute = data_from_path(case, category)
+ if bucket is not None:
+ for key, value in bucket.items():
+ if self._is_in_bucket(value, attribute):
+ point_attributes.append(key)
+ else:
+ point_attributes.append(attribute)
+
+ for idx, assignment in enumerate(self._series_assignments):
+ if point_attributes == assignment:
+ x_data[idx].append(x_data_point)
+ y_data[idx].append(y_data_point)
+ return x_data, y_data
+
+ return x_data, y_data
+
+ def arrange_legend(self):
+ """
+ Creates the legend for the defined grouping.
+ """
+ legend = []
+ assignments = self._series_assignments.copy()
+
+ assignments_array = np.array(assignments)
+ if np.all(assignments_array[:, 0] == assignments_array[0, 0]):
+ assignments = assignments_array[:, 1:].tolist()
+
+ if assignments is None:
+ return None
+
+ for assignment in assignments:
+ legend.append(" - ".join(assignment))
+
+ return legend
+
+
+def generate_colorbar_from_image(
+ image_filename=os.path.join(here, "img", "colorbar_rainbow_banded_30.png"),
+ limits: Tuple[float, float] = (0, 1),
+ field_name: str = "Field",
+ output_filename="colorbar_with_ticks.png",
+ height_px=25,
+ is_log_scale=False,
+): # pylint: disable=too-many-arguments,too-many-locals
+ """
+ Generate a color bar image from an existing PNG file with ticks and labels.
+
+ This function reads a colormap from a provided PNG file (a horizontal strip of
+ colors), and overlays ticks and labels according to the specified value limits
+ and scale type (linear or logarithmic).
+
+ For a linear scale, matplotlib automatically chooses the number and format of
+ ticks. For a log scale, a twin axis is used for proper tick placement without
+ distorting the color distribution.
+
+ Parameters
+ ----------
+ image_filename : str
+ Path to the colormap PNG file (horizontal strip).
+ limits : tuple of float
+ A tuple (min_value, max_value) specifying the data range.
+ If `is_log_scale` is True, `max_value` must be greater than 0.
+ field_name : str
+ The field name for the label.
+ output_filename : str
+ The output filename for the resulting image with ticks.
+ height_px : int
+ The height in pixels for the color bar image.
+ is_log_scale : bool
+ If True, use a log scale axis for ticks and minor ticks.
+
+ Returns
+ -------
+ None
+ The resulting image is saved to `output_filename`.
+
+ Notes
+ -----
+ - On a log scale, the main colorbar axis remains linear to avoid deforming
+ the color distribution. A twin axis is used solely for log-scale labeling.
+ """
+
+ import matplotlib.pyplot as plt # pylint: disable=import-outside-toplevel
+ from matplotlib.ticker import ( # pylint: disable=import-outside-toplevel
+ LogFormatterSciNotation,
+ )
+ from PIL import Image # pylint: disable=import-outside-toplevel
+
+ img = Image.open(image_filename)
+ original_width, _ = img.size
+ new_size = (original_width, height_px)
+ img_resized = img.resize(new_size, Image.LANCZOS) # pylint: disable=no-member
+ img_array = np.array(img_resized)
+
+ dpi = 200
+ width_inch = new_size[0] / dpi * 4
+ height_inch = height_px / dpi
+
+ fig, ax = plt.subplots(figsize=(width_inch, height_inch), dpi=dpi)
+
+ min_value = limits[0]
+ max_value = limits[1]
+
+ ax.imshow(img_array, aspect="auto", extent=[min_value, max_value, 0, 1])
+
+ ax.get_yaxis().set_visible(False)
+
+ if is_log_scale:
+ if min_value <= 0:
+ raise ValueError("min_value must be >0 for log scale.")
+
+ ax2 = ax.twiny()
+ ax2.set_xscale("log")
+ ax2.set_xlim(min_value, max_value)
+
+ ax2.xaxis.set_major_formatter(LogFormatterSciNotation())
+ ax2.tick_params(
+ axis="x", which="both", top=True, bottom=False, labeltop=True, labelbottom=False
+ )
+ ax.set_xticks([])
+
+ ax.set_xlabel(field_name, fontsize=10)
+ plt.savefig(output_filename, bbox_inches="tight", pad_inches=0.05)
+ plt.close(fig)
+
+
+font_path = posixpath.join(here, "fonts/").replace("\\", "/")
+font_definition = (
+ r"""
+\setmainfont{TWKEverett}[
+ Path = """
+ + font_path
+ + r""",
+ Extension = .otf,
+ UprightFont = *-Regular,
+ ItalicFont = *-RegularItalic,
+ BoldFont = *-Bold,
+ BoldItalicFont = *-BoldItalic,
+]
+"""
+)
+
+
+def downsample_image_to_relative_width(input_path, output_path, relative_width=1.0, dpi=150):
+ """
+ Downsample the image so that when displayed at 'relative_width' fraction of A4 horizontal width,
+ it corresponds approximately to the given DPI.
+
+ Parameters
+ ----------
+ input_path : str
+ Path to the original high-resolution image.
+ output_path : str
+ Path to save the downsampled image.
+ relative_width : float
+ Fraction of the A4 horizontal width (297 mm) the image should occupy.
+ e.g., 1.0 means full width, 0.5 means half the width, etc.
+ dpi : int
+ Desired DPI (pixels per inch).
+ """
+
+ from PIL import Image # pylint: disable=import-outside-toplevel
+
+ a4_width_in_mm = 297.0 # A4 width in mm in landscape orientation
+ mm_per_inch = 25.4
+
+ final_width_inches = (a4_width_in_mm * relative_width) / mm_per_inch
+ desired_pixel_width = final_width_inches * dpi
+
+ img = Image.open(input_path)
+ original_width, original_height = img.size
+
+ scale = desired_pixel_width / original_width
+
+ if scale < 1:
+ new_width = int(round(original_width * scale))
+ new_height = int(round(original_height * scale))
+ img = img.resize((new_width, new_height), Image.LANCZOS) # pylint: disable=no-member
+
+ img.save(output_path)
diff --git a/flow360/plugins/report/uvf_shutter.py b/flow360/plugins/report/uvf_shutter.py
new file mode 100644
index 000000000..513325607
--- /dev/null
+++ b/flow360/plugins/report/uvf_shutter.py
@@ -0,0 +1,964 @@
+"""
+This module is responsible for communicating with UVF-shutter service
+"""
+
+import asyncio
+import json
+import os
+import reprlib
+import time
+import zipfile
+from collections import defaultdict
+from functools import wraps
+from typing import Callable, List, Literal, Optional, Tuple, Union
+from urllib.parse import urljoin
+
+import pydantic as pd
+
+from flow360.component.simulation.framework.base_model import Flow360BaseModel
+from flow360.environment import Env
+from flow360.exceptions import (
+ Flow360RuntimeError,
+ Flow360WebError,
+ Flow360WebNotFoundError,
+)
+from flow360.log import log
+from flow360.plugins.report.report_context import ReportContext
+
+here = os.path.dirname(os.path.abspath(__file__))
+
+
+class ShutterRequestBaseModel(Flow360BaseModel):
+ """
+ Base model for UVF shutter requests
+ """
+
+
+ShutterObjectTypes = Literal["slices", "qcriterion", "isosurface", "boundaries"]
+
+
+class Resource(Flow360BaseModel):
+ """
+ Resource context for identifying the source of a request.
+
+ Parameters
+ ----------
+ path_prefix : str
+ Prefix with identifier for the user initiating the request.
+ id : str
+ Identifier for the case associated with the request.
+ """
+
+ path_prefix: str
+ id: str
+ type: str = "case"
+
+ model_config = Flow360BaseModel.model_config.copy()
+ model_config.update({"frozen": True})
+
+
+class Resolution(Flow360BaseModel):
+ """
+ Screen resolution settings.
+
+ Parameters
+ ----------
+ width : int, default=1920
+ Width of the resolution in pixels.
+ height : int, default=1080
+ Height of the resolution in pixels.
+ """
+
+ width: pd.PositiveInt = 1920
+ height: pd.PositiveInt = 1080
+
+
+class Settings(Flow360BaseModel):
+ """
+ Configuration settings for a scene.
+
+ Parameters
+ ----------
+ resolution : Resolution
+ Resolution settings for the scene.
+ """
+
+ resolution: Resolution = Resolution()
+
+ model_config = Flow360BaseModel.model_config.copy()
+ model_config.update({"frozen": True})
+
+
+class SetObjectVisibilityPayload(Flow360BaseModel):
+ """
+ Payload for setting the visibility of objects.
+
+ Parameters
+ ----------
+ object_ids : List[UvfObjectTypes]
+ List of object identifiers for which visibility will be set.
+ visibility : bool
+ Boolean indicating the visibility state.
+ """
+
+ object_ids: List[Union[ShutterObjectTypes, str]]
+ visibility: bool
+
+
+class SetColormapPayload(Flow360BaseModel):
+ """
+ SetColormapPayload
+ """
+
+ type: Literal["Rainbow"] = "Rainbow"
+ steps: Optional[
+ List[float]
+ ] # eg: [0, 0.25, 0.5, 0.75, 1.0], // Always sorted before use, 0 and 1 implicitly added if not specified
+
+
+class SetFieldPayload(Flow360BaseModel):
+ """
+ Payload for setting field parameters on an object.
+
+ Parameters
+ ----------
+ object_id : ShutterObjectTypes
+ Identifier of the object for field setting.
+ field_name : str
+ Name of the field to modify.
+ min_max : Tuple[float, float]
+ Minimum and maximum values for the field.
+ """
+
+ object_id: ShutterObjectTypes
+ field_name: str
+ min_max: Tuple[float, float]
+ is_log_scale: bool
+ # colormap: Optional[SetColormapPayload] = None
+
+
+class TakeLegendScreenshotPayload(Flow360BaseModel):
+ """
+ Payload for taking a legend screenshot.
+
+ This payload is used to capture just the legend (color scale, range, and optional title) for
+ the specified object (e.g., slice, boundary). The legend is saved as an image file.
+
+ Parameters
+ ----------
+ object_id : ShutterObjectTypes
+ Identifier of the object whose legend will be captured.
+ file_name : str
+ The name of the output screenshot file, aliased as "filename".
+ type : str, default="png"
+ Image format for the legend screenshot.
+ width : int, default=400
+ Width of the screenshot in pixels.
+ height : int, default=60
+ Height of the screenshot in pixels.
+ title : str, optional
+ Title to display on the legend. If omitted, the default is the field name being visualized.
+ """
+
+ object_id: ShutterObjectTypes
+ file_name: str = pd.Field(alias="filename")
+ type: str = "png"
+ width: Optional[pd.PositiveInt] = 400
+ height: Optional[pd.PositiveInt] = 60
+ title: Optional[str] = None
+
+
+class SetLICPayload(Flow360BaseModel):
+ """
+ Payload for setting the visibility of objects.
+
+ Parameters
+ ----------
+ object_id : ShutterObjectTypes
+ Object identifier for which LIC will be set.
+ visibility : bool
+ Boolean indicating the visibility state.
+ """
+
+ object_id: str
+ visibility: bool
+
+
+class Camera(Flow360BaseModel):
+ """
+ Represents the camera configuration payload.
+ """
+
+ position: Optional[Tuple[float, float, float]] = pd.Field(
+ (-1, -1, 1),
+ description="Camera eye position, think of the eye position as a position on the unit sphere"
+ + " centered at the `lookAt`. The units are in length units used in geometry or volume mesh.",
+ )
+ up: Optional[Tuple[float, float, float]] = pd.Field(
+ (0, 0, 1), description="Up orientation of the camera."
+ )
+ look_at: Optional[Tuple[float, float, float]] = pd.Field(
+ None,
+ description="Target point the camera will look at from the position. Default: center of bbox."
+ + " The units are in length units used in geometry or volume mesh.",
+ )
+ pan_target: Optional[Tuple[float, float, float]] = pd.Field(
+ None,
+ description="Position to pan the viewport center to; if undefined, the default is `look_at`."
+ + " The units are in length units used in geometry or volume mesh.",
+ )
+ dimension_dir: Optional[Literal["width", "height", "diagonal"]] = pd.Field(
+ "width",
+ alias="dimensionDirection",
+ description="The direction `dimension_size_model_units` is for.",
+ )
+ dimension: Optional[float] = pd.Field(
+ None,
+ alias="dimensionSizeModelUnits",
+ description="The camera zoom will be set such that the extents of the scene's projection is this number"
+ + " of model units for the applicable `dimension_dir`."
+ + " The units are in length units used in geometry or volume mesh.",
+ )
+ type: Literal["Camera"] = pd.Field("Camera", frozen=True)
+
+
+class TopCamera(Camera):
+ """
+ Camera looking down from above (along +Z).
+ """
+
+ position: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 1.0, 0.0))
+ type: Literal["TopCamera"] = pd.Field("TopCamera")
+
+
+class LeftCamera(Camera):
+ """
+ Camera looking from the positive Y side toward the origin (i.e. along -Y).
+ """
+
+ position: Tuple[float, float, float] = pd.Field((0.0, -1.0, 0.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ type: Literal["LeftCamera"] = pd.Field("LeftCamera")
+
+
+class RearCamera(Camera):
+ """
+ Camera looking from negative X toward the origin (i.e. along +X).
+ """
+
+ position: Tuple[float, float, float] = pd.Field((1.0, 0.0, 0.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ type: Literal["RearCamera"] = pd.Field("RearCamera")
+
+
+class FrontCamera(Camera):
+ """
+ Camera looking from positive X side toward the origin (i.e. along -X).
+ """
+
+ position: Tuple[float, float, float] = pd.Field((-1.0, 0.0, 0.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ type: Literal["FrontCamera"] = pd.Field("FrontCamera")
+
+
+class BottomCamera(Camera):
+ """
+ Camera looking up from below (along -Z).
+ """
+
+ position: Tuple[float, float, float] = pd.Field((0.0, 0.0, -1.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, -1.0, 0.0))
+ type: Literal["BottomCamera"] = pd.Field("BottomCamera")
+
+
+class FrontLeftBottomCamera(Camera):
+ """
+ Camera placed front-left-bottom, diagonally looking at the model.]
+ """
+
+ position: Tuple[float, float, float] = pd.Field((-1.0, -1.0, -1.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ type: Literal["FrontLeftBottomCamera"] = pd.Field("FrontLeftBottomCamera")
+
+
+class RearRightBottomCamera(Camera):
+ """
+ Camera placed rear-right-bottom, diagonally looking at the model.
+ """
+
+ position: Tuple[float, float, float] = pd.Field((1.0, 1.0, -1.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ type: Literal["RearRightBottomCamera"] = pd.Field("RearRightBottomCamera")
+
+
+class FrontLeftTopCamera(Camera):
+ """
+ Camera placed front-left-top, diagonally looking at the model.
+ """
+
+ position: Tuple[float, float, float] = pd.Field((-1.0, -1.0, 1.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ type: Literal["FrontLeftTopCamera"] = pd.Field("FrontLeftTopCamera")
+
+
+class RearLeftTopCamera(Camera):
+ """
+ Camera placed rear-left-top, diagonally looking at the model.
+ """
+
+ position: Tuple[float, float, float] = pd.Field((1.0, -1.0, 1.0))
+ look_at: Tuple[float, float, float] = pd.Field((0.0, 0.0, 0.0))
+ up: Tuple[float, float, float] = pd.Field((0.0, 0.0, 1.0))
+ type: Literal["RearLeftTopCamera"] = pd.Field("RearLeftTopCamera")
+
+
+class SetCameraPayload(Camera):
+ """
+ Alias for Camera
+ """
+
+
+class TakeScreenshotPayload(Flow360BaseModel):
+ """
+ Payload for taking a screenshot.
+
+ Parameters
+ ----------
+ file_name : str
+ Name of the file for saving the screenshot.
+ type : str, default="png"
+ Type of the screenshot file format.
+ """
+
+ file_name: str = pd.Field(alias="filename")
+ type: str = "png"
+
+
+class ResetFieldPayload(Flow360BaseModel):
+ """
+ Payload for resetting a field on an object.
+
+ Parameters
+ ----------
+ object_id : ShutterObjectTypes
+ Identifier of the object for which the field is reset.
+ """
+
+ object_id: ShutterObjectTypes
+
+
+class FocusPayload(Flow360BaseModel):
+ """
+ Payload for focusing camera on an object.
+
+ Parameters
+ ----------
+ object_id : ShutterObjectTypes
+ Identifier of the object for which the field is reset.
+ zoom: pd.PositiveFloat
+ Zoom multiplier can be used to add padding, default 1
+ """
+
+ object_ids: List[Union[ShutterObjectTypes, str]]
+ zoom: Optional[pd.PositiveFloat] = 1
+
+
+ActionTypes = Literal[
+ "focus",
+ "set-object-visibility",
+ "set-field",
+ "set-lic",
+ "reset-field",
+ "set-camera",
+ "take-screenshot",
+ "take-legend-screenshot",
+]
+
+
+class ActionPayload(Flow360BaseModel):
+ """
+ Defines an action to be taken on an object in a scene.
+
+ Parameters
+ ----------
+ action : ACTIONTYPES
+ Type of action to be performed.
+ payload : Optional[Union[SetObjectVisibilityPayload, SetFieldPayload, TakeScreenshotPayload, ResetFieldPayload]]
+ Data required for the specified action.
+ """
+
+ action: ActionTypes
+ payload: Optional[
+ Union[
+ SetObjectVisibilityPayload,
+ SetFieldPayload,
+ TakeScreenshotPayload,
+ TakeLegendScreenshotPayload,
+ ResetFieldPayload,
+ SetCameraPayload,
+ FocusPayload,
+ SetLICPayload,
+ ]
+ ] = None
+
+
+class Scene(Flow360BaseModel):
+ """
+ Represents a scene with specific settings and scripted actions.
+
+ Parameters
+ ----------
+ name : str
+ Name of the scene.
+ settings : Settings
+ Configuration settings for the scene.
+ script : List[ActionPayload]
+ List of actions to execute within the scene.
+ """
+
+ name: str
+ settings: Settings = Settings()
+ script: List[ActionPayload]
+
+
+class ScenesData(Flow360BaseModel):
+ """
+ Data structure holding multiple scenes and associated resource.
+
+ Parameters
+ ----------
+ resource : Resource
+ Resource data related to the source.
+ scenes : List[Scene]
+ List of scenes with actions and settings.
+ """
+
+ resource: Resource
+ scenes: List[Scene]
+
+
+class Flow360WebNotAvailableError(Flow360WebError):
+ """
+ Exception raised when the Flow360 web service is unavailable.
+ """
+
+
+def http_interceptor(func):
+ """
+ Decorator that intercepts HTTP responses and raises appropriate exceptions based on response status.
+ """
+
+ @wraps(func)
+ async def wrapper(*args, **kwargs):
+ """A wrapper function"""
+
+ log.debug(f"call: {func.__name__}({reprlib.repr(args)}, {reprlib.repr(kwargs)})")
+ start_time = time.time()
+
+ async with await func(*args, **kwargs) as resp:
+ log.debug(f"response: {resp}")
+
+ if resp.status == 503:
+ error_message = await resp.json()
+ raise Flow360WebNotAvailableError(f"Web: not available {error_message}")
+
+ if resp.status == 400:
+ error_message = await resp.json()
+ log.debug(f"{error_message=}")
+ raise Flow360WebError(f"Web: Bad request error: {error_message}")
+
+ if resp.status == 404:
+ error_message = await resp.json()
+ raise Flow360WebNotFoundError(f"Web: Not found error: {error_message}")
+
+ if resp.status == 200:
+ end_time = time.time()
+ execution_time = end_time - start_time
+ log.debug(f"UVF Shutter execution time: {execution_time:.4f} seconds")
+
+ try:
+ content_type = resp.headers.get("Content-Type", "")
+ if "application/json" in content_type:
+ result = await resp.json()
+ return result.get("data")
+ data = await resp.read()
+ log.debug("received binary data")
+ return data
+ except Exception as e:
+ log.error(f"Exception occurred while reading response: {e}")
+ raise
+
+ error_message = await resp.text()
+ raise Flow360WebError(f"Web: Unexpected response error: {resp.status}, {error_message}")
+
+ return wrapper
+
+
+def combine(model_a, model_b, key_to_combine, eq: callable):
+ """
+ Combines attributes of two models based on a specified key if they satisfy a given equality condition.
+
+ This function checks if two models are considered equal using the provided `eq` function.
+ If they are equal, it combines the values of the specified attribute (referenced by `key_to_combine`)
+ into a single list, updates the first model with the combined values, and returns the updated model
+ along with a flag indicating that the models were combined.
+
+ Parameters
+ ----------
+ model_a : Any
+ The first model to combine.
+ model_b : Any
+ The second model to combine.
+ key_to_combine : str
+ The name of the attribute in both models to combine.
+ eq : callable
+ A function that takes two models as input and returns `True` if the models are considered equal,
+ `False` otherwise.
+
+ Returns
+ -------
+ tuple
+ A tuple containing:
+ - The updated model (`model_a`) if the models were combined, or the original `model_a` if not.
+ - A boolean flag indicating whether the models were combined (`True`) or not (`False`).
+
+ Raises
+ ------
+ TypeError
+ If the specified attribute (`key_to_combine`) is not a list in both models.
+
+ Example
+ -------
+ >>> model_a = SomeModel(attr=["item1"])
+ >>> model_b = SomeModel(attr=["item2"])
+ >>> eq = lambda a, b: a.some_property == b.some_property
+ >>> combined_model, combined = combine(model_a, model_b, "attr", eq)
+ >>> print(combined_model.attr) # ['item1', 'item2']
+ >>> print(combined) # True
+ """
+
+ if eq(model_a, model_b):
+ attr_a = getattr(model_a, key_to_combine)
+ attr_b = getattr(model_b, key_to_combine)
+
+ if isinstance(attr_a, list) and isinstance(attr_b, list):
+ combined_attr = attr_a + attr_b
+ new_model = model_a.copy(update={key_to_combine: combined_attr})
+ return new_model, True
+ raise TypeError(f"The attribute '{key_to_combine}' is not a list in both models.")
+
+ return model_a, False
+
+
+def make_shutter_context(context: ReportContext):
+ """
+ Extracts relevant data for shutter from context
+ """
+ context_data = {
+ "data_storage": context.data_storage,
+ "url": context.shutter_url,
+ "access_token": context.shutter_access_token,
+ "screenshot_process_function": context.shutter_screenshot_process_function,
+ "process_screenshot_in_parallel": context.process_screenshot_in_parallel,
+ }
+ context_data = {k: v for k, v in context_data.items() if v is not None}
+ return context_data
+
+
+class ShutterBatchService:
+ """
+ Service to collect and process UVF shutter requests.
+ """
+
+ def __init__(self, data_storage=".", shutter_url=None, shutter_access_token=None):
+ self.data_storage = data_storage
+ self.shutter_url = shutter_url
+ self.shutter_access_token = shutter_access_token
+ self.requests = defaultdict(list)
+
+ def _merge_similar_scenes(self, resource, new_scenes):
+ stored_scenes: List[Scene] = self.requests.get(resource, [])
+ for scene in new_scenes:
+ appended = False
+ # pylint: disable=unnecessary-lambda-assignment
+ eq = lambda a, b: a.name == b.name and a.settings == b.settings
+ for i, stored_scene in enumerate(stored_scenes):
+ combined_scene, appended = combine(stored_scene, scene, "script", eq)
+ if appended:
+ stored_scenes[i] = combined_scene
+ break
+ if appended is False:
+ stored_scenes.append(scene.copy())
+ return stored_scenes
+
+ def _merge_visibility_actions(self, actions: List[ActionPayload]) -> List[ActionPayload]:
+ """
+ Merges consecutive 'set-object-visibility' actions with the same 'visibility' value.
+ Does not merge actions if there are other actions (like 'screenshot') in between.
+ """
+ merged_actions = []
+ last_visibility_action = None
+
+ for action in actions:
+ if action.action == "set-object-visibility":
+ payload = action.payload
+ if not isinstance(payload, SetObjectVisibilityPayload):
+ raise TypeError("Payload must be of type SetObjectVisibilityPayload")
+
+ if (
+ last_visibility_action
+ and payload.visibility == last_visibility_action.payload.visibility
+ ):
+ combined_object_ids = set(last_visibility_action.payload.object_ids) | set(
+ payload.object_ids
+ )
+ last_visibility_action.payload.object_ids = list(combined_object_ids)
+ else:
+ if last_visibility_action:
+ merged_actions.append(last_visibility_action)
+ last_visibility_action = action.copy()
+ else:
+ if last_visibility_action:
+ merged_actions.append(last_visibility_action)
+ last_visibility_action = None
+ merged_actions.append(action)
+
+ if last_visibility_action:
+ merged_actions.append(last_visibility_action)
+
+ return merged_actions
+
+ def _remove_redundant_visibility_actions(
+ self, actions: List[ActionPayload]
+ ) -> List[ActionPayload]:
+ """
+ Optimizes 'set-object-visibility' actions by removing redundant actions and sequences.
+
+ Rules:
+ - If a 'set-object-visibility' action with the same 'object_ids' and 'visibility' has already occurred,
+ remove the subsequent duplicate action.
+ - If a sequence of 'set-object-visibility' actions (regardless of other actions in between) is repeated
+ later in the action list with the same 'object_ids' and 'visibility', remove the latter sequence.
+ - Other action types are preserved and ignored in this optimization.
+
+ Note:
+ - This function assumes that the order of actions is important and preserves the order of other actions.
+ """
+ optimized_actions = []
+ visibility_sequence = []
+ current_sequence = []
+
+ for action in actions:
+ if action.action == "set-object-visibility":
+ payload = action.payload
+ if not isinstance(payload, SetObjectVisibilityPayload):
+ raise TypeError("Payload must be of type SetObjectVisibilityPayload")
+ current_sequence.append(action)
+ else:
+ if current_sequence:
+ sequence_key = tuple(
+ (tuple(sorted(a.payload.object_ids)), a.payload.visibility)
+ for a in current_sequence
+ )
+ if sequence_key != visibility_sequence:
+ visibility_sequence = sequence_key
+ optimized_actions.extend(current_sequence)
+ current_sequence = []
+ optimized_actions.append(action)
+
+ if current_sequence:
+ sequence_key = tuple(
+ (tuple(sorted(a.payload.object_ids)), a.payload.visibility)
+ for a in current_sequence
+ )
+ if sequence_key != visibility_sequence:
+ optimized_actions.extend(current_sequence)
+
+ return optimized_actions
+
+ def _remove_redundant_set_field_actions(
+ self, actions: List[ActionPayload]
+ ) -> List[ActionPayload]:
+ """
+ Removes redundant 'set-field' actions when the payload has not changed between calls.
+
+ Rules:
+ - If a 'set-field' action has the same payload as the previous one and no intervening actions affect the field
+ settings,
+ remove the latter 'set-field' action.
+ - Other action types are preserved and ignored in this optimization unless they affect the field settings.
+
+ Note:
+ - This function assumes that the order of actions is important and preserves the order of other actions.
+ """
+ optimized_actions = []
+ last_set_field_payload = None
+
+ field_affecting_actions = {"reset-field", "set-field"}
+
+ for action in actions:
+ if action.action == "set-field":
+ payload = action.payload
+ if not isinstance(payload, SetFieldPayload):
+ raise TypeError("Payload must be of type SetFieldPayload")
+
+ if last_set_field_payload == payload:
+ continue
+ last_set_field_payload = payload
+ elif action.action in field_affecting_actions:
+ last_set_field_payload = None
+ optimized_actions.append(action)
+
+ return optimized_actions
+
+ def add_request(self, request: ScenesData):
+ """
+ Adds a new request to the batch and processes it to optimize actions.
+
+ This method merges the provided request's scenes with any existing scenes for the same resource,
+ ensuring that similar scenes are combined and redundant actions are removed.
+
+ Parameters
+ ----------
+ request : ScenesData
+ The new request containing scenes and associated resource information.
+
+ Processing Steps
+ ----------------
+ 1. Merges similar scenes based on their name and settings.
+ 2. Optimizes scripts within each scene by:
+ - Merging consecutive 'set-object-visibility' actions with the same visibility value.
+ - Removing redundant 'set-object-visibility' actions across the script.
+ - Eliminating redundant 'set-field' actions when the payload is unchanged.
+
+ Raises
+ ------
+ TypeError
+ If an invalid payload type is encountered during processing.
+
+ Example
+ -------
+ >>> resource = Resource(path_prefix="user", id="case1")
+ >>> scenes = [Scene(name="scene1", settings=Settings(), script=[])]
+ >>> request = ScenesData(resource=resource, scenes=scenes)
+ >>> service = ShutterBatchService()
+ >>> service.add_request(request)
+ """
+
+ stored_scenes = self._merge_similar_scenes(request.resource, request.scenes)
+
+ for stored_scene in stored_scenes:
+ stored_scene.script = self._merge_visibility_actions(stored_scene.script)
+
+ for stored_scene in stored_scenes:
+ stored_scene.script = self._remove_redundant_visibility_actions(stored_scene.script)
+
+ for stored_scene in stored_scenes:
+ stored_scene.script = self._remove_redundant_set_field_actions(stored_scene.script)
+
+ self.requests[request.resource] = stored_scenes
+
+ def get_batch_requests(self):
+ """
+ Retrieves all batched requests currently stored in the service.
+
+ This method compiles the collected scenes and their associated resources into a
+ list of `ScenesData` objects, which can be sent to the UVF shutter service for processing.
+
+ Returns
+ -------
+ List[ScenesData]
+ A list of `ScenesData` objects, where each object represents a resource and its
+ associated scenes.
+ """
+
+ return [
+ ScenesData(resource=resource, scenes=scenes)
+ for resource, scenes in self.requests.items()
+ ]
+
+ def process_requests(self, context):
+ """
+ Processes the collected requests by grouping and combining them.
+ """
+ img_files = Shutter(**make_shutter_context(context)).get_images(
+ "None", self.get_batch_requests()
+ )
+ return img_files
+
+
+class Shutter(Flow360BaseModel):
+ """
+ Model representing UVF shutter request data and configuration settings.
+
+ Parameters
+ ----------
+ data_storage : str, default="."
+ Path to the directory where data will be stored.
+ url : str
+ URL endpoint for the shutter service, defaults to "https://shutter-api.{Env.current.domain}".
+ use_cache : bool
+ Whether to force generate data or use cached data
+ process_screenshot_in_parallel : bool
+ Whether to process screenshots concurrently
+ """
+
+ data_storage: str = "."
+ url: str = pd.Field(default_factory=lambda: f"https://shutter-api.{Env.current.domain}")
+ use_cache: bool = True
+ process_screenshot_in_parallel: bool = True
+ access_token: Optional[str] = None
+ screenshot_process_function: Optional[Callable] = None
+
+ # pylint: disable=too-many-locals
+ async def _get_3d_images_api(self, screenshots: dict[str, Tuple]) -> dict[str, list]:
+ try:
+ import backoff # pylint: disable=import-outside-toplevel
+ except ImportError as err:
+ raise RuntimeError(
+ "backoff is not installed. Please install backoff to use this functionality."
+ ) from err
+
+ try:
+ import aiohttp # pylint: disable=import-outside-toplevel
+ except ImportError as err:
+ raise RuntimeError(
+ "aiohttp is not installed. Please install aiohttp to use this functionality."
+ ) from err
+
+ @backoff.on_exception(
+ lambda: backoff.constant(3), Flow360WebNotAvailableError, max_time=3600
+ )
+ @http_interceptor
+ async def _get_image_sequence(
+ session: aiohttp.ClientSession, url: str, shutter_request: list[dict]
+ ) -> str:
+ log.debug(
+ f"sending request to uvf-shutter: {url=}, {type(shutter_request)=}, {len(json.dumps(shutter_request))=}"
+ )
+ return session.post(url, json=shutter_request)
+
+ async with aiohttp.ClientSession(
+ timeout=aiohttp.ClientTimeout(total=3600),
+ headers={"Authorization": f"Bearer {self.access_token}"},
+ ) as session:
+ tasks = []
+ for _, _, shutter_request in screenshots:
+ tasks.append(
+ _get_image_sequence(
+ session=session,
+ url=urljoin(self.url, "/sequence/run"),
+ shutter_request=shutter_request,
+ )
+ )
+ log.debug(f"request to shutter: {json.dumps(shutter_request)}")
+
+ responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+ for response, (_, img_folder, _) in zip(responses, screenshots):
+ if not isinstance(response, Exception):
+ os.makedirs(img_folder, exist_ok=True)
+ zip_file_path = os.path.join(img_folder, "images.zip")
+ with open(zip_file_path, "wb") as f:
+ f.write(response)
+ log.info(f"Zip file saved to {zip_file_path}")
+
+ for response in responses:
+ if isinstance(response, Exception):
+ raise response
+
+ img_files = {}
+ for case_id, img_folder, _ in screenshots:
+ zip_file_path = os.path.join(img_folder, "images.zip")
+ with zipfile.ZipFile(zip_file_path, "r") as zip_ref:
+ zip_ref.extractall(path=img_folder)
+ extracted = zip_ref.namelist()
+ img_files[case_id] = [os.path.join(img_folder, file) for file in extracted]
+ log.info(f"Extracted files: {extracted}")
+
+ return img_files
+
+ async def sequential_screenshot_generator(
+ self, screenshots: List[Tuple], process_function: Optional[Callable]
+ ):
+ """
+ process screenshot sequentially
+ """
+ img_files_generated = {}
+ for screenshot in screenshots:
+ img_files_generated_single_run = await process_function([screenshot])
+ img_files_generated.update(img_files_generated_single_run)
+ return img_files_generated
+
+ # pylint: disable=too-many-branches
+ def get_images(
+ self, fig_name, data: List[ScenesData], regenerate_if_not_found: bool = True
+ ) -> dict[str, List]:
+ """
+ Generates or retrieves cached image files for scenes.
+
+ Parameters
+ ----------
+ fig_name : str
+ The base name for the image file.
+ data : List[ScenesData]
+ A list of scene data objects to generate images for.
+
+ Returns
+ -------
+ dict[str, List[str]]
+ A dictionary with case IDs as keys and lists of image file paths as values.
+ """
+ screenshots = []
+ cached_files = {}
+ for data_item in data:
+ case_id = data_item.resource.id
+ img_folder = os.path.join(self.data_storage, case_id)
+ img_name = fig_name + ".png"
+ img_full_path = os.path.join(img_folder, img_name)
+ if not os.path.exists(img_full_path) or self.use_cache is False:
+ if regenerate_if_not_found is True:
+ screenshots.append(
+ (
+ case_id,
+ img_folder,
+ data_item.model_dump(
+ by_alias=True, exclude_unset=True, exclude_none=True
+ ),
+ )
+ )
+ else:
+ raise Flow360RuntimeError(
+ f"File: {img_name=} not found, shutter generation failed."
+ )
+ else:
+ log.debug(f"File: {img_name=} exists in cache, using.")
+ if case_id not in cached_files:
+ cached_files[case_id] = [img_full_path]
+ else:
+ cached_files[case_id].append(img_full_path)
+
+ img_files_generated = {}
+ if len(screenshots) > 0:
+ if self.screenshot_process_function is not None:
+ process_function = self.screenshot_process_function
+ else:
+ process_function = self._get_3d_images_api
+
+ if self.process_screenshot_in_parallel:
+ img_files_generated = asyncio.run(process_function(screenshots))
+ else:
+ img_files_generated = asyncio.run(
+ self.sequential_screenshot_generator(screenshots, process_function)
+ )
+
+ return {**img_files_generated, **cached_files}
diff --git a/poetry.lock b/poetry.lock
index b6e216d46..c0986a714 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -837,7 +837,7 @@ files = [
{file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"},
{file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
]
-markers = {dev = "sys_platform == \"win32\" or platform_system == \"Windows\""}
+markers = {dev = "platform_system == \"Windows\" or sys_platform == \"win32\""}
[[package]]
name = "colorful"
@@ -3708,6 +3708,21 @@ files = [
sphinx = ">=6"
tomli = {version = ">=1.1.0", markers = "python_version < \"3.11\""}
+[[package]]
+name = "ordered-set"
+version = "4.1.0"
+description = "An OrderedSet is a custom MutableSet that remembers its order, so that every"
+optional = false
+python-versions = ">=3.7"
+groups = ["main"]
+files = [
+ {file = "ordered-set-4.1.0.tar.gz", hash = "sha256:694a8e44c87657c59292ede72891eb91d34131f6531463aab3009191c77364a8"},
+ {file = "ordered_set-4.1.0-py3-none-any.whl", hash = "sha256:046e1132c71fcf3330438a539928932caf51ddbc582496833e23de611de14562"},
+]
+
+[package.extras]
+dev = ["black", "mypy", "pytest"]
+
[[package]]
name = "overrides"
version = "7.7.0"
@@ -4370,6 +4385,29 @@ files = [
[package.extras]
windows-terminal = ["colorama (>=0.4.6)"]
+[[package]]
+name = "pylatex"
+version = "1.4.2"
+description = "A Python library for creating LaTeX files and snippets"
+optional = false
+python-versions = "*"
+groups = ["main"]
+files = [
+ {file = "PyLaTeX-1.4.2.tar.gz", hash = "sha256:bb7b21bec57ecdba3f6f44c856ebebdf6549fd6e80661bd44fd5094236729242"},
+]
+
+[package.dependencies]
+ordered-set = "*"
+
+[package.extras]
+all = ["MarkupSafe (==2.0.1)", "alabaster (<0.7.12)", "black", "coverage", "isort", "jinja2 (<3.0)", "matplotlib", "numpy", "pytest (>=4.6)", "pytest-cov", "quantities", "sphinx", "twine"]
+docs = ["MarkupSafe (==2.0.1)", "alabaster (<0.7.12)", "jinja2 (<3.0)", "sphinx"]
+matplotlib = ["matplotlib"]
+matrices = ["numpy"]
+packaging = ["twine"]
+quantities = ["numpy", "quantities"]
+testing = ["black", "coverage", "isort", "pytest (>=4.6)", "pytest-cov"]
+
[[package]]
name = "pylint"
version = "3.3.7"
@@ -4418,14 +4456,13 @@ diagrams = ["jinja2", "railroad-diagrams"]
[[package]]
name = "pyperclip"
-version = "1.11.0"
+version = "1.9.0"
description = "A cross-platform clipboard module for Python. (Only handles plain text for now.)"
optional = false
python-versions = "*"
groups = ["main"]
files = [
- {file = "pyperclip-1.11.0-py3-none-any.whl", hash = "sha256:299403e9ff44581cb9ba2ffeed69c7aa96a008622ad0c46cb575ca75b5b84273"},
- {file = "pyperclip-1.11.0.tar.gz", hash = "sha256:244035963e4428530d9e3a6101a1ef97209c6825edab1567beac148ccc1db1b6"},
+ {file = "pyperclip-1.9.0.tar.gz", hash = "sha256:b7de0142ddc81bfc5c7507eea19da920b92252b548b96186caf94a5e2527d310"},
]
[[package]]
@@ -4907,14 +4944,14 @@ jupyter = ["ipywidgets (>=7.5.1,<9)"]
[[package]]
name = "rich-argparse"
-version = "1.7.2"
+version = "1.7.1"
description = "Rich help formatters for argparse and optparse"
optional = false
python-versions = ">=3.8"
groups = ["main"]
files = [
- {file = "rich_argparse-1.7.2-py3-none-any.whl", hash = "sha256:0559b1f47a19bbeb82bf15f95a057f99bcbbc98385532f57937f9fc57acc501a"},
- {file = "rich_argparse-1.7.2.tar.gz", hash = "sha256:64fd2e948fc96e8a1a06e0e72c111c2ce7f3af74126d75c0f5f63926e7289cd1"},
+ {file = "rich_argparse-1.7.1-py3-none-any.whl", hash = "sha256:a8650b42e4a4ff72127837632fba6b7da40784842f08d7395eb67a9cbd7b4bf9"},
+ {file = "rich_argparse-1.7.1.tar.gz", hash = "sha256:d7a493cde94043e41ea68fb43a74405fa178de981bf7b800f7a3bd02ac5c27be"},
]
[package.dependencies]
@@ -5109,6 +5146,7 @@ files = [
{file = "ruamel.yaml.clib-0.2.12-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f66efbc1caa63c088dead1c4170d148eabc9b80d95fb75b6c92ac0aad2437d76"},
{file = "ruamel.yaml.clib-0.2.12-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:22353049ba4181685023b25b5b51a574bce33e7f51c759371a7422dcae5402a6"},
{file = "ruamel.yaml.clib-0.2.12-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:932205970b9f9991b34f55136be327501903f7c66830e9760a8ffb15b07f05cd"},
+ {file = "ruamel.yaml.clib-0.2.12-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:a52d48f4e7bf9005e8f0a89209bf9a73f7190ddf0489eee5eb51377385f59f2a"},
{file = "ruamel.yaml.clib-0.2.12-cp310-cp310-win32.whl", hash = "sha256:3eac5a91891ceb88138c113f9db04f3cebdae277f5d44eaa3651a4f573e6a5da"},
{file = "ruamel.yaml.clib-0.2.12-cp310-cp310-win_amd64.whl", hash = "sha256:ab007f2f5a87bd08ab1499bdf96f3d5c6ad4dcfa364884cb4549aa0154b13a28"},
{file = "ruamel.yaml.clib-0.2.12-cp311-cp311-macosx_13_0_arm64.whl", hash = "sha256:4a6679521a58256a90b0d89e03992c15144c5f3858f40d7c18886023d7943db6"},
@@ -5117,6 +5155,7 @@ files = [
{file = "ruamel.yaml.clib-0.2.12-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:811ea1594b8a0fb466172c384267a4e5e367298af6b228931f273b111f17ef52"},
{file = "ruamel.yaml.clib-0.2.12-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:cf12567a7b565cbf65d438dec6cfbe2917d3c1bdddfce84a9930b7d35ea59642"},
{file = "ruamel.yaml.clib-0.2.12-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:7dd5adc8b930b12c8fc5b99e2d535a09889941aa0d0bd06f4749e9a9397c71d2"},
+ {file = "ruamel.yaml.clib-0.2.12-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1492a6051dab8d912fc2adeef0e8c72216b24d57bd896ea607cb90bb0c4981d3"},
{file = "ruamel.yaml.clib-0.2.12-cp311-cp311-win32.whl", hash = "sha256:bd0a08f0bab19093c54e18a14a10b4322e1eacc5217056f3c063bd2f59853ce4"},
{file = "ruamel.yaml.clib-0.2.12-cp311-cp311-win_amd64.whl", hash = "sha256:a274fb2cb086c7a3dea4322ec27f4cb5cc4b6298adb583ab0e211a4682f241eb"},
{file = "ruamel.yaml.clib-0.2.12-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:20b0f8dc160ba83b6dcc0e256846e1a02d044e13f7ea74a3d1d56ede4e48c632"},
@@ -5125,6 +5164,7 @@ files = [
{file = "ruamel.yaml.clib-0.2.12-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:749c16fcc4a2b09f28843cda5a193e0283e47454b63ec4b81eaa2242f50e4ccd"},
{file = "ruamel.yaml.clib-0.2.12-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:bf165fef1f223beae7333275156ab2022cffe255dcc51c27f066b4370da81e31"},
{file = "ruamel.yaml.clib-0.2.12-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:32621c177bbf782ca5a18ba4d7af0f1082a3f6e517ac2a18b3974d4edf349680"},
+ {file = "ruamel.yaml.clib-0.2.12-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b82a7c94a498853aa0b272fd5bc67f29008da798d4f93a2f9f289feb8426a58d"},
{file = "ruamel.yaml.clib-0.2.12-cp312-cp312-win32.whl", hash = "sha256:e8c4ebfcfd57177b572e2040777b8abc537cdef58a2120e830124946aa9b42c5"},
{file = "ruamel.yaml.clib-0.2.12-cp312-cp312-win_amd64.whl", hash = "sha256:0467c5965282c62203273b838ae77c0d29d7638c8a4e3a1c8bdd3602c10904e4"},
{file = "ruamel.yaml.clib-0.2.12-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:4c8c5d82f50bb53986a5e02d1b3092b03622c02c2eb78e29bec33fd9593bae1a"},
@@ -5133,6 +5173,7 @@ files = [
{file = "ruamel.yaml.clib-0.2.12-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:96777d473c05ee3e5e3c3e999f5d23c6f4ec5b0c38c098b3a5229085f74236c6"},
{file = "ruamel.yaml.clib-0.2.12-cp313-cp313-musllinux_1_1_i686.whl", hash = "sha256:3bc2a80e6420ca8b7d3590791e2dfc709c88ab9152c00eeb511c9875ce5778bf"},
{file = "ruamel.yaml.clib-0.2.12-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:e188d2699864c11c36cdfdada94d781fd5d6b0071cd9c427bceb08ad3d7c70e1"},
+ {file = "ruamel.yaml.clib-0.2.12-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4f6f3eac23941b32afccc23081e1f50612bdbe4e982012ef4f5797986828cd01"},
{file = "ruamel.yaml.clib-0.2.12-cp313-cp313-win32.whl", hash = "sha256:6442cb36270b3afb1b4951f060eccca1ce49f3d087ca1ca4563a6eb479cb3de6"},
{file = "ruamel.yaml.clib-0.2.12-cp313-cp313-win_amd64.whl", hash = "sha256:e5b8daf27af0b90da7bb903a876477a9e6d7270be6146906b276605997c7e9a3"},
{file = "ruamel.yaml.clib-0.2.12-cp39-cp39-macosx_12_0_arm64.whl", hash = "sha256:fc4b630cd3fa2cf7fce38afa91d7cfe844a9f75d7f0f36393fa98815e911d987"},
@@ -5141,6 +5182,7 @@ files = [
{file = "ruamel.yaml.clib-0.2.12-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e2f1c3765db32be59d18ab3953f43ab62a761327aafc1594a2a1fbe038b8b8a7"},
{file = "ruamel.yaml.clib-0.2.12-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:d85252669dc32f98ebcd5d36768f5d4faeaeaa2d655ac0473be490ecdae3c285"},
{file = "ruamel.yaml.clib-0.2.12-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:e143ada795c341b56de9418c58d028989093ee611aa27ffb9b7f609c00d813ed"},
+ {file = "ruamel.yaml.clib-0.2.12-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:2c59aa6170b990d8d2719323e628aaf36f3bfbc1c26279c0eeeb24d05d2d11c7"},
{file = "ruamel.yaml.clib-0.2.12-cp39-cp39-win32.whl", hash = "sha256:beffaed67936fbbeffd10966a4eb53c402fafd3d6833770516bf7314bc6ffa12"},
{file = "ruamel.yaml.clib-0.2.12-cp39-cp39-win_amd64.whl", hash = "sha256:040ae85536960525ea62868b642bdb0c2cc6021c9f9d507810c0c604e66f5a7b"},
{file = "ruamel.yaml.clib-0.2.12.tar.gz", hash = "sha256:6c8fbb13ec503f99a91901ab46e0b07ae7941cd527393187039aec586fdfd36f"},
@@ -6278,4 +6320,4 @@ docs = ["autodoc_pydantic", "cairosvg", "ipython", "jinja2", "jupyter", "myst-pa
[metadata]
lock-version = "2.1"
python-versions = ">=3.9,<