NeuralFlow Options
NeuralFlow is a solver-trained recurrent Graph Neural Operator (GNO). It does not predict a finished flow field in one pass. Starting from a CMPS 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, CMPS 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 \(D\), NeuralFlow currently learns \(\mathbf q=[u_1,\ldots,u_D,p,T]^T\), so \(n_q=D+2\). Species, turbulence variables, dispersed variables, solid variables and VOF fractions remain in the conventional CMPS path.
The recurrent correction can be written conceptually as \(\mathbf q^{(r+1)}=\Phi_\theta(\mathbf q^{(r)},\mathcal M,\mathcal C_{BC})=\mathbf q^{(r)}+\Delta\mathbf q_\theta^{(r)}\).
Activation, mode and device
These controls choose whether NeuralFlow 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 NeuralFlow subsystem for the current case. | PhysicsCost When disabled, the normal CMPS CFD solver path is used without NeuralFlow corrections. | Keep disabled for ordinary CFD cases; enable only after a compatible NeuralFlow model/setup is ready. | NeuralFlow execution modes |
| AI Mode: Inference | Runs the trained NeuralFlow 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. | NeuralFlow 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. | NeuralFlow execution modes |
| AI Mode: CFD | Uses the conventional CFD-solving mode selected in the NeuralFlow panel context. | Cost Provides the non-training solver path/reference behavior. | Use for baseline/reference solution generation and comparison. | NeuralFlow execution modes |
| Device: CPU | Runs NeuralFlow 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. | NeuralFlow execution modes |
| Device: CUDADefault: Default in current NeuralFlow options | Runs NeuralFlow 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. | NeuralFlow 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. | NeuralFlow 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. | NeuralFlow 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. | NeuralFlow 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 |
|---|---|---|---|---|
| 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 \(N_g\) of recurrent message-passing stage applications inside one NeuralFlow 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 \(N_r\) of differentiable NeuralFlow 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 \(60\times20=1200\) times. | Increase only with memory/checkpointing planning and evidence that longer-horizon training helps. | Shared recurrent graph stage |
| Residual scaleDefault: 0.5 | Scales each recurrent hidden-state update, \(\mathbf h_i^{\ell+1}=\mathbf h_i^\ell+s_h\Delta\mathbf h_i^\ell\). | 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: \(p^+=p\exp(\Delta\ln p)\), \(T^+=T\exp(\Delta\ln T)\), \(\mathbf u^+=\mathbf u+\Delta\mathbf u\). 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 \(\omega_\phi^{pred}=\omega_{\phi,max}\sigma(g_\phi)\). 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, \(\Delta\mathbf u=\omega_{u,max}\Delta\mathbf u^{raw}\). | 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 \(\widehat{\Delta\ln p}=\Delta_{p,max}\tanh(r_p)\) and \(\Delta\ln p=\omega_{p,max}\widehat{\Delta\ln p}\). | Stability / convergenceAccuracy Bounds multiplicative pressure changes per pass. | The default effective bound is \(|\Delta\ln p|\le0.05\times0.2=0.01\). 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 \(|\Delta\ln T|\le0.05\times0.08=0.004\). | Learned relaxation head |
| Max dlog(p) / passDefault: 0.2 | Tanh cap \(\Delta_{p,max}\) 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 \(\Delta_{T,max}\) 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 CMPS 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 \(r_0=\omega_0/\omega_{max}\), the initial bias is \(b_0=\ln[r_0/(1-r_0)]\). | 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 \(b_{\phi,i}=r_{\phi,i}/(r_{\phi,i}+\beta_\phi)\). | 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 \(\eta\). | 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 \(\|g\|_2>g_{max}\), uses \(g\leftarrow g\,g_{max}/(\|g\|_2+\epsilon)\). | 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 NeuralFlow 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 \(J_{phys}=\tfrac12 B^TWB\) and CMPS matrix sign convention \(A_{solv}\approx-\partial B/\partial q\), the state gradient is \(\nabla_qJ_{phys}\approx-A_{solv}^TWB\).
| GUI option | Meaning / formulation | Effect on the simulation | Practical guidance | Theory reference |
|---|---|---|---|---|
| Flux loss weighting: None | Uses \(J=\frac{1}{2N}\mathbf B^T\mathbf B\), so \(W\mathbf B=\mathbf B/N\). | 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 \(r_i=\|B_i\|_2\) and a frozen hotspot factor \(a_i=\mathrm{clamp}(1+\beta r_i/\bar r,1,a_{max})\). | 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 \(r_i=\|S_i^{-1}T_i^{-1}B_i\|_2\). | AccuracyStability / convergence Balances velocity, pressure and temperature residual influence while emphasizing difficult cells. | Current default physical weighting mode and best starting point for general NeuralFlow training. | Physics-loss metric selection |
| Flux loss weighting: RegularizedFrozenCorrection | Builds a frozen global correction metric from the steady spatial Jacobian: \(K=AS^2A^T,\;G=K+\mu D_\delta\) and \(J=(1+\mu)B^TG^{-1}B/(2N)\). | 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 \(D_i=\sum_j A_{ij}S_j^2A_{ij}^T\) and \(J=\gamma\sum_i B_i^TD_{i,\delta}^{-1}B_i/(2N)\). | 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 CMPS solution: velocity error plus squared \(\ln p\) and \(\ln T\) 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 \(\lambda\) 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, \(q_{anchor}^{new}=(1-\alpha)q_{anchor}^{old}+\alpha q_{pred}\). | 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 \(N_{corr}\approx M N_r\). | 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 |
NeuralFlow 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 NeuralFlow 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. | NeuralFlow 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. | NeuralFlow 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. | NeuralFlow 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. | NeuralFlow correction pipeline |
| Inference | Runs NeuralFlow 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. | NeuralFlow correction pipeline |
| Reset | Restores/reset NeuralFlow 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. | NeuralFlow correction pipeline |
| Apply Optimizer | Commits optimizer/training hyperparameters. | Initialization Changes subsequent parameter-update behavior. | Apply after editing optimizer settings and before starting training. | NeuralFlow 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. | NeuralFlow correction pipeline |
| Capture Target Sol. | Captures the current converged CMPS 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. | NeuralFlow correction pipeline |
What happens during a training rollout
- NeuralFlow predicts a corrected state \(q_{next}=G_\theta(q)\).
- The corrected \([\mathbf u,p,T]\) values are applied to CMPS cells.
- Prescribed/scripted boundary values are refreshed.
- CMPS 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 CMPS residual/Jacobian feedback.
This synchronization is why NeuralFlow should be understood as a learned iterative solver coupled to CMPS physics, not as a detached field-regression model.