Relaxation filter options and how to use them

This page summarizes the practical control parameters for the TRANSP profile relaxation filter, the meaning of each option, and recommended settings for reduced-transport and predictive PT_SOLVER applications.

What the filter is doing

The filter modifies the profile that is passed into the anomalous transport model during a PT_SOLVER step. It blends radial smoothing, optional temporal anchoring, optional robust weighting, and optional shape control.

For profiles that are not evolved, the filtered result is used only inside the transport step and the original experimental profile is restored afterward. Repeated filtering therefore does not accumulate as a persistent time-history change in the stored profile.

The filter should be viewed as a transport-input regularization tool, not as a replacement for experimental data. Its purpose is to reduce numerical artifacts while preserving physically important profile structure and gradients.

Operational consequence

Use radial smoothing and soft shape filtering mainly to improve the transport solver numerics. Avoid using the filter to hide a physically inconsistent input setup. After changing relaxation parameters, compare the resulting transport-input profiles, effective diffusivities, and evolved temperatures against a baseline case.

Use lam_t_base carefully. For non-evolved profiles it influences the transport input used at the current step, but it does not create a lasting lagged profile state. For evolved profiles, temporal anchoring can help regularize the first predictive steps, but large values may delay the response of the profile to the transport model.

Main control parameters

Parameter	Role	Suggested starting range	Increase it to...	Main risk
`relx_profile`	Blend factor between the raw and filtered profile.	`0.2-1.0`	Apply more of the filtered result.	Over-filtering if the raw profile is already well behaved.
`lam_t_base`	Temporal smoothness or anchoring strength.	`0-1` for non-evolved profiles; `1-60` for stronger anchoring when needed.	Reduce step-to-step variation.	The transport input may follow previous frames too strongly and lag rapid physical changes.
`lam_r_base`	Radial curvature smoothing strength.	`0.1-10` for routine use; larger values should be treated as case-specific.	Reduce grid-scale roughness and stabilize gradients.	Broadening or damping real radial structure.
`shape_mode`	Shape constraint mode: `0` none, `1` hard monotone, `2` soft monotone.	`0`, `1`, or `2`.	Apply stronger shape control.	Hard mode can flatten profile features and alter gradients.
`lam_m_base`	Strength of the soft monotonicity penalty.	`1-20`	Suppress larger outward rises while avoiding hard projection.	Can erase real off-axis features if too large.
`delta_base`	Allowed outward increase before the soft monotone penalty activates.	`0.005-0.03` for soft density filtering; `0` for near-monotone behavior.	Preserve mild bumps or hollowness.	If too large, shape control becomes weak.
`bdy_weight`	Relative weight of edge adherence.	`0.5-2`, usually near `1`.	Hold the edge closer to the experimental value.	If too small, the edge can drift under curvature smoothing.

Recommended default strategy

For density and other non-evolved experimental profiles, prefer soft shape control with modest radial smoothing.
Use shape_mode = 2 for bump-preserving soft monotonicity.
Use delta_base > 0 to allow physically reasonable outward increases.
Keep bdy_weight near unity unless you intentionally want weak edge adherence.
Add temporal anchoring only after the radial and shape settings have been tuned.

No shape constraint

shape_mode = 0

Use only radial smoothing and optional temporal anchoring. This is a good choice for well-behaved profiles or for cases where non-monotone structure is expected to be physical.

Hard monotone

shape_mode = 1

Applies a monotone projection after the main solve. Use only when strict monotonicity is physically appropriate and flattening of local features is acceptable.

Soft monotone

shape_mode = 2

Adds a penalty for outward increases larger than delta_base. This is usually the preferred option for density filtering because it suppresses clearly problematic structure while preserving mild bumps and gradients more faithfully than hard monotone projection.

How to use the filter in practice

1. Start with the use case

Decide whether the profile is evolved by PT_SOLVER, fixed during prediction, or restored after each step. For restored experimental profiles, treat the filter as a within-step transport-input modifier.

