Core Concepts

This page introduces the main parameter models, result objects, and workflow conventions used across fdscore.

Parameter Models

The public API is built around a small set of frozen dataclasses that define fatigue, oscillator, PSD, and inversion settings.

SNParams

SNParams defines the S-N fatigue curve used by Miner damage accumulation.

from fdscore import SNParams

sn = SNParams.normalized(slope_k=6.0)
sn_physical = SNParams(slope_k=6.0, ref_stress=120.0, ref_cycles=1e6)

Key ideas:

  • slope_k controls the fatigue exponent.

  • ref_stress and ref_cycles define the reference point of the S-N curve.

  • amplitude_from_range controls whether rainflow ranges are interpreted as 2 * amplitude or as amplitude directly.

SDOFParams

SDOFParams defines the oscillator bank used by FDS, ERS, SRS, and PVSS workflows.

from fdscore import SDOFParams

sdof = SDOFParams(q=10.0, metric="pv", fmin=10.0, fmax=200.0, df=10.0)

The main fields are:

  • q: quality factor, with damping ratio zeta = 1 / (2Q).

  • metric: "pv", "acc", "vel", or "disp".

  • frequency definition: either explicit f or linear fmin, fmax, df.

PSDParams

PSDParams configures Welch PSD estimation and related spectral preprocessing choices used by workflows such as compute_psd_welch(...) and compute_fds_spectral_time(...).

IterativeInversionParams

IterativeInversionParams controls the multiplicative update logic used by the iterative inversion engines. It groups convergence, smoothing, prior, and regularization settings into one explicit object instead of scattering them across many keyword arguments.

SineDwellSegment

SineDwellSegment defines one harmonic dwell used by deterministic mission profiles and dwell-discretized sine sweeps.

Result Objects

The library returns frozen dataclasses rather than ad-hoc dictionaries. The main public result types are:

Object

Role

FDSResult

Miner damage spectrum over oscillator frequency

ERSResult

Extreme response spectrum for the selected metric

PSDResult

One-sided acceleration PSD plus diagnostics

PSDMetricsResult

Scalar PSD-derived metrics such as RMS and peak estimates

ShockSpectrumPair

Explicit negative/positive sided shock spectrum pair

ShockEventSet

Detected shock windows and detector metadata

RollingERSResult

Event-by-event stacked spectra

HalfSinePulse

Equivalent half-sine pulse fit

FDSTimePlan

Reusable FFT-domain transfer plan for repeated FDS calls

Compatibility Metadata

Most results expose a structured compatibility signature in meta["compat"]. This signature is used to validate safe composition and inversion.

Examples:

  • sum_fds(...) requires compatible FDS semantics and the same oscillator grid.

  • invert_fds_closed_form(...) requires compatible fatigue semantics but does not require the candidate PSD grid to match the FDS grid.

  • shock envelope helpers require compatible shock-spectrum semantics.

See compatibility.md for the detailed rules.

Normalized and Physical Workflows

fdscore supports two equally valid fatigue parameterizations.

Normalized Workflow

Use a normalized S-N definition when the main interest is FDS shape, comparison, and equivalent PSD inversion.

sn = SNParams.normalized(slope_k=4.0)

In this case, p_scale=1.0 is the natural default.

Physical Workflow

Use a physical S-N definition when the absolute Miner damage level matters.

sn = SNParams(slope_k=6.0, ref_stress=120.0, ref_cycles=1e6)
p_scale_physical = 300.0

For fixed slope_k, the combination of ref_stress, ref_cycles, and p_scale acts as a global damage scaling factor. It changes the magnitude of the FDS but not its relative shape.

Reusable Transfer Plans

FDSTimePlan exists for repeated time-domain FDS evaluations on signals that share the same sampling setup and oscillator definition.

from fdscore import prepare_fds_time_plan

plan = prepare_fds_time_plan(fs=fs, n_samples=len(x), sdof=sdof)

The plan stores the full FFT-domain transfer matrix H, which improves reuse performance at the cost of memory. This is usually worthwhile when evaluating multiple channels or repeated realizations over the same grid.

Spectrum Families in fdscore

The library uses several related but distinct spectrum concepts:

  • FDS: accumulated fatigue damage per oscillator.

  • ERS: extreme response spectrum for a selected response metric.

  • SRS: shock response spectrum, implemented through a dedicated recursive shock backend and restricted to sdof.metric="acc".

  • PVSS: pseudo-velocity shock spectrum, also implemented through the shock backend and restricted to sdof.metric="pv".

  • PSD: one-sided acceleration power spectral density.

Those objects are intentionally separate because they serve different physical purposes and obey different composition rules.