NeuralFlow Theory & User Reference Manual › NeuralFlowML Options

NeuralFlowML Options

NeuralFlowML is a solver-trained recurrent Graph Neural Operator (GNO). It does not predict a finished flow field in one pass. Starting from a NeuralFlow state, the learned operator proposes a local correction, the corrected state is returned to the finite-volume solver, and the process is repeated. During training, NeuralFlow residuals and exact Jacobian actions provide the physics feedback.

Theory reference. Each option entry includes a link to the corresponding equation, physical model, closure, or numerical method in the Theory Manual. Defaults, availability, simulation effects, and practical guidance are documented directly with the GUI option.

Learned state. For spatial dimension

, NeuralFlowML currently learns

, so

. Species, turbulence variables, dispersed variables, solid variables and VOF fractions remain in the conventional NeuralFlow path.

The recurrent correction can be written conceptually as .

Activation, mode and device

These controls choose whether NeuralFlowML is used and where its tensor calculations run.

GUI option	Meaning / formulation	Effect on the simulation	Practical guidance	Theory reference
ActiveDefault: Off unless selected	Enables the NeuralFlowML subsystem for the current case.	PhysicsCost When disabled, the normal NeuralFlow CFD solver path is used without NeuralFlowML corrections.	Keep disabled for ordinary CFD cases; enable only after a compatible NeuralFlowML model/setup is ready.	NeuralFlowML execution modes
AI Mode: Inference	Runs the trained NeuralFlowML correction policy without optimizer updates.	CostStability / convergence Applies the learned iterative solver behavior to the current state.	Use with a compatible trained model and verify convergence/residual reduction.	NeuralFlowML execution modes
AI Mode: Training	Enables differentiable rollout and optimizer updates from the physics/converged-solution objectives.	CostInitialization Adds substantial memory/compute cost and changes network weights.	Use only when intentionally training or continuing training.	NeuralFlowML execution modes
AI Mode: CFD	Uses the conventional CFD-solving mode selected in the NeuralFlowML panel context.	Cost Provides the non-training solver path/reference behavior.	Use for baseline/reference solution generation and comparison.	NeuralFlowML execution modes
Device: CPU	Runs NeuralFlowML tensor operations on CPU.	Cost Usually lower setup complexity but slower for large graphs/training.	Useful for small cases, debugging and systems without a supported GPU.	NeuralFlowML execution modes
Device: CUDADefault: Default in current NeuralFlowML options	Runs NeuralFlowML tensor operations on NVIDIA CUDA GPU.	Cost Can substantially accelerate graph-network training/inference if graph size is large enough and GPU memory is sufficient.	Use for production training/inference on supported NVIDIA GPUs.	NeuralFlowML execution modes
Precision: Float32Default: Default	Uses single-precision neural-network arithmetic.	AccuracyCost Lower memory and usually faster, with reduced numerical precision.	Default for most training/inference; compare against Float64 for sensitive cases.	NeuralFlowML execution modes
Precision: Float64	Uses double-precision neural-network arithmetic.	AccuracyCost Higher precision and roughly higher memory/bandwidth cost.	Use for numerical sensitivity studies or when single precision causes unstable gradients/corrections.	NeuralFlowML execution modes
Use TF32 accelerationDefault: Off	Allows compatible reduced-mantissa tensor acceleration where supported.	AccuracyCost May increase throughput at the cost of some arithmetic precision.	Leave off for baseline reproducibility; enable only after confirming no material change in convergence/training.	NeuralFlowML execution modes

Network architecture and propagation

Architecture settings define the trained operator itself; they are not ordinary solver tuning knobs.