2. Choose the shape policy

Use shape_mode = 2 for density unless you have a strong reason to enforce strict monotonicity. Use shape_mode = 0 when off-axis structure, pellet effects, internal transport barriers, or other non-monotone features are expected to be physical.

3. Tune smoothness first

Adjust lam_r_base until small-scale roughness is reduced without broadening the profile excessively. Check the resulting gradients, not only the profile values.

4. Add temporal anchoring last

Add only enough lam_t_base to reduce jitter in the transport input. Keep it low for non-evolved profiles unless frame-to-frame noise is clearly affecting convergence.

Suggested starting points

Case	Suggested setup
Experimental density, not evolved	`shape_mode = 2`, modest `lam_r_base`, small or zero `lam_t_base`, moderate `lam_m_base`, `delta_base = 0.01-0.03`.
Evolving predictive profile at the first predictive step	Use modest radial smoothing and, if needed, temporal anchoring to regularize the initial state. Avoid continuous aggressive filtering unless solver-generated artifacts persist.
Fixed profile used during prediction	Use soft shape control and modest radial smoothing. Use small temporal anchoring only if frame-to-frame jitter affects convergence.
Well-behaved profile with only minor noise	`shape_mode = 0`, small `lam_r_base`, little or no `lam_t_base`.
Need strict monotonicity	`shape_mode = 1` only if flattening is acceptable and physically consistent.

Transition-stage solver relaxation

Profile filtering can be combined with temporary relaxation of nonlinear convergence controls during the handoff from interpretive to predictive evolution. This transition is often the most difficult part of a predictive run, because the solver is reconciling a measurement-constrained state with transport-model-implied fluxes.

The recommended policy is staged strictness: use relaxed convergence only during the initial adjustment phase, then return to the standard solver settings once the profiles and diffusivities become smoother. Filtering and relaxation should be used together carefully. The filter removes profile-driven numerical pathologies, while temporary relaxation avoids excessive work on the remaining transient mismatch.

Residuals and Peclet-number-related factors

Recent PT_SOLVER refactoring changed the interpretation of enhancement factors and residuals used in diffusivity calculations. The default settings for residual and Peclet-number-related factors have also been updated. Most users do not set these quantities explicitly and should use the release defaults.

Users who explicitly set pt_residual%RES_TE, pt_residual%RES_TI, pt_residual%RES_NE, pt_residual%RES_NMAIN, pt_residual%RES_NIMP, pt_residual%RES_PPHI, or numerical-diffusivity parameters entering the Peclet-number calculation should review their input files before rerunning older cases. Values copied from older runs may not have the same practical meaning after the refactoring.

Use the current release defaults unless a convergence study indicates that changes are needed.
Do not increase residual tolerances only to make a run finish faster without checking profile fidelity.
Do not change Peclet-number factors or minimum numerical diffusivities unless the numerical behavior is understood.
When changing these values, compare electron temperature, ion temperature, density, rotation, effective diffusivities, and convective velocities against a baseline run.

For the broader PT_SOLVER setup, see the PT_SOLVER options page. For the algorithmic background, see arXiv:2605.09720.

When to be cautious

shape_mode = 1 can flatten local structure because it applies a hard monotone projection.
Large lam_m_base with very small delta_base can suppress real off-axis features.
Large lam_t_base can make the transport input follow previous frames too strongly.
Too small bdy_weight can let curvature regularization distort the edge.
Too much filtering can change gradient scale lengths and therefore change gradient-sensitive transport predictions.

Quick troubleshooting

Profile still noisy: raise lam_r_base first, then consider a small lam_t_base.
Real bump disappeared: reduce lam_m_base, increase delta_base, or set shape_mode = 0.
Edge shifted too much: increase bdy_weight.
Profile looks flattened: check whether shape_mode = 1 is active.
Transport input lags frame-to-frame: reduce lam_t_base.
Run is still slow after filtering: check nonlinear iterations, time-step cuts, and whether temporary transition-stage relaxation is active.

