flow.FlowStudy

flow.FlowStudy(
    name,
    resolution=None,
    *,
    bounds=None,
    size=None,
    bcs=list(),
    reynolds=100.0,
    characteristic_cells=None,
    viscosity=None,
    prandtl=AIR_PRANDTL,
    conductivity_ratio=200.0,
    alpha_max=DEFAULT_ALPHA_MAX,
    epsilon=None,
    profile='smootherstep',
    scheme='exponential',
    expansion=1.0 / 300.0,
    steady=SteadyOptions(),
    energy_tol=1e-10,
    energy_max_steps=4000,
    energy_restart=60,
    domain=None,
)

Declarative conjugate heat transfer in forced convection.

Declared in a scene exactly like :class:~cadjoint.fem.study.ThermalStudy – constructing one inside :func:~cadjoint.studies.capture_studies registers it – but it meshes nothing. The lattice is fixed and the design enters as a field on it, which is why the whole solve stays one differentiable JAX expression.

Attributes

Name	Type	Description
name	str	Study identifier, unique within a scene program.
resolution	Any	Lattice size, an int or an `(NX, NY, NZ)` triplet. The duct axis is `+Y`.
bounds	Any	World coordinates of the lattice’s minimum corner.
size	Any	World extent of the lattice along each axis.
bcs	list[Any]	:class:`Inlet`, :class:`Outlet`, :class:`Walls`, :class:`HeatSource` and :class:`HeldTemperature` conditions. An :class:`Inlet` is required; the rest have defaults.
reynolds	float	Reynolds number against `characteristic_cells`, which together with the inlet speed fixes the lattice viscosity.
characteristic_cells	int \| None	The Reynolds length scale in cells; `None` uses the duct’s `NZ`.
viscosity	float \| None	Kinematic viscosity in lattice units, overriding `reynolds`. Required when the inlet speed is zero, because a Reynolds number does not define a viscosity without a speed.
prandtl	float	Ratio of momentum to thermal diffusivity; the default is air at 300 K.
conductivity_ratio	float	`k_solid / k_fluid`. Aluminium in air is about 8000; see :class:`~cadjoint.flow.energy.EnergyConfig` on why a few hundred is usually the better working point.
alpha_max	float	Brinkman drag at `chi = 1`.
epsilon	float \| None	Interface half-width in world units; `None` uses :meth:`~cadjoint.flow.FlowGrid.suggested_epsilon`.
profile	str	How signed distance is squashed to a solid fraction; see :func:`~cadjoint.flow.solid_fraction`.
scheme	str	Convection-diffusion blend, `"exponential"` or `"upwind"`.
expansion	float	Thermal expansion coefficient `beta` in 1/K, used only to report the :attr:`richardson` number the one-way coupling neglects. The default is an ideal gas at 300 K.
steady	SteadyOptions	Convergence settings for the momentum solve and its adjoint.
energy_tol	float	Relative residual the energy solve stops at.
energy_max_steps	int	Iteration cap for the energy solve.
energy_restart	int	Krylov subspace size for the energy solve. Raise it with `conductivity_ratio`; too small a subspace makes restarted GMRES stagnate and report a badly wrong temperature without failing. See :class:`~cadjoint.flow.energy.EnergyConfig`.
domain	Any	Optional SDF restricting which part of the scene becomes solid; `None` penalises the whole scene.
last_result	FlowStudyResult \| None	The most recent :class:`FlowStudyResult`.

Raises

Name	Type	Description
	ValueError	On a missing or duplicated boundary condition, a resolution the lattice cannot use, a viscosity that cannot be derived, or an unknown profile or scheme.

Methods

Name	Description
describe	JSON-ready payload: everything a viewer would need to display it.
energy_config	The energy configuration this study implies.
flow_config	The momentum configuration this study implies.
solve	Sample the scene, converge the flow, then the temperature.

describe

flow.FlowStudy.describe()

JSON-ready payload: everything a viewer would need to display it.

Returns

Name	Type	Description
	FlowStudyDescription	A dictionary whose `kind` is `"flow"`.

energy_config

flow.FlowStudy.energy_config()

The energy configuration this study implies.

Returns

Name	Type	Description
	EnergyConfig	A frozen :class:`~cadjoint.flow.energy.EnergyConfig`.

flow_config

flow.FlowStudy.flow_config()

The momentum configuration this study implies.

Returns

Name	Type	Description
	FlowConfig	A frozen :class:`~cadjoint.flow.FlowConfig`.

Raises

Name	Type	Description
	ValueError	If the inlet does not move, in which case there is no momentum problem to configure.

solve

flow.FlowStudy.solve(sdf=None, *, chi=None)

Sample the scene, converge the flow, then the temperature.

Differentiable end to end in sdf’s parameters: nothing here contours, meshes, or decides membership, and both solves carry implicit adjoints.

Runs under :func:~cadjoint.flow.precision.double_precision and restores the caller’s setting afterwards, so a scene that declares a flow study still compiles to a float32 shader. The design parameters a scene builds at import are float32 when the process is in its default mode; chi is promoted explicitly below rather than relying on the flag having been on when they were made.

A caller who differentiates this must enable x64 process-wide. The scope above covers the forward solve only – jax.grad runs its transposed pass after this returns, and cannot then materialise the float64 intermediates. Same rule as the FEM solvers; see :mod:cadjoint.flow.precision.

Parameters

Name	Type	Description	Default
sdf	Any	A callable on `(..., 3)` points, as :func:`cadjoint.functionalize` produces. Optional when `chi` is given directly.	`None`
chi	Any	A precomputed solid fraction, `(NX, NY, NZ)`, bypassing the sampling step. For tests and for reusing one sampling across several operating points.	`None`

Returns

Name	Type	Description
The	FlowStudyResult	class:`FlowStudyResult`, also stored as `last_result`.

Raises

Name	Type	Description
	ValueError	If neither `sdf` nor `chi` is given, or `chi` does not match the lattice.