GUI option	Meaning / formulation	Effect on the simulation	Practical guidance	Theory reference
Hidden layersDefault: 96, 96, 96	Defines MLP hidden widths used inside the graph-network components.	AccuracyCost Larger/wider networks increase representational capacity, parameter count, memory and compute.	Increase only when training evidence shows under-capacity; wider is not automatically better.	Shared recurrent graph stage
Activation: SiLUDefault: Default	Uses the smooth SiLU activation in hidden MLPs.	AccuracyStability / convergence Provides smooth gradients and is the current standard activation.	Keep for baseline models/training continuation.	Shared recurrent graph stage
Activation: GELU	Uses GELU as the alternative smooth activation.	AccuracyStability / convergence Changes nonlinear representation and optimization dynamics.	Treat as a model-architecture change requiring retraining/validation.	Shared recurrent graph stage
Graph stagesDefault: 60	Number of recurrent message-passing stage applications inside one NeuralFlowML correction pass. The same stage parameters are reused.	AccuracyCost More stages propagate information farther through the graph but increase cost/memory; they do not create independent parameter sets per stage.	Keep consistent with the trained model architecture. Changing this generally requires retraining.	Shared recurrent graph stage
Rollout stepsDefault: 20	Number of differentiable NeuralFlowML correction passes in a training rollout.	AccuracyCost Longer rollout trains multi-step convergence behavior but increases memory/compute. With defaults, one full rollout applies the same graph stage times.	Increase only with memory/checkpointing planning and evidence that longer-horizon training helps.	Shared recurrent graph stage
Graph hidden dimDefault: 96	Width of the node latent state .	AccuracyCost Larger width increases message capacity and parameter/memory cost.	Keep consistent with saved model weights.	Shared recurrent graph stage
Residual scaleDefault: 0.5	Scales each recurrent hidden-state update, .	Stability / convergenceAccuracy Smaller values make hidden propagation more conservative; larger values strengthen each stage and can make optimization/inference less stable.	Keep the trained value unless developing a new architecture.	Shared recurrent graph stage

Correction relaxation and gate

The correction map is multiplicative for pressure/temperature and additive for velocity: , , . Physical p/T limits are applied afterwards.

GUI option	Meaning / formulation	Effect on the simulation	Practical guidance	Theory reference
Learned relaxation headDefault: Off	When enabled, the network predicts per-channel relaxation factors . When disabled, fixed maximum relaxation values are used directly.	Stability / convergenceAccuracy Adds learned control over correction size. It can improve adaptivity but requires suitable training.	The current default is off; do not assume relaxation is learned unless this switch is enabled.	Learned relaxation head
Max relax UDefault: 0.4	Maximum/fixed velocity relaxation. With the learned head off, .	Stability / convergenceCost Directly scales velocity correction magnitude. Larger values can converge faster but overshoot more easily.	Tune conservatively; velocity does not have a separate tanh magnitude cap on its raw correction.	Learned relaxation head
Max relax PDefault: 0.05	Maximum/fixed pressure-log relaxation. Pressure correction uses and .	Stability / convergenceAccuracy Bounds multiplicative pressure changes per pass.	The default effective bound is . Increase only after checking rollout stability.	Learned relaxation head
Max relax TDefault: 0.05	Maximum/fixed temperature-log relaxation, analogous to pressure.	Stability / convergenceAccuracy Bounds multiplicative temperature change per pass.	Default effective bound is .	Learned relaxation head
Max dlog(p) / passDefault: 0.2	Tanh cap applied before pressure relaxation.	Stability / convergenceAccuracy Limits raw pressure-head authority independently of the relaxation factor.	Treat the product with Max relax P as the effective pressure correction authority.	Primitive correction map
Max dlog(T) / passDefault: 0.08	Tanh cap applied before temperature relaxation.	Stability / convergenceAccuracy Limits raw temperature-head authority.	Treat the product with Max relax T as the effective temperature correction authority.	Primitive correction map
Residual teacher gateDefault: Off	When enabled, derives correction authority from NeuralFlow residual state during training and blends it with predicted relaxation.	Stability / convergenceAccuracyCost Provides a curriculum/supervision signal for relaxation, especially early in training.	Default is off. Enable only for a training design that explicitly uses teacher gating.	Residual teacher gate
Teacher warmup epochsDefault: 400	Number of epochs for teacher-dominated gate behavior before blending begins.	Stability / convergenceCost Longer warmup delays reliance on the network-predicted gate.	Use only when residual teacher gate is enabled.	Residual teacher gate
Teacher ramp epochsDefault: 800	Number of epochs over which teacher-to-predicted blending is ramped.	Stability / convergenceCost Longer ramp makes the transition more gradual.	Use only with teacher gating; coordinate with total training length.	Residual teacher gate
Init relax U / P / TDefault: U=0.02, P=0.02, T=0.002	Initial relaxation targets used to initialize the optional gate head so its sigmoid initially reproduces the configured small relaxation. For ratio , the initial bias is .	Stability / convergenceInitialization Sets conservative initial gate behavior before training changes it.	These values matter primarily when the learned relaxation head is enabled.	Learned relaxation head
Teacher beta U / P / TDefault: 1, 1, 1	Local residual-gate saturation parameter .	Stability / convergenceAccuracy Larger beta requires a larger normalized residual to produce strong teacher relaxation.	Keep default unless deliberately calibrating teacher-gate sensitivity.	Residual teacher gate
Gate loss weight U / P / TDefault: 1, 1, 1	Weights squared difference between predicted and teacher relaxation in the optional gate loss.	AccuracyCost Changes how strongly each channel learns to imitate teacher relaxation.	Only relevant when teacher-gate/gate training is used.	Primitive correction map