Bottom line

For reduced transport with experimental profiles that are restored after each step, the most robust operating point is usually:

shape_mode = 2 + modest lam_r_base + moderate lam_m_base + nonzero delta_base + bdy_weight near unity + little or no lam_t_base.

This keeps the transport input numerically smoother while preserving the essential profile shape more faithfully than hard monotone filtering. For evolved predictive profiles, use filtering mainly to regularize the initial state or to remove clear numerical artifacts, and avoid repeated aggressive filtering unless it is justified by convergence tests.

QROT and Heat-Flux Split Controls in TRANSP/PT_SOLVER

1. QROT control overview

Rotational-energy dissipation enters the ion-temperature equation through the QROT source term. In predictive PT_SOLVER calculations, large or noisy toroidal rotation profiles can generate localized rotational heating or cooling terms that are too large for a stable temperature solve.

TRANSP provides two levels of control:

Pre-PT_SOLVER omega controls, applied before MOMBAL computes the rotational-energy dissipation terms.
PT_SOLVER QROT controls, applied after the QROT source has been constructed and mapped into the PT_SOLVER source arrays.

These controls overlap in purpose but act at different stages. The omega controls modify the rotation profile before QROT is generated. The PT_SOLVER controls limit how the already-generated QROT source enters the ion-temperature equation.

2. Omega filtering and capping before PT_SOLVER

2.1 `NLQROT_OMEGA_CAP`

NLQROT_OMEGA_CAP = .TRUE.

This option caps the prescribed angular velocity before MOMBAL computes QROTF and QROTCV.

The cap is based on the proton rotational energy,

\[ E_{p,\mathrm{rot}} = \frac{1}{2}\frac{m_p (R_{\mathrm{axis}}\Omega)^2}{e} \]

where \(E_{p,\mathrm{rot}}\) is in eV, \(m_p\) is the proton mass, \(R_{\mathrm{axis}}\) is the magnetic-axis major radius, and \(\Omega\) is the toroidal angular frequency.

The namelist parameter QROT_OMEGA_EPMAX sets the maximum allowed value of \(E_{p,\mathrm{rot}}\). The corresponding cap on angular velocity is approximately

\[ |\Omega| \le \Omega_{\max} = \frac{1}{R_{\mathrm{axis}}} \sqrt{\frac{2 e\,QROT\_OMEGA\_EPMAX}{m_p}} . \]

A smaller value of QROT_OMEGA_EPMAX gives a stronger cap.

QROT_OMEGA_EPMAX = 1.0D4    ! stronger cap
QROT_OMEGA_EPMAX = 1.0D5    ! weaker cap

The cap is useful when the input rotation profile contains local spikes or extrapolated values that would otherwise imply excessive rotational energy.

2.2 `NLQROT_OMEGA_FILTER`

NLQROT_OMEGA_FILTER = .TRUE.

This option regularizes the prescribed OMEGA profile before MOMBAL. The filter is intended to reduce localized radial outliers and abrupt time-to-time changes while preserving the overall sign and shape of the rotation profile.

The filter can be viewed as solving a regularized least-squares problem. In simplified form, for a raw profile \(y_i\), previous accepted profile \(x_i^{prev}\), and filtered profile \(x_i\), the filter minimizes

\[ J(x) = \sum_i w_i (x_i-y_i)^2 + \lambda_t \sum_i (x_i-x_i^{prev})^2 + \lambda_r \sum_i (\Delta_r^2 x_i)^2 . \]

QROT_OMEGA_LAM_T: Temporal anchoring strength, \(\lambda_t\). Larger values keep the new filtered profile closer to the previous accepted profile.
QROT_OMEGA_LAM_R: Radial curvature penalty, \(\lambda_r\). Larger values produce a smoother radial profile.
QROT_OMEGA_HUBER: Huber outlier threshold used to construct the weights \(w_i\). Points with large time-to-time deviations receive smaller weights.

