Reports

Reports#

The reports built in the WebUI can also be created, loaded, updated and reapplied from Python with the flexcompute-flow-report package. It is a companion package, published separately from flow360, and it operates on the same report resources as the WebUI: a report created from Python opens in the browser at Report.web_url and can be edited there, and a report saved in the browser can be loaded from Python with Report.from_cloud().

The client covers the content of a report: its resources, sections and their settings. Exporting a report to PDF, exporting views as PNG, exporting chart data as CSV and deleting a report remain WebUI operations; see GUI Guide: Reports. The README shipped with the package adds task-oriented guides on saved scenes, visualization capabilities and residual or CFL charts; read it on the PyPI project page.

Installation#

pip install flexcompute-flow-report

The package depends on flow360 25.10.4 or later and installs a compatible client. It uses the active Flow360 environment and credentials, so the setup described in Installation and Setup is all that is required. Import the client from the shared flexcompute namespace:

from flexcompute.flow_report import Report

Minimal example#

import flow360 as fl
from flexcompute.flow_report import Report

baseline = fl.Case(id="case-11111111-1111-1111-1111-111111111111")
variant = fl.Case(id="case-22222222-2222-2222-2222-222222222222")

report = Report.create(
    name="Wing comparison",
    resources=[baseline, variant],
    reference=baseline,
    sections=[
        Report.Summary(resource_type="case"),
        Report.Visualization(),
        Report.Chart(y=["CL", "CD"], comparison="delta"),
    ],
)

print(report.id)
print(report.web_url)

Resources are passed as lightweight references built from their cloud IDs: fl.Case(id=...), fl.Geometry(id=...), fl.SurfaceMesh(id=...) and fl.VolumeMesh(id=...). The client reads the metadata it needs through these references, so calling from_cloud() on them first is unnecessary. Wherever a parameter accepts a resource, it also accepts the resource ID as a string.

Report lifecycle#

class Report[source]#

An interactive Report resource created on the Flow360 platform.

All properties are read-only. config is a deep copy: changing it does not change the cloud report. The section classes used by create() and update() are available as nested aliases, Report.Summary, Report.Chart, Report.ChartVariable, Report.Visualization, Report.VisualizationSetup, Report.VisualizationView, Report.Camera and Report.Scene; see Section API.

property id: str#: Cloud report ID.

property project_id: str | None#: Project ID created for this report.

property name: str#: Report name.

property description: str | None#: Report description.

property tags: list[str]#: Report tags.

property parent_folder_id: str | None#: Parent folder ID.

property workspace_id: str | None#: Workspace containing the report.

property status: str#: Current report generation status.

property viewed: bool | None#: Whether the report has been viewed.

property is_deleted: bool | None#: Whether the report has been deleted.

property associated_resources: list[ReportAssociatedResource]#: Resources associated with this report.

property config: ReportConfig#: A defensive copy of the configuration persisted for this Report.

property config_json: str#: The persisted Report configuration serialized as JSON.

property created_at: datetime | None#: Report creation time.

property updated_at: datetime | None#: Report last update time.

property web_url: str#: Browser URL for this report in the environment where it was created.

classmethod Report.create(*, name, resources, sections=None, reference=None, aliases=None, description='', tags=None, parent_folder_id='ROOT.FLOW360')[source]#

Create an interactive report and return its cloud resource.

AI-generated workflows should load get_agent_guide() before constructing sections. For visualizations, discover every resource’s capabilities and run check_visualization_setup(...) before calling this method.

The four summary sections (one per asset type) are always present; sections adds visualization and chart sections and customizes the summaries.

Parameter	Meaning
`name`	Non-empty report name.
`resources`	The assets of the report, between 1 and 50: `Case`, `Geometry`, `SurfaceMesh` or `VolumeMesh` objects or IDs.
`sections`	Additional or customized sections, see Section API.
`reference`	Reference case. If omitted, the first case is used.
`aliases`	Report-only display names, keyed by resource ID.
`description`	Report description.
`tags`	Tags, trimmed and deduplicated in input order.
`parent_folder_id`	Destination folder ID.

Parameters:

name (str)
resources (Iterable[Case | Geometry | SurfaceMeshV2 | VolumeMeshV2])
sections (Iterable[ReportSummary | ReportVisualization | ReportChart] | None)
reference (Case | str | None)
aliases (Mapping[str, str] | None)
description (str)
tags (Iterable[str] | None)
parent_folder_id (str)

Return type:

Report

classmethod Report.from_cloud(report_id)[source]#

Load an interactive Report from the active Flow360 environment.

Loads an existing report, whether it was created in the WebUI or from Python. The returned object stays bound to the environment that was active when it was loaded.

Parameters:: report_id (str)
Return type:: Report

Report.update(*, resources=None, sections=None, reference=None, aliases=None, name=None, description=None, tags=None, parent_folder_id=None)[source]#

Update this Report in place while preserving its cloud ID and URL.

Returns the same object; the report ID and web_url do not change. Metadata (name, description, tags, parent_folder_id) can be updated on its own. Updating the content requires resources and sections together: the configuration is rebuilt from them rather than patched field by field.

Parameter	Meaning
`resources`	New complete resource set. Requires `sections`.
`sections`	New complete section specification. Requires `resources`.
`reference`	Reference case of the rebuilt configuration.
`aliases`	Aliases of the rebuilt configuration.
`name`	New name; `None` leaves it unchanged.
`description`	New description; `None` leaves it unchanged, `""` clears it.
`tags`	New complete tag list; `None` leaves it unchanged, `[]` clears it.
`parent_folder_id`	New folder ID; `None` leaves it unchanged.

Parameters:

resources (Iterable[Case | Geometry | SurfaceMeshV2 | VolumeMeshV2] | None)
sections (Iterable[ReportSummary | ReportVisualization | ReportChart] | None)
reference (Case | str | None)
aliases (Mapping[str, str] | None)
name (str | None)
description (str | None)
tags (Iterable[str] | None)
parent_folder_id (str | None)

Return type:

Report

Report.refresh()[source]#

Reload this Report’s metadata and persisted configuration.

Use it when the report may have changed in the WebUI or in another process. It is not needed after a successful update().

Return type:: Report

Report.apply_to_new(*, name, resources, reference=None, aliases=None, description='', tags=None, parent_folder_id=None)[source]#

Create a new Report by applying this Report to new cloud resources.

The Python counterpart of the Apply to new header action: the new report has the same sections, layout and display settings applied to a new set of resources. Visualization sections take the first eight matching resources and chart sections the first ten cases, in the order supplied; a per-resource force scope is reset to total because face and body-group IDs cannot be reused across cases.

Parameter	Meaning
`name`	Name of the new report.
`resources`	Resource pool of the new report.
`reference`	Reference case in the new pool.
`aliases`	Display names for the new resources.
`description`	Description of the new report.
`tags`	Tags of the new report.
`parent_folder_id`	Destination folder; `None` reuses the source report’s folder.

Parameters:

name (str)
resources (Iterable[Case | Geometry | SurfaceMeshV2 | VolumeMeshV2])
reference (Case | str | None)
aliases (Mapping[str, str] | None)
description (str)
tags (Iterable[str] | None)
parent_folder_id (str | None)

Return type:

Report

Section API#

Section objects map one to one onto the sections described in the GUI Guide. Each class below is also reachable as a nested alias of Report (Report.Summary is ReportSummary, and so on), which is the spelling used in the examples.

class ReportSummary[source]#

Customize one of the four summary tables included in every report.

Alias: Report.Summary. supported_fields() returns the accepted field names for a resource type.

Parameter	Meaning
`resource_type`	The summary table to customize: `"case"`, `"geometry"`, `"surface_mesh"` or `"volume_mesh"`.
`title`	Custom title.
`fields`	Visible rows. For cases `None` shows the standard subset (the General tab); for the other types it shows every field.
`force_scope`	Force scope of the case summary (`"total"`, `"faces"` or `"body_groups"`); cases only.
`force_scope_ids`	Face or body-group IDs; required with `"faces"` or `"body_groups"`.

resource_type: SummaryResourceType [Required]#

title: str | None = None#

Constraints:

min_length = 1

fields: list[SummaryField] | None = None#

force_scope: ForceScopeMode | None = None#

force_scope_ids: list[str] | None = None#

classmethod supported_fields(resource_type)[source]#

Return the accepted field names for one summary resource type.

Parameters:: resource_type (Literal['geometry', 'surface_mesh', 'volume_mesh', 'case'])
Return type:: tuple[Literal[‘bodies’, ‘patches’, ‘edges’, ‘max_edge_length’, ‘nodes’, ‘triangles’, ‘quadrilaterals’, ‘first_layer_thickness’, ‘tetrahedrons’, ‘prisms’, ‘pyramids’, ‘hexahedrons’, ‘velocity’, ‘alpha’, ‘beta’, ‘turbulence_model’, ‘transition_model’, ‘pseudo_steps’, ‘physical_steps’, ‘area’, ‘oal’, ‘oah’, ‘oaw’, ‘wb’, ‘cl’, ‘cd’, ‘clf’, ‘clr’, ‘cs’, ‘cd_area’], …]

class ReportChart[source]#

Add a 2D chart section using the controls available in the Report UI.

Alias: Report.Chart. supported_x_variables() and supported_y_variables() list the built-in variables; supported_y_variables() returns only the fixed force and moment coefficients (total, pressure and skin-friction parts), never residuals, CFL or result-file columns, which go through ReportChartVariable.

Parameter	Meaning
`title`	Section title.
`resources`	Cases to plot; `None` selects up to 10 report cases.
`x`	X-axis variable: `"alpha"`, `"beta"`, `"velocity"`, `"first_layer_thickness"`, `"surface_max_edge_length"`, `"pseudo_step"`, `"physical_step"`, `"coordinate_x"` or `"coordinate_y"`.
`y`	One to five Y axes, one chart per variable: built-in Y variables or `ReportChartVariable` values.
`comparison`	`"delta"` plots differences to the reference case and cannot be combined with `log_scale`.
`x_range`, `y_ranges`	Manual axis ranges: `(min, max)` for X, a mapping from Y variable to `(min, max)` for Y. `None` is the global auto scaling.
`log_scale`	Logarithmic Y axes.
`style`	`"case"` colors by case and varies the line style by variable; `"variable"` the reverse.
`background_view`	Geometry outline behind coordinate charts: `"coordinate_x"` with `"left"` or `"top"`, `"coordinate_y"` with `"back"` or `"top"`.
`force_scope`, `force_scope_ids`	Force scope of history charts (pseudo or physical step with a force variable), as in `ReportSummary`.
`series`	Members of a metadata-defined series group to show, such as residual components.
`series_display`	How the selected series are drawn: `"individual"`, `"cumulative"` or `"summed"`.

Sweep variables (alpha to surface_max_edge_length) accept the total force coefficients; pseudo_step and physical_step accept force-history variables and ReportChartVariable values; coordinate_x and coordinate_y accept only ReportChartVariable values.

title: str = '2D Chart'#

Constraints:

min_length = 1

resources: list[pd.SkipValidation[CaseResourceSelector]] | None = None#

x: BuiltInChartXVariable = 'alpha'#

y: list[BuiltInChartYVariable | ReportChartVariable] [Optional]#

Constraints:

min_length = 1
max_length = 5

comparison: ChartComparison = 'absolute'#

x_range: tuple[float, float] | None = None#

y_ranges: dict[BuiltInChartYVariable | ReportChartVariable, tuple[float, float]] | None = None#

log_scale: bool = False#

style: ChartStyle = 'case'#

background_view: ChartBackgroundView | None = None#

force_scope: ForceScopeMode | None = None#

force_scope_ids: list[str] | None = None#

series: list[str] | None = None#

series_display: ChartSeriesDisplay | None = None#

classmethod supported_x_variables()[source]#

Return the built-in x-axis variables.

Return type:: tuple[Literal[‘alpha’, ‘beta’, ‘velocity’, ‘first_layer_thickness’, ‘surface_max_edge_length’, ‘pseudo_step’, ‘physical_step’, ‘coordinate_x’, ‘coordinate_y’], …]

classmethod supported_y_variables()[source]#

Return the built-in y-axis variables.

Return type:: tuple[Literal[‘CL’, ‘CD’, ‘CFx’, ‘CFy’, ‘CFz’, ‘CMx’, ‘CMy’, ‘CMz’, ‘CLPressure’, ‘CDPressure’, ‘CFxPressure’, ‘CFyPressure’, ‘CFzPressure’, ‘CMxPressure’, ‘CMyPressure’, ‘CMzPressure’, ‘CLSkinFriction’, ‘CDSkinFriction’, ‘CFxSkinFriction’, ‘CFySkinFriction’, ‘CFzSkinFriction’, ‘CMxSkinFriction’, ‘CMySkinFriction’, ‘CMzSkinFriction’], …]

class ReportChartVariable[source]#

A CSV or user-defined-dynamics variable selected in the Report UI.

Alias: Report.ChartVariable. A Y-axis variable defined by the result metadata of the cases rather than by the fixed list of force coefficients. Prefer the factories over the constructor: csv() and udd() select one column of a result CSV file or of a user-defined dynamics output as one Y axis; csv_series() and udd_series() select the whole series group of such a file, whose members are then picked with Report.Chart(series=[...]). A leading / or results/ in file_name is removed.

source: Literal['csv', 'udd'] = 'csv'#

file_name: str [Required]#

Constraints:

min_length = 1

column: str [Required]#

Constraints:

min_length = 1

classmethod csv(file_name, column)[source]#

Select a CSV output column.

Parameters:

file_name (str)
column (str)

Return type:

ReportChartVariable

classmethod udd(file_name, column)[source]#

Select a user-defined-dynamics output column.

Parameters:

file_name (str)
column (str)

Return type:

ReportChartVariable

classmethod csv_series(file_name)[source]#

Select a metadata-defined series group from a CSV output.

Parameters:: file_name (str)
Return type:: ReportChartVariable

classmethod udd_series(file_name)[source]#

Select a metadata-defined series group from a UDD output.

Parameters:: file_name (str)
Return type:: ReportChartVariable

class ReportVisualization[source]#

Add a configured 3D resource comparison section to a report.

AI-generated workflows should first load get_agent_guide(). Before reusing one setup across resources, obtain each resource’s capabilities and call check_visualization_setup before creating or updating the Report.

Alias: Report.Visualization. One 3D visualization section over resources of a single type.

Parameter	Meaning
`title`	Section title.
`resources`	Up to eight resources of one type. `None` selects the first eight cases, or the first eight resources of the report’s first type when there are no cases.
`layout`	Grid view or `"single"` view with one tab per resource.
`resolution`	Rendering resolution of cases, `"low"` (default) or `"high"`. Meshes and geometries always render at high resolution and reject `"low"`.
`setup`	The linked-view visualization set-up shared by all views: a `ReportVisualizationSetup`, a list of them, or the `visualization_setting` of a saved `Scene`. At most one manual set-up per output.
`camera`	The shared camera of the linked views: a `ReportCamera` or the `viewpoint` of a saved scene.
`views`	Per-resource overrides, keyed by resource ID: a `ReportVisualizationView` or a `{"setup": ..., "camera": ...}` mapping. An overridden view is unlinked from the shared state, like Independent Settings in the WebUI.

The set-up types available per resource type are surface, slice, isosurface and streamline for cases, surface for surface meshes and slice for volume meshes. Geometry views have no set-up controls.

title: str = 'Visualization'#

Constraints:

min_length = 1

resources: list[pd.SkipValidation[ReportResourceSelector]] | None = None#

layout: VisualizationLayout = 'grid'#

resolution: VisualizationResolution | None = None#

setup: list[ReportVisualizationSetup] | SceneVisualizationSetting [Optional]#

camera: ReportCamera | SceneViewpoint | None = None#

views: dict[str, ReportVisualizationView] [Optional]#

class ReportVisualizationSetup[source]#

Configure one surface, slice, isosurface, or streamline output.

Use exact IDs returned by get_capabilities(resource) and check this setup against that resource before creating or updating a Report. Name normalization can suggest candidates but does not produce authoritative IDs.