Optimizer controls

Training updates network parameters only after a finite, admissible differentiable rollout and gradient evaluation.

GUI option	Meaning / formulation	Effect on the simulation	Practical guidance	Theory reference
Optimizer: Adam	Adaptive first/second-moment optimizer without decoupled weight decay.	AccuracyCost Often easy to tune but weight decay behavior differs from AdamW.	Use for optimizer comparisons; changing optimizer can change training trajectory materially.	Optimizer and parameter update
Optimizer: AdamWDefault: Default	Adaptive moment optimizer with decoupled weight decay.	AccuracyCost Provides stable general training behavior and independent regularization through weight decay.	Current default training optimizer.	Optimizer and parameter update
Optimizer: SGD	Stochastic gradient descent with optional momentum/dampening/Nesterov.	AccuracyCost Less adaptive; may require smaller/more carefully scheduled learning rates but can provide different generalization behavior.	Use only with deliberate optimizer tuning.	Optimizer and parameter update
Learning rateDefault: 1e-3	Optimizer step size .	Stability / convergenceCost Too large can make loss/weights diverge; too small makes training slow/stagnant.	Tune on loss/residual trend; reduce when late training oscillates.	Optimizer and parameter update
Additional epochs	Number of additional optimizer updates to run from the current epoch when Start is pressed.	Cost Controls training duration, not architecture.	Use incremental training blocks and evaluate convergence between them.	Optimizer and parameter update
Weight decayDefault: 1e-6	Decoupled regularization coefficient for AdamW or corresponding optimizer regularization behavior.	Accuracy Penalizes large weights and can reduce overfitting/unstable parameter growth; excessive decay underfits.	Keep small unless validation behavior supports stronger regularization.	Optimizer and parameter update
Grad clipDefault: On	Enables global gradient-norm clipping.	Stability / convergence Protects against occasional large gradient spikes and optimizer instability.	Keep enabled for recurrent long-rollout training.	Optimizer and parameter update
Max normDefault: 1	If , uses .	Stability / convergenceCost Smaller limit stabilizes training but can slow legitimate updates.	Use the default unless clipping is nearly always active or rare spikes remain problematic.	Optimizer and parameter update
beta1 / beta2 / epsDefault: 0.9 / 0.999 / 1e-8	Adaptive-moment coefficients and numerical epsilon.	Stability / convergenceAccuracy Control moment averaging and numerical stability of Adam/AdamW.	Keep standard defaults unless conducting optimizer research.	Optimizer and parameter update
amsgradDefault: Off	Enables the AMSGrad variant of adaptive moments when supported by the selected optimizer.	Accuracy Changes second-moment accumulation and optimization trajectory.	Leave off for baseline compatibility; enable only as an optimizer experiment.	Optimizer and parameter update
SGD momentum	Adds velocity-like accumulation of previous gradients.	Stability / convergenceAccuracy Can accelerate smooth descent but overshoot if learning rate/momentum are too high.	Relevant only for SGD.	Optimizer and parameter update
SGD dampening	Dampens the momentum contribution in SGD.	Stability / convergence Changes effective momentum dynamics.	Relevant only for SGD; use together with its momentum definition.	Optimizer and parameter update
SGD nesterovDefault: Off	Uses Nesterov-style momentum where compatible.	Accuracy Changes look-ahead gradient update and training trajectory.	Relevant only for SGD and compatible momentum/dampening settings.	Optimizer and parameter update
VerboseDefault: Off	Prints more NeuralFlowML training/runtime information.	Reporting / displayCost No learned model mathematics change; adds logging overhead.	Enable while diagnosing training; disable for cleaner long runs.	Optimizer and parameter update

Physics-loss weighting

For and NeuralFlow matrix sign convention , the state gradient is .