Schematically,

\[ w_i = \begin{cases} 1, & u_i \le 1, \\ 1/u_i, & u_i > 1, \end{cases} \]

with

\[ u_i = \frac{|(y_i-x_i^{prev})-\mathrm{median}(y-x^{prev})|} {k_{\mathrm{Huber}}\,s} . \]

The scale \(s\) is estimated from the median absolute deviation of the time residuals.

`QROT_OMEGA_RELX`

This parameter sets the blend between the raw and filtered profile:

\[ \Omega_{\mathrm{used}} = (1-\alpha)\Omega_{\mathrm{raw}} + \alpha\Omega_{\mathrm{filtered}}, \qquad \alpha = QROT\_OMEGA\_RELX . \]

QROT_OMEGA_RELX = 0.0  ! no filtering effect
QROT_OMEGA_RELX = 0.3  ! partial filtering
QROT_OMEGA_RELX = 1.0  ! full filtered profile

`QROT_OMEGA_WARN`

This parameter controls diagnostic printing. A message is printed when the relative maximum correction exceeds this threshold:

\[ \frac{\max_i |\Omega_{filtered,i}-\Omega_{raw,i}|} {\max_i |\Omega_{raw,i}|} > QROT\_OMEGA\_WARN . \]

When both omega filtering and omega capping are enabled, the profile is filtered first and then capped.

3. QROT controls inside PT_SOLVER

3.1 Imported QROT source

The rotational-energy terms imported into PT_SOLVER are QROTF and QROTCV, represented internally as diffusive and convective contributions:

Qrot_diff
Qrot_conv

These terms are loaded as zone powers and converted into a volume source density by dividing by the zone volume:

\[ QROT_j = \frac{QROT\_DIFF_j + QROT\_CONV_j} {\max(\Delta V_j,\,PT\_QROT\_DVOL\_FLOOR)} . \]

Here \(QROT_j\) has units of W/m³.

The floor PT_QROT_DVOL_FLOOR prevents division by an extremely small or invalid zone volume. It is not a physical cap on QROT; it is a numerical safety floor in the conversion from W/zone to W/m³.

3.2 `NLPT_QROT_ENSURE_POSITIVE`

NLPT_QROT_ENSURE_POSITIVE = .TRUE. / .FALSE.

When this option is .TRUE., the imported QROT source is clipped to be non-negative:

\[ QROT_j \leftarrow \max(0,QROT_j) . \]

The diffusive and convective components are also clipped consistently. This treats rotational dissipation as ion heating only.

When this option is .FALSE., signed QROT is retained before the cap is applied. This allows both local rotational heating and local rotational cooling.

3.3 `PT_QROT_CAP_FRAC`

PT_QROT_CAP_FRAC = value

This option limits the magnitude of the QROT source relative to the local ion thermal energy density divided by the PT_SOLVER timestep.

The local ion thermal energy density used for the cap is

\[ W_{i,j} = \frac{3}{2} n_{i,j} T_{i,j} . \]

In code units, with \(T_i\) in keV and \(n_i\) in m^-3,

\[ W_{i,j} = 1.5\, e\,10^3\, \max(n_{i,j},0)\, \max(T_{i,j},PT\_QROT\_TEMP\_FLOOR) . \]

The QROT limit is then

\[ QROT_{\max,j} = PT\_QROT\_CAP\_FRAC \frac{W_{i,j}}{\Delta t} . \]

The applied cap is symmetric:

\[ QROT_j \leftarrow \min\left[ \max(QROT_j,-QROT_{\max,j}), QROT_{\max,j} \right] . \]

Therefore, PT_QROT_CAP_FRAC is approximately the maximum fraction of local ion thermal energy that QROT is allowed to add or remove in one PT_SOLVER step.

PT_QROT_CAP_FRAC = 1.0D0   ! about 100% of local ion energy per step
PT_QROT_CAP_FRAC = 1.0D-2  ! about 1% of local ion energy per step
PT_QROT_CAP_FRAC = 1.0D-4  ! about 0.01% of local ion energy per step