Alias: Report.VisualizationSetup. Which output to show, how to color it and which entities to display. Output, field and entity names must match the resource’s visualization metadata exactly; use Capability discovery to read them.

Parameter	Meaning
`output`, `type`	Required. Exact output name from the resource metadata, and its category: `"surface"`, `"slice"`, `"isosurface"` or `"streamline"`.
`field`	Field to color by. Required for the field-display parameters below.
`show`, `hide`	Entity IDs to show or hide; an ID cannot appear in both.
`log_scale`, `range`, `color_range`, `theme`, `solid_color`, `show_color_map`, `visualizer`, `unit`, `use_local_value`, `time_frame`	Field display: logarithmic scale, rendering range and color-scale bounds (each defaults to the other when only one is given), color theme, solid color, color-map visibility, the `"lic"` visualizer, display unit, resource-local range and time-frame index.
`clip`, `clip_value`, `clip_range`	Clipping: `"none"`, `"above"`, `"below"` or `"range"`; the threshold for above or below; the `(min, max)` required by `"range"`.
`contour_mode`, `contour_steps`, `contour_line_color`	Contours, `surface` and `slice` only: `"surface"`, `"contours"` or `"both"`; number of steps; line color.
`streamline_direction`, `render_type`, `tube_width`, `tube_width_unit`, `ribbon_width`, `ribbon_width_unit`, `ribbon_angle_scale`	`streamline` only: `"upstream"`, `"downstream"` or `"both"`; `"ribbon"` or `"line"`; tube and ribbon sizing.
`slice_variants`	Slice rendering per entity ID, `"flat"` or `"crinkled"`; `slice` only.
`wireframes`	Wireframe state per entity ID.
`custom_colors`	Custom color map as `(position, "#RRGGBB")` pairs, at least two positions between 0 and 100; only one set-up per section may define it.

output: str [Required]#

Constraints:

min_length = 1

type: VisualizationFieldType [Required]#

field: str | None = None#

Constraints:

min_length = 1

show: list[str] | None = None#

hide: list[str] | None = None#

log_scale: bool | None = None#

range: tuple[float, float] | None = None#

color_range: tuple[float, float] | None = None#

theme: str | None = None#

Constraints:

min_length = 1

contour_mode: Literal['surface', 'contours', 'both'] | None = None#

contour_steps: int | None = None#

Constraints:

gt = 0

contour_line_color: int | None = None#

Constraints:

ge = 0

solid_color: int | None = None#

Constraints:

ge = 0

clip: VisualizationClip | None = None#

clip_value: float | None = None#

clip_range: tuple[float, float] | None = None#

show_color_map: bool | None = None#

streamline_direction: Literal['upstream', 'downstream', 'both'] | None = None#

render_type: Literal['ribbon', 'line'] | None = None#

tube_width: float | None = None#

Constraints:

gt = 0

tube_width_unit: str | None = None#

Constraints:

min_length = 1

ribbon_width: float | None = None#

Constraints:

gt = 0

ribbon_width_unit: str | None = None#

Constraints:

min_length = 1

ribbon_angle_scale: float | None = None#

Constraints:

gt = 0

visualizer: Literal['lic'] | None = None#

unit: str | None = None#

Constraints:

min_length = 1

use_local_value: bool | None = None#

time_frame: int | None = None#

Constraints:

ge = 0

slice_variants: dict[str, Literal['flat', 'crinkled']] | None = None#

wireframes: dict[str, bool] | None = None#

custom_colors: list[tuple[float, str]] | None = None#

Constraints:

min_length = 2

class ReportVisualizationView[source]#

Validated independent state stored for one visualization resource view.

Alias: Report.VisualizationView. The setup and camera override of one resource inside a ReportVisualization.

setup: list[ReportVisualizationSetup] | SceneVisualizationSetting [Optional]#

camera: ReportCamera | SceneViewpoint | None = None#

class ReportCamera[source]#

Camera used by linked views, with optional input units for length values.

Alias: Report.Camera.

Parameter	Meaning
`position`, `look_at`, `pan_target`, `up`	Camera position, target, pan target and up vector, each a 3-tuple of numbers.
`dimension`, `dimension_dir`	Framing dimension (positive number) and its meaning: `"width"`, `"height"` or `"diagonal"`.
`unit`	Unit of the lengths: `"m"`, `"cm"`, `"mm"`, `"inch"` or `"ft"`. For the shared camera `None` means metres; for a per-resource camera `None` means the resource’s model coordinates. A per-resource camera with an explicit unit is converted to model coordinates using the resource’s simulation settings.

position: tuple[float, float, float] | None = None#

look_at: tuple[float, float, float] | None = None#

pan_target: tuple[float, float, float] | None = None#

up: tuple[float, float, float] | None = None#

dimension: float | None = None#

Constraints:

gt = 0

dimension_dir: Literal['width', 'height', 'diagonal'] | None = None#

unit: CameraLengthUnit | None = None#

Capability discovery#

The client does not translate names or validate a set-up against the resource when the report is created, so check them first. All three helpers are importable from flexcompute.flow_report.

get_capabilities(resource)[source]#

Return Manifest-declared visualization capabilities for one resource.

AI-generated workflows should call this function for every selected resource before choosing exact output, field, or visibility-target IDs. See get_agent_guide() for the required cross-resource selection workflow.

Parameters:: resource (Case | Geometry | SurfaceMeshV2 | VolumeMeshV2)
Return type:: ResourceVisualizationCapabilities

check_visualization_setup(setup, capabilities)[source]#

Check exact setup references against one resource’s visualization capabilities.

Run this check for every selected resource before Report.create(...) or a configuration-changing report.update(...). This function performs no network requests and does not mutate or translate the setup. Obtain capabilities separately with get_capabilities() and reuse them for configuration decisions. AI-generated workflows should follow the complete sequence in get_agent_guide().

Parameters:

setup (ReportVisualizationSetup | Sequence[ReportVisualizationSetup] | SceneVisualizationSetting)
capabilities (ResourceVisualizationCapabilities)

Return type:

VisualizationSetupCheckResult

class Scene[source]#

A read-only visualization Scene loaded from the active Flow360 environment.

Alias: Report.Scene. A scene saved in the workbench; its visualization_setting and viewpoint can be passed as the setup and camera of a ReportVisualization or of one of its views.

classmethod from_cloud(scene_id)[source]#

Load a Scene and its visualization setting and viewpoint.

Before applying visualization_setting to multiple resources, obtain each resource’s capabilities and call check_visualization_setup before creating or updating the Report.

Parameters:: scene_id (str)
Return type:: Scene

property id: str#: Cloud Scene ID.

property project_id: str#: Project containing this Scene.

property name: str#: Scene name.

property resource_type: Literal['Case', 'Geometry', 'SurfaceMesh', 'VolumeMesh']#: Resource type from which the Scene setting was captured.

property resource_item_id: str#: Resource ID from which the Scene setting was captured.

property created_by: str#: User ID that created this Scene.

property updated_by: str#: User ID that last updated this Scene.

property created_at: int#: Scene creation timestamp returned by the API.

property updated_at: int#: Scene update timestamp returned by the API.

property visualization_setting: SceneVisualizationSetting#: A defensive copy of the Scene’s Workbench visualization setting.

property viewpoint: SceneViewpoint#: A defensive copy of the Scene’s canonical-metre viewpoint.

get_agent_guide()[source]#

Return the authoritative guide to inject before an AI agent uses this package.

Agent runners should add the returned Markdown to their system or developer instructions before sending the user’s task to the model. Calling this function is deterministic; installing the wheel alone does not make an agent read its docs.

The same guide is printed by the flexcompute-flow-report-guide command.

Return type:: str

Limits#

The limits are those of the WebUI: 1 to 50 resources per report, at most 8 resources of one type per visualization section, at most 10 cases and 1 to 5 Y axes per chart, and a reference that is a case included in the report. Unsupported combinations are rejected before any request is sent.

Reports

Contents

Reports#

Installation#

Minimal example#

Report lifecycle#

Section API#

Capability discovery#

Limits#