GUI option	Meaning / formulation	Effect on the simulation	Practical guidance	Theory reference
Flux loss weighting: None	Uses , so .	AccuracyStability / convergence All residual components contribute in their raw solver units/scales, which may let numerically large equation components dominate.	Use mainly as an unweighted reference.	Physics-loss metric selection
Flux loss weighting: ResidualHotspot	Uses cell residual norm and a frozen hotspot factor .	AccuracyStability / convergence Emphasizes high-residual cells without changing the local residual vector direction.	Useful when a small number of cells dominate convergence.	Physics-loss metric selection
Flux loss weighting: ResidualHotspotNormalizedScore	Builds hotspot scores from normalized residual magnitude but applies weighting to the original residual components.	AccuracyStability / convergence Reduces unit/scale bias in hotspot detection while retaining the physical residual in the Jacobian transpose action.	Good choice when raw equation scales differ strongly.	Physics-loss metric selection
Flux loss weighting: WeissSmithFull	Uses a reduced pressure-velocity thermodynamic metric to transform residual components before forming the objective.	AccuracyStability / convergence Balances compressible equation components in a preconditioning-aware metric.	Use for low-Mach/mixed-scale compressible training studies after comparing against the primitive-scaled default.	Physics-loss metric selection
Flux loss weighting: WeissSmithPrimitiveScaledHotspotDefault: Default	Applies the reduced thermodynamic transform plus primitive-variable scales and hotspot weighting. A representative score is .	AccuracyStability / convergence Balances velocity, pressure and temperature residual influence while emphasizing difficult cells.	Current default physical weighting mode and best starting point for general NeuralFlowML training.	Physics-loss metric selection
Flux loss weighting: RegularizedFrozenCorrection	Builds a frozen global correction metric from the steady spatial Jacobian: and .	AccuracyStability / convergenceCost Measures residual through approximate correction difficulty, giving strong equation/coupling awareness at substantial setup/solve cost.	Advanced training metric; use only when its extra cost and steady-Jacobian assumptions are acceptable.	Physics-loss metric selection
Flux loss weighting: FrozenLocalJacobianRowGram	Uses a per-cell frozen row-Gram metric and .	AccuracyStability / convergenceCost Balances residuals using local Jacobian sensitivity without a global metric solve, but has case restrictions related to pressure reference/nullspaces.	Advanced option; use only for compatible pressure-referenced steady cases.	Physics-loss metric selection

Training strategy, memory and scheduler

These settings control where training states come from, auxiliary supervision and memory/runtime behavior.

GUI option	Meaning / formulation	Effect on the simulation	Practical guidance	Theory reference
Converged solution lossDefault: Off	Adds an optional state-target loss against a captured converged NeuralFlow solution: velocity error plus squared and differences.	AccuracyCost Introduces supervised guidance toward a known converged field in addition to physics residual training.	Leave off for pure physics-residual training; enable when a trustworthy target solution is intentionally used.	Completed-solution auxiliary objective
Converged solution loss weightDefault: 1e-4	Weight used when mixing RMS-normalized physics and target-state gradients.	Accuracy Larger weight makes training follow the captured solution more strongly.	Keep very small unless intentionally moving toward supervised training.	Completed-solution auxiliary objective
Anchor update after epochDefault: Off	Allows the accepted training anchor to move toward the predicted state after an optimizer update.	AccuracyStability / convergence Changes the distribution of states from which later rollouts begin; can help curriculum/continuation but reduces fixed-anchor comparability.	Leave off for classic fixed-anchor training.	Training-anchor semantics
Anchor update alphaDefault: 0.01	When enabled, .	Stability / convergenceAccuracy Higher alpha moves training anchor faster toward current predictions.	Use small values to avoid destabilizing the training state distribution.	Training-anchor semantics
Episode trainingDefault: Off	Carries physical state across multiple optimizer updates within an episode while each differentiable update still uses the configured rollout length.	AccuracyCost Trains longer-horizon iterative behavior without backpropagating through an indefinitely long graph.	Use when fixed-anchor training is insufficient to teach multi-iteration continuation.	Episode training
Iterations per episode MDefault: 10 when episode mode is enabled	Number of optimizer updates/state continuations per episode. Approximate corrections per episode are .	AccuracyCost Larger M trains farther from the episode anchor but increases compute and distribution shift.	Increase gradually and monitor residual evolution across an episode.	Episode training
Frozen-policy evalDefault: Off	Evaluates the current policy over additional rollout steps without changing weights, for convergence assessment.	Reporting / displayCost Adds evaluation cost but helps detect whether a trained correction remains stable beyond the training horizon.	Useful during model qualification.	Training optimization
Frozen eval stepsDefault: 0 / derived	Number of evaluation steps when frozen-policy evaluation is enabled; zero can select the configured/derived behavior.	Reporting / displayCost Longer evaluation tests farther-horizon convergence at greater cost.	Use enough steps to reveal divergence/stall beyond the training rollout.	Training optimization
Graph-stage checkpointingDefault: Off	Recomputes selected graph-stage activations during backpropagation instead of storing all of them.	Cost Reduces training memory at the cost of additional compute.	Enable when GPU memory limits rollout/stage count.	Training memory/checkpointing
Checkpoint block sizeDefault: 5	Number of graph stages grouped per checkpoint block.	Cost Larger blocks store fewer checkpoints but may increase recomputation granularity/memory tradeoff.	Tune based on GPU memory and training throughput.	Training memory/checkpointing
LR Scheduler: NoneDefault: Default/effective	Keeps the optimizer learning rate at the configured value.	Accuracy Current training behavior uses the fixed learning rate.	Use this for the supported baseline training path.	Training optimization
LR Scheduler: Step / ExponentialDefault: Currently inactive	The GUI exposes Step and Exponential scheduler selectors and gamma fields, but the current training runner does not apply these schedules.	Reporting / display Selecting them does not currently create the expected learning-rate decay during training.	Treat these controls as visible but currently inactive; change learning rate manually when needed.	Training optimization
Step gamma / Exp gammaDefault: Currently inactive	Parameters displayed for the inactive scheduler selections.	Reporting / display No current training effect while the schedules are not applied by the training runner.	Do not rely on them for learning-rate decay in this edition.	Training optimization