If PT_QROT_CAP_FRAC <= 0, the QROT cap is disabled.

3.4 `PT_QROT_TEMP_FLOOR`

PT_QROT_TEMP_FLOOR = 5.0D-3

This is the temperature floor used when computing the thermal-energy scale for the QROT cap:

\[ T_{cap,j} = \max(T_{i,j},PT\_QROT\_TEMP\_FLOOR) . \]

It prevents the allowed QROT limit from becoming unrealistically small or singular in very cold zones. A smaller value makes the QROT cap stricter in cold regions. A larger value makes the cap less restrictive in cold regions.

3.5 `pt_num_diffusivity%qrot_to_ti`

pt_num_diffusivity%qrot_to_ti = .TRUE. / .FALSE.

This option controls whether the imported and capped QROT source is added to the ion-temperature equation.

With pt_num_diffusivity%qrot_to_ti = .TRUE.,

\[ Q_i = P_i + P_{i,rcy} + P_{i,\alpha} + QROT . \]

With pt_num_diffusivity%qrot_to_ti = .FALSE.,

\[ Q_i = P_i + P_{i,rcy} + P_{i,\alpha} . \]

In the second case, QROT may still be computed, capped, archived, and diagnosed, but it is not used as a direct source in the PT_SOLVER Ti equation.

4. Overlap between omega controls and PT_SOLVER QROT controls

The omega controls act before QROT is generated:

NLQROT_OMEGA_FILTER
NLQROT_OMEGA_CAP
QROT_OMEGA_*

These modify or limit \(\Omega\), and therefore affect QROTF, QROTCV, the downstream momentum/rotation state, and the QROT source seen by PT_SOLVER.

The PT_SOLVER controls act after QROT is generated:

NLPT_QROT_ENSURE_POSITIVE
PT_QROT_CAP_FRAC
PT_QROT_TEMP_FLOOR
PT_QROT_DVOL_FLOOR
pt_num_diffusivity%qrot_to_ti

These protect the Ti equation but do not repair the underlying rotation profile. Therefore, an unphysical omega profile may still cause failures outside the Ti equation even when qrot_to_ti = .FALSE..

Control group	Acts on	Primary purpose
`NLQROT_OMEGA_FILTER`, `NLQROT_OMEGA_CAP`, `QROT_OMEGA_*`	Rotation profile before QROT generation	Reduce unphysical omega values, spikes, and time-to-time jumps
`PT_QROT_CAP_FRAC`, `PT_QROT_TEMP_FLOOR`, `PT_QROT_DVOL_FLOOR`	Already-generated QROT source	Limit the effect of QROT on local ion thermal energy
`pt_num_diffusivity%qrot_to_ti`	Ti source assembly	Include or exclude QROT from the PT_SOLVER Ti equation

Heat-flux split mode

The option

pt_num_diffusivity%heat_flux_split_mode

controls how a model heat flux is represented as a combination of positive diffusivity and heat-convective velocity.

The split helper represents a model heat flux in the form

\[ \Gamma_T = -n\,\chi\,\nabla T + n\,T\,v_T , \]

where \(\Gamma_T\) is the model heat-flux-like quantity, \(n\) is density, \(T\) is temperature, \(\chi\) is heat diffusivity, and \(v_T\) is heat convective velocity.

Given a model flux \(\Gamma_T^{model}\), the raw effective diffusivity is

\[ \chi_{raw} = -\frac{\Gamma_T^{model}} {n\,\nabla T_{eff}} , \]

where \(\nabla T_{eff}\) is the temperature gradient with a small signed floor applied to avoid division by zero when the gradient is very small.

Mode 0: project onto positive diffusion

pt_num_diffusivity%heat_flux_split_mode = 0

Mode 0 projects the model heat flux onto positive diffusion only:

\[ \chi = \min\left[ \max(|\chi_{raw}|,\chi_{min}), \chi_{max} \right], \qquad v_T = 0 . \]

The represented flux becomes

\[ \Gamma_T^{repr} = -n\,\chi\,\nabla T . \]

If the raw model flux is up-gradient, this mode reverses it into a down-gradient diffusive representation of comparable magnitude. Mode 0 is numerically robust but does not preserve the original model heat flux.

Mode 1: positive diffusion plus convective residual

pt_num_diffusivity%heat_flux_split_mode = 1

Mode 1 is the default. It first constructs a non-negative diffusivity:

\[ \chi = \min\left[ \max(\chi_{raw},\chi_{min}), \chi_{max} \right] . \]

Then it chooses the heat convective velocity so that the total model flux is preserved:

\[ v_T = \frac{\Gamma_T^{model} + n\,\chi\,\nabla T} {n\,T} . \]

The represented flux is therefore

\[ \Gamma_T^{repr} = -n\,\chi\,\nabla T + n\,T\,v_T = \Gamma_T^{model} . \]

Mode 1 keeps \(\chi\) non-negative while preserving the original model heat flux. The residual flux is represented through \(v_T\).

Mode 2: suppress net up-gradient heat flux

pt_num_diffusivity%heat_flux_split_mode = 2

Mode 2 suppresses the part of the model heat flux that is net up-gradient. The criterion for up-gradient heat flux is

\[ \Gamma_T^{model}\,\nabla T_{eff} > 0 . \]

For ordinary down-gradient diffusion,

\[ \Gamma_T = -n\chi\nabla T, \]

so \(\Gamma_T \nabla T < 0\). Therefore, a positive product means the model flux reinforces the temperature gradient rather than relaxing it.

When an up-gradient flux is detected, mode 2 replaces the target flux with a minimum down-gradient diffusive flux:

\[ \Gamma_T^{use} = -n\,\chi_{min}\,\nabla T_{eff} . \]

The usual convective split is then applied to \(\Gamma_T^{use}\). This suppresses the anti-diffusive component before it is represented in the matrix.

Mode 3: limited convective residual

pt_num_diffusivity%heat_flux_split_mode = 3

Mode 3 starts from the mode-1 convective split but limits the residual heat velocity.

After computing

\[ v_T = \frac{\Gamma_T^{model} + n\,\chi\,\nabla T} {n\,T}, \]

the code computes a local temperature scale length,

\[ L_T = \frac{|T|} {\max(|\nabla T_{eff}|,|\nabla T_{floor}|)} , \]

and a velocity bound,

\[ |v_T| \le C_{Pe}\frac{\chi_{eff}}{L_T} . \]

In the current implementation,

\[ C_{Pe}=3, \]

so the effective local convective Peclet number is limited:

\[ Pe_T = \frac{|v_T|L_T}{\chi_{eff}} \le 3 . \]

Mode 3 keeps \(\chi\) non-negative, retains moderate residual heat convection, and limits very large residual heat convection. The represented flux may differ from the original model flux if the residual velocity is clipped.

Default and suggested use

The default heat-flux split is:

pt_num_diffusivity%heat_flux_split_mode = 1

This is the most conservative choice with respect to the transport model because it preserves the model heat flux while keeping the matrix diffusivity non-negative.

Mode	Short description	Flux preservation	Typical use
0	Positive-diffusion projection	No	Diagnostic control; removes heat convective residual
1	Positive diffusion plus convective residual	Yes	Default model-faithful split
2	Suppress up-gradient heat flux	Only for down-gradient fluxes	Stabilization when inverted heat flux is problematic
3	Limited convective residual	Approximately, unless velocity clipping is active	Stabilization when mode 1 produces excessive heat velocity

For rotation-driven QROT problems, prefer correcting the omega path first with NLQROT_OMEGA_CAP and, when needed, NLQROT_OMEGA_FILTER. Use the PT_SOLVER QROT cap as a local safety limiter on the Ti equation.