Advanced solver controls¶

FluxCore is a complete GPU-native CFD and multiphysics solver. Its typed control objects expose physical models, nonlinear progression, time advancement, GPU-native linear-system solution, multigrid policy, monitoring and result production without exposing the proprietary algorithms beneath them.

Automatic settings are the recommended starting point. Expert controls are available for verification, difficult meshes, time-resolved studies and repeatable production workflows.

Note

FluxCore is not a repackaging of a conventional segregated CPU solver. The simulation path—from equation assembly through convergence assessment and result production—is designed for GPU execution as one coordinated system.

Aggregate configuration¶

class gradientdynamics.fluxcore.AdvancedControls(*, spatial: SpatialControls | None = None, progression: ProgressionControls | None = None, convergence: ConvergenceCriteria | None = None, turbulence: TurbulenceModel | None = None, time: SteadyTimeControls | PhysicalTimeControls | None = None, linear_solvers: LinearSolverSet | None = None, outputs: OutputControls | None = None, rotating_zones: Sequence[RotatingZone] = (), thermal: ThermalControls | None = None, checkpoints: CheckpointControls | None = None, compute: ComputePreference | None = None)¶

Optional expert controls attached to SimulationConfig.

Unspecified groups use FluxCore’s validated automatic policies. The detailed objects are documented under Turbulence models, Time integration, Linear solvers and multigrid and Output and monitoring controls.

classmethod production() → AdvancedControls¶: Create balanced production defaults with automatic stability management, convergence monitoring and checkpointing.

classmethod validation() → AdvancedControls¶: Create stricter reporting and convergence defaults for verification and validation work.

Spatial controls¶

class gradientdynamics.fluxcore.SpatialControls(*, accuracy: str = 'second_order', boundedness: str = 'automatic', gradient_quality: str = 'enhanced', non_orthogonal_handling: str = 'automatic', wall_resolution: str = 'resolved')¶

Accuracy and robustness policy for spatial operators on polyhedral meshes.

accuracy: Literal['first_order', 'second_order']¶: Requested formal spatial accuracy. First order is intended for diagnosis and initialisation, not final production results.

boundedness: Literal['automatic', 'strict', 'low_dissipation']¶: Policy for maintaining physical states near steep gradients and difficult cells.

gradient_quality: Literal['standard', 'enhanced']¶: Gradient accuracy policy for irregular polyhedra and boundary-layer cells.

non_orthogonal_handling: Literal['automatic', 'conservative', 'aggressive']¶: Treatment level for non-orthogonal and skewed cells.

Nonlinear progression¶

class gradientdynamics.fluxcore.ProgressionControls(*, initial_cfl: float = 1.0, target_cfl: float = 100.0, ramp_iterations: int = 500, growth_factor: float = 1.25, retreat_factor: float = 0.5, update_limit: float | None = None, adaptive: bool = True, recovery: str = 'automatic')¶

Controls how a steady or inner transient solve advances from a robust startup state toward high-throughput convergence.

initial_cfl: float¶: Starting pseudo-time Courant number.

target_cfl: float¶: Maximum requested pseudo-time Courant number after successful progression.

ramp_iterations: int¶: Nominal pseudo-iterations over which the target is earned.

growth_factor: float¶: Maximum CFL growth after a successful convergence window.

retreat_factor: float¶: CFL multiplier used after a rejected or unstable update.

adaptive: bool¶: Allow FluxCore to advance or retreat based on observed nonlinear behaviour.

recovery: Literal['automatic', 'strict', 'disabled']¶: Policy when an attempted update does not satisfy stability and progress gates.

Convergence criteria¶

class gradientdynamics.fluxcore.ConvergenceCriteria(*, residual: float = 1e-6, minimum_iterations: int = 100, monitor_window: int = 50, mass_imbalance: float | None = 1e-4, energy_imbalance: float | None = None, force_coefficient_delta: float | None = None, heat_balance: float | None = None, require_all: bool = True)¶

Multi-signal definition of a converged engineering state.

residual: float¶: Normalised equation-residual target.

mass_imbalance: float | None¶: Optional domain mass-balance tolerance.