NeuralFlowML actions

Actions commit, load, train, evaluate or save the learned solver.

GUI option	Meaning / formulation	Effect on the simulation	Practical guidance	Theory reference
Apply Model	Applies the displayed NeuralFlowML model options/architecture settings to the active model context.	Initialization Can rebuild/reconfigure the model and therefore must remain compatible with saved weights.	Use after changing model settings and before training/inference.	NeuralFlowML correction pipeline
Load Model	Loads saved network parameters/model state.	Initialization Changes the correction policy used for inference/training continuation.	Load only a model compatible with the current dimension/state/architecture.	NeuralFlowML correction pipeline
Save Model	Writes the current trained model state.	Reporting / display No immediate solution change.	Save checkpoints before major training changes and after validated milestones.	NeuralFlowML correction pipeline
Start / Stop	Starts or requests stopping of the configured training operation.	Cost Start changes weights over optimizer updates; Stop preserves the last accepted training state.	Use finite training blocks and inspect loss/residual behavior.	NeuralFlowML correction pipeline
Inference	Runs NeuralFlowML inference/correction from the current compatible state.	Stability / convergenceCost Changes the flow state through learned corrections.	Monitor physical residual, limits and final convergence just as with any nonlinear solver.	NeuralFlowML correction pipeline
Reset	Restores/reset NeuralFlowML options/state as defined by the GUI workflow.	Initialization Can discard current edits/runtime state.	Save a model first if you need to preserve trained weights.	NeuralFlowML correction pipeline
Apply Optimizer	Commits optimizer/training hyperparameters.	Initialization Changes subsequent parameter-update behavior.	Apply after editing optimizer settings and before starting training.	NeuralFlowML correction pipeline
Check Network	Runs the available network consistency/shape checks.	Reporting / display Diagnostic only unless a problem is found.	Use after architecture/model loading changes.	NeuralFlowML correction pipeline
Capture Target Sol.	Captures the current converged NeuralFlow solution for the optional converged-solution loss.	InitializationAccuracy Creates the reference field used by the target-state auxiliary objective.	Capture only a well-converged, physically correct solution.	NeuralFlowML correction pipeline

What happens during a training rollout

NeuralFlowML predicts a corrected state .
The corrected values are applied to NeuralFlow cells.
Prescribed/scripted boundary values are refreshed.
NeuralFlow assembles the finite-volume residual at the required rollout points; residual-teacher training can request intermediate physical assembly.
The physics objective is differentiated back through the recurrent graph using the NeuralFlow residual/Jacobian feedback.

This synchronization is why NeuralFlowML should be understood as a learned iterative solver coupled to NeuralFlow physics, not as a detached field-regression model.