Struct DiffSettings 

pub struct DiffSettings {
    pub scheme: DiffScheme,
    pub relative_step: f64,
    pub min_scale: f64,
}

Step-size policy for every entry point in this module.

The step-size rule

h = relative_step * max(|x|, min_scale)

The step is relative to the magnitude of the variable being perturbed, because a step that is right for x ~ 1 is far too small for a pressure in pascals and far too large for a mole fraction. min_scale is the floor that keeps the rule usable at x = 0 — see Self::step_for.

Units

relative_step is dimensionless. min_scale carries the same units as the variable being differentiated with respect to, because it is a fallback magnitude for x, and its default of 1.0 therefore means “one of whatever unit x is in”. A caller differentiating with respect to a pressure in pascals near zero wants min_scale set to a pascal-scale number, not 1.0.

Fields

scheme: DiffScheme

Which stencil to use. See DiffScheme.

relative_step: f64

The relative step, dimensionless. Defaults to DiffScheme::default_relative_step for the chosen scheme.

min_scale: f64

Floor on |x| in the step rule, so x = 0 still gets a usable step. Same units as x. Default 1.0.

Implementations

impl DiffSettings

pub fn with_scheme(scheme: DiffScheme) -> Self

Settings for scheme, with that scheme’s optimal relative step and min_scale = 1.0.

Example

use outram_foam_basic_lib::math::differentiate::{DiffScheme, DiffSettings};

let s = DiffSettings::with_scheme(DiffScheme::Central);
assert_eq!(s.relative_step, DiffScheme::Central.default_relative_step());
assert_eq!(s.min_scale, 1.0);

pub fn forward() -> Self

DiffScheme::Forward with its optimal relative step — the n + 1 evaluation Jacobian.

pub fn backward() -> Self

DiffScheme::Backward with its optimal relative step.

pub fn central() -> Self

DiffScheme::Central with its optimal relative step — the 2n evaluation Jacobian, and the scheme both existing workspace implementations use.

pub fn central_4th() -> Self

DiffScheme::Central4th with its optimal relative step — the 4n evaluation Jacobian. Same as Self::default.

pub fn step_for(&self, x: f64) -> f64

The step this policy uses to perturb a variable currently at x.

h = relative_step * max(|x|, min_scale)

What happens at x = 0

A purely relative step relative_step * |x| is exactly zero at x = 0, which would divide by zero and hand back NaN or inf. The max(|x|, min_scale) floor is what prevents that: at x = 0 the step becomes relative_step * min_scale, i.e. an absolute step of relative_step in the default min_scale = 1.0 case.

This is the convention already settled elsewhere in this workspace — outram-park-fork-offbeat‘s newton_perturbed uses perturbation * x.abs().max(1.0) for exactly this reason. It is not the convention outram-park-fork-dwsim-libs’ finite_difference_jacobian uses; see the module-level “Provenance” section for that divergence and why.

The same floor also rescues the near-zero case, which is the one that actually bites: at x = 1e-300 a relative step is 1e-308-ish, so x + h rounds straight back to x and the difference is identically zero. That is reported as DiffStatus::DegenerateStep, not as a derivative of zero.

Returns

The step, in the same units as x. Non-finite or non-positive results are possible if the caller supplies a nonsensical relative_step, and are caught by the kernels rather than by this function.

Example

use outram_foam_basic_lib::math::differentiate::DiffSettings;

let s = DiffSettings::central();
// Relative where |x| is large ...
assert_eq!(s.step_for(1000.0), s.relative_step * 1000.0);
// ... absolute where it is not, so x = 0 still works.
assert_eq!(s.step_for(0.0), s.relative_step);
assert_eq!(s.step_for(-1000.0), s.relative_step * 1000.0);

Trait Implementations

impl Clone for DiffSettings

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for DiffSettings

impl Debug for DiffSettings

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DiffSettings

fn default() -> Self

DiffScheme::Central4th with its optimal relative step and min_scale = 1.0.

The default is the most accurate scheme rather than the cheapest, because a caller who has not thought about step size is far more likely to be surprised by a wrong derivative than by four function evaluations.

impl PartialEq for DiffSettings

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for DiffSettings