energy_imbalance: float | None¶: Optional energy-balance tolerance for thermal and CHT workflows.

force_coefficient_delta: float | None¶: Maximum change in a monitored coefficient across the rolling window.

heat_balance: float | None¶: Optional normalised heat-flux balance target across selected interfaces.

require_all: bool¶: Require every enabled criterion rather than residual reduction alone.

Rotating zones¶

class gradientdynamics.fluxcore.RotatingZone(*, zone: str, axis: tuple[float, float, float], angular_speed: float, origin: tuple[float, float, float] = (0.0, 0.0, 0.0), rotating_patches: Sequence[str] = (), stationary_patches: Sequence[str] = ())¶

Moving-reference-frame definition for fans, pumps and turbomachinery.

zone: str¶: Named mesh cell zone.

axis: tuple[float, float, float]¶

angular_speed: float¶: Angular speed in radians per second.

Thermal coupling¶

class gradientdynamics.fluxcore.ThermalControls(*, specific_heat: float | None = None, laminar_prandtl: float = 0.71, turbulent_prandtl: float = 0.85, wall_heat_transfer: str = 'automatic', contact_resistance: Mapping[tuple[str, str], float] | None = None, outer_iterations: int | None = None, outer_tolerance: float | None = None)¶

Fluid energy and multi-region solid-coupling policy.

contact_resistance: Mapping[tuple[str, str], float] | None¶: Optional thermal contact resistance for named region-interface pairs.

outer_iterations: int | None¶: Maximum fluid–solid coupling transactions.

outer_tolerance: float | None¶: Coupled temperature and heat-flux convergence target.

Checkpoints and restart¶

class gradientdynamics.fluxcore.CheckpointControls(*, every_pseudo_steps: int | None = 250, every_physical_steps: int | None = 25, keep_last: int = 2, resume_from: str | Path | None = None, restart_required: bool = False, export_final_state: bool = True)¶

Checkpoint, warm-start and restart policy.

every_pseudo_steps: int | None¶: Checkpoint cadence for steady pseudo-time advancement.

every_physical_steps: int | None¶: Checkpoint cadence for physical-time simulations.

resume_from: str | Path | None¶: Compatible steady or transient state used to initialise the run.

restart_required: bool¶: Fail instead of starting from the default initial state if a requested checkpoint is missing or incompatible.

Compute selection¶

class gradientdynamics.fluxcore.ComputePreference(*, accelerator: str = 'auto', device_count: int | str = 'auto', precision: str = 'automatic', memory_profile: str = 'balanced', partitioning: str = 'automatic')¶

Managed GPU-capacity preference. Availability is organisation-specific.

accelerator: Literal['auto', 'a100', 'h100', 'b200']¶

device_count: int | Literal['auto']¶

memory_profile: Literal['balanced', 'capacity', 'throughput']¶

partitioning: Literal['automatic', 'geometry', 'balanced']¶: High-level distribution policy for supported multi-GPU runs.

Composed example¶

from gradientdynamics.fluxcore import (
    AdvancedControls,
    CheckpointControls,
    ComputePreference,
    ConvergenceCriteria,
    ProgressionControls,
    SpatialControls,
)

advanced = AdvancedControls(
    spatial=SpatialControls(accuracy="second_order", gradient_quality="enhanced"),
    progression=ProgressionControls(
        initial_cfl=1.0,
        target_cfl=200.0,
        ramp_iterations=800,
        adaptive=True,
    ),
    convergence=ConvergenceCriteria(
        residual=1e-7,
        mass_imbalance=1e-5,
        force_coefficient_delta=2e-5,
        monitor_window=100,
    ),
    turbulence=turbulence,
    time=time_controls,
    linear_solvers=linear_solvers,
    outputs=output_controls,
    checkpoints=CheckpointControls(
        every_pseudo_steps=250,
        every_physical_steps=25,
        keep_last=3,
    ),
    compute=ComputePreference(
        accelerator="h100",
        device_count="auto",
        memory_profile="throughput",
    ),
)

The four variables composed above are fully defined on the dedicated API pages. The public surface communicates FluxCore’s depth while its algorithms, GPU kernels, data structures and solver architecture remain proprietary.