The utl.py module

Summary

Classes

PathFamily

Translate semantic operations into mode-appropriate Fluent paths.

Enums

FamilyKind

Which path family is active in the target session.

Functions

detect_utl_mode	Return True if UTL is currently enabled on backend.
enable_utl	Enable UTL on the live session. Returns True on success.
disable_utl	Disable UTL on the live session. Returns True on success.
translate_prefix	Rewrite path’s family prefix if it matches a known mapping.

Attributes

logger

Constants

UTL_PROBE_PATH
STANDARD_ONLY_ROOTS
UTL_ONLY_ROOTS
UTL_PREFIX_MAP_TO_UTL
UTL_PREFIX_MAP_TO_STANDARD

Description

UTL (Unified Topology Layer) detection, toggling, and path translation.

UTL is a Fluent beta feature that exposes a physics-grouped settings namespace (setup.physics.boundaries,``setup.physics.volumes``, or setup.physics.interfaces) and disables the per-zone namespace (setup.boundary_conditions, or setup.cell_zone_conditions, setup.mesh_interfaces). It is toggled at runtime via the Scheme feature flag:

(enable-feature 'utl)

There is no PyFluent settings-API equivalent for this toggle as of Fluent 27.1 and PyFluent 0.38.1he Ansys-authored UTL regression scripts themselves use solver.execute_tui("(enable-feature 'utl)"). This module isolates that one Scheme call in enable_utl()/disable_utl() and documents the exception. Every other UTL interaction goes through the PyFluent settings API.

The following empirical mapping was extracted from a live probe against Fluent 2027 R1. See _probe_utl.py in the repository root for the raw data.

• Canonical detection signal: solver.settings.setup.physics.is_active().

• When UTL is enabled, the standard families raise InactiveObjectError on write, which is a clean, typed failure the executor surfaces as a validation diagnostic rather than a crash.

• Several surfaces are mode-agnostic (active in both modes): solution.cell_registers, results.surfaces.*, solution.controls.equations, setup.models.*, and the scalar leaves of solution.report_definitions.* (field, report_type, create_report_file, …). Recipes that touch only these surfaces work unchanged in both modes.

• The mode-divergent surfaces collapse to four shapes:

  • Namespace prefix

  • BC-value nesting (.thermal.value versus .value)

  • Value enum casing ('temperature' versus 'Temperature')

  • Selector form on a handful of command arguments (surface_names=[…] versus locations={'physics':[…]})

PathFamily encapsulates all four shapes so a single recipe template can target both modes by calling family helpers rather than hard-coding paths.

Module detail

async utl.detect_utl_mode(backend: Any) → bool | None

Return True if UTL is currently enabled on backend.

Returns None if the backend is not connected or the probe fails (such as against a non-PyFluent backend). Callers should treat None as “unknown — assume standard”.

Parameters:

backendAny

Backend to supply to the function.

Returns:

bool | None

Boolean result produced by the function.

async utl.enable_utl(backend: Any) → bool

Enable UTL on the live session. Returns True on success.

Uses the one sanctioned execute_tui call for the Scheme feature toggle. There is no settings-API equivalent in 27.1.

Parameters:

backendAny

Backend to supply to the function.

Returns:

bool

Boolean result produced by the function.

async utl.disable_utl(backend: Any) → bool

Disable UTL on the live session. Returns True on success.

Parameters:

backendAny

Backend to supply to the function.

Returns:

bool

Boolean result produced by the function.

utl.translate_prefix(path: str, *, to_utl: bool) → str

Rewrite path’s family prefix if it matches a known mapping.

Returns the path unchanged when no mapping applies (such as for paths under solution.*/results.*, which are mode-agnostic, or leaf attribute names that differ in nesting depth and so can’t be rewritten by a simple prefix swap. For those, use PathFamily helpers).

Parameters:

pathstr

Fluent object path or file-system path to inspect.

to_utlbool

Whether to translate the path to UTL.

Returns:

str

String result produced by the function.

utl.UTL_PROBE_PATH = 'setup.physics'

utl.STANDARD_ONLY_ROOTS: tuple[str, Ellipsis] = ('setup.boundary_conditions', 'setup.cell_zone_conditions', 'setup.mesh_interfaces')

utl.UTL_ONLY_ROOTS: tuple[str, Ellipsis] = ('setup.physics.boundaries', 'setup.physics.volumes', 'setup.physics.interfaces')

utl.UTL_PREFIX_MAP_TO_UTL: dict[str, str]

utl.UTL_PREFIX_MAP_TO_STANDARD: dict[str, str]

utl.logger