.. _python_api_reports: .. currentmodule:: flexcompute.flow_report ******* Reports ******* The :ref:`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 :attr:`Report.web_url` and can be edited there, and a report saved in the browser can be loaded from Python with :meth:`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 :doc:`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 ============ .. code-block:: bash 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 :doc:`Installation and Setup ` is all that is required. Import the client from the shared ``flexcompute`` namespace: .. code-block:: python from flexcompute.flow_report import Report Minimal example =============== .. literalinclude:: reports_snippets/minimal_report.py :language: python 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 ================ .. The Flow360 conf.py sets ``autodoc_default_options["members"] = True``, and Sphinx replaces an explicit ``:members:`` list with that default, so members are selected with ``:exclude-members:`` here. The lifecycle methods are documented one by one below with ``automethod``; the nested aliases are documented as their own classes. .. autoclass:: Report :members: :exclude-members: __init__, create, from_cloud, update, refresh, apply_to_new, Summary, Chart, ChartVariable, Visualization, VisualizationSetup, VisualizationView, Camera, Scene All properties are read-only. :attr:`config` is a deep copy: changing it does not change the cloud report. The section classes used by :meth:`create` and :meth:`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`_. .. automethod:: Report.create The four summary sections (one per asset type) are always present; ``sections`` adds visualization and chart sections and customizes the summaries. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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. .. automethod:: Report.from_cloud 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. .. automethod:: Report.update Returns the same object; the report ID and :attr:`~Report.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. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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. .. automethod:: Report.refresh Use it when the report may have changed in the WebUI or in another process. It is not needed after a successful :meth:`~Report.update`. .. automethod:: Report.apply_to_new 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. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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. Section API =========== Section objects map one to one onto the sections described in the :doc:`GUI Guide `. Each class below is also reachable as a nested alias of :class:`Report` (``Report.Summary`` is :class:`~flexcompute.flow_report.spec.ReportSummary`, and so on), which is the spelling used in the examples. .. autoclass:: flexcompute.flow_report.spec.ReportSummary :members: :exclude-members: model_config, model_fields_set, __init__, Config, SchemaConfig Alias: ``Report.Summary``. :meth:`supported_fields` returns the accepted field names for a resource type. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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"``. .. autoclass:: flexcompute.flow_report.spec.ReportChart :members: :exclude-members: model_config, model_fields_set, __init__, Config, SchemaConfig Alias: ``Report.Chart``. :meth:`supported_x_variables` and :meth:`supported_y_variables` list the built-in variables; :meth:`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 :class:`~flexcompute.flow_report.spec.ReportChartVariable`. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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 :class:`~flexcompute.flow_report.spec.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 :class:`~flexcompute.flow_report.spec.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 :class:`~flexcompute.flow_report.spec.ReportChartVariable` values; ``coordinate_x`` and ``coordinate_y`` accept only :class:`~flexcompute.flow_report.spec.ReportChartVariable` values. .. autoclass:: flexcompute.flow_report.spec.ReportChartVariable :members: :exclude-members: model_config, model_fields_set, __init__, Config, SchemaConfig 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: :meth:`csv` and :meth:`udd` select one column of a result CSV file or of a user-defined dynamics output as one Y axis; :meth:`csv_series` and :meth:`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. .. autoclass:: flexcompute.flow_report.spec.ReportVisualization :members: :exclude-members: model_config, model_fields_set, __init__, Config, SchemaConfig Alias: ``Report.Visualization``. One 3D visualization section over resources of a single type. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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 :class:`~flexcompute.flow_report.spec.ReportVisualizationSetup`, a list of them, or the ``visualization_setting`` of a saved :class:`~flexcompute.flow_report.scene.Scene`. At most one manual set-up per output. * - ``camera`` - The shared camera of the linked views: a :class:`~flexcompute.flow_report.spec.ReportCamera` or the ``viewpoint`` of a saved scene. * - ``views`` - Per-resource overrides, keyed by resource ID: a :class:`~flexcompute.flow_report.spec.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. .. autoclass:: flexcompute.flow_report.spec.ReportVisualizationSetup :members: :exclude-members: model_config, model_fields_set, __init__, Config, SchemaConfig 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. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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. .. autoclass:: flexcompute.flow_report.spec.ReportVisualizationView :members: :exclude-members: model_config, model_fields_set, __init__, Config, SchemaConfig Alias: ``Report.VisualizationView``. The ``setup`` and ``camera`` override of one resource inside a :class:`~flexcompute.flow_report.spec.ReportVisualization`. .. autoclass:: flexcompute.flow_report.spec.ReportCamera :members: :exclude-members: model_config, model_fields_set, __init__, Config, SchemaConfig Alias: ``Report.Camera``. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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. 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``. .. autofunction:: get_capabilities .. autofunction:: check_visualization_setup .. autoclass:: flexcompute.flow_report.scene.Scene :members: from_cloud, visualization_setting, viewpoint Alias: ``Report.Scene``. A scene saved in the workbench; its :attr:`visualization_setting` and :attr:`viewpoint` can be passed as the ``setup`` and ``camera`` of a :class:`~flexcompute.flow_report.spec.ReportVisualization` or of one of its ``views``. .. autofunction:: get_agent_guide The same guide is printed by the ``flexcompute-flow-report-guide`` command. 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. .. seealso:: :ref:`User Guide: Reports ` for when to use a report, and :doc:`GUI Guide: Reports ` for the controls each section maps to.