Functions#

Parametric functions for stochastic ground motion simulation.

Each class exposes its required parameter names via the param_names property for easy introspection and automation. .. tip:: These classes are callable: For exmaple use as stateful y = BetaPeakConcentration()(t, …) or as stateless y = BetaPeakConcentration.compute(t, …).

Examples

>>> import numpy as np
>>> from sgsim.Functions import BetaSingle, Linear, Constant
>>> t = np.linspace(0, 40, 4000)
>>> # Functional (stateless) usage
>>> y_env = BetaSingle.compute(t, peak=0.3, concentration=5.0, energy=100.0, duration=40.0)
>>> y_freq = Linear.compute(t, start=10.0, end=5.0)
>>> y_damp = Constant.compute(t, value=0.3)
>>>
>>> # Object-oriented (stateful) usage
>>> env = BetaSingle()
>>> y_env2 = env(t, peak=0.3, concentration=5.0, energy=100.0, duration=40.0)
>>> print(env.params)  # {'peak': 0.3, 'concentration': 5.0, 'energy': 100.0, 'duration': 40.0}

class sgsim.Functions.BetaPeakConcentration[source]#

Bases: ParametricFunction

Beta modulating function for earthquake ground motion simulation parameterized by peak and concentration.

Provides a smooth envelope function based on the Beta distribution, suitable for modeling single-phase earthquake strong motion.

Parameters:

peak (float) – Ratio of the peak location as fraction of duration (0 < peak < 1).
concentration (float) – Concentration parameter controlling sharpness (> 0).
energy (float) – Total energy under the envelope (> 0).
duration (float) – Total duration of the function (> 0).

See also

BetaCentroidSpread: Alternative Beta parameterization using centroid and spread.
BetaSingle: Beta function with weak motion baseline.
BetaDual: Beta function with two strong phases.

References

Broadband stochastic simulation of earthquake ground motions with multiple strong phases with an application to the 2023 Kahramanmaraş, Turkey (Türkiye), earthquake. https://doi.org/10.1177/87552930251331981

static compute(t, peak, concentration, energy, duration)[source]#

class sgsim.Functions.BetaCentroidSpread[source]#

Bases: ParametricFunction

Beta modulating function for earthquake ground motion simulation parameterized by physical moments.

Provides a smooth envelope function based on the Beta distribution, suitable for modeling single-phase earthquake strong motion.

Parameters:

centroid (float) – Ratio of the energy center of mass (0 < centroid < 1).
spread (float) – Ratio of the standard deviation of the energy envelope to the duration (0 < spread < 1).
energy (float) – Total energy under the envelope (> 0).
duration (float) – Total duration of the function (> 0).

See also

BetaPeakConcentration: Basic Beta function parameterized by peak and concentration.
BetaSingle: Beta function with weak motion baseline.
BetaDual: Beta function with two strong phases.

References

static compute(t, centroid, spread, energy, duration)[source]#

class sgsim.Functions.BetaSingle[source]#

Bases: ParametricFunction

Beta modulating function with a weak motion baseline parameterized by peak and concentration.

Combines a parabolic weak motion component (5% energy) with a Beta distribution strong motion component (95% energy) for realistic earthquake ground motion envelopes.

Parameters:

peak (float) – Ratio of the peak location as fraction of duration (0 < peak < 1).
concentration (float) – Concentration parameter controlling sharpness (> 0).
energy (float) – Total energy under the envelope (> 0).
duration (float) – Total duration of the function (> 0).

See also

BetaPeakConcentration: Basic Beta function without weak motion.
BetaCentroidSpread: Alternative Beta parameterization using centroid and spread.
BetaDual: Beta function with two strong phases.

References

static compute(t, peak, concentration, energy, duration)[source]#

class sgsim.Functions.BetaDual[source]#

Bases: ParametricFunction

Beta modulating function with two distinct strong phases parameterized by peak and concentration.

Models earthquakes with multiple strong motion packets, combining weak motion baseline (5% energy) with two independent Beta distributions representing separate strong motion phases.

Parameters:

peak (float) – Peak location of first strong phase as fraction of duration (0 < peak < 1).
concentration (float) – Concentration parameter of first phase (> 0).
peak_2 (float) – Peak location of second strong phase as fraction of duration (0 < peak_2 < 1).
concentration_2 (float) – Concentration parameter of second phase (> 0).
energy_ratio (float) – Energy fraction allocated to first strong phase (0 < energy_ratio < 0.95).
energy (float) – Total energy under the envelope (> 0).
duration (float) – Total duration of the function (> 0).

See also

BetaPeakConcentration: Basic Beta function without weak motion.
BetaCentroidSpread: Alternative Beta parameterization using centroid and spread.
BetaSingle: Single strong phase with weak motion.

References

static compute(t, peak, concentration, peak_2, concentration_2, energy_ratio, energy, duration)[source]#

class sgsim.Functions.Gamma[source]#

Bases: ParametricFunction

Gamma distribution modulating function.

Classical envelope function for earthquake ground motion based on Gamma distribution with exponential decay.

Parameters:

scale (float) – Amplitude scaling factor (> 0).
shape (float) – Shape parameter controlling rise time (> 0).
decay (float) – Decay rate parameter (> 0).

See also

BetaSingle: Alternative Beta-based envelope.
Housner: Piecewise envelope function.

static compute(t, scale, shape, decay)[source]#

class sgsim.Functions.Housner[source]#

Bases: ParametricFunction

Housner piecewise modulating function.

Three-phase envelope function: quadratic rise, constant plateau, and exponential decay. Classic model for earthquake strong motion.

Parameters:

amplitude (float) – Constant amplitude during plateau phase (> 0).
decay (float) – Decay rate during tail phase (> 0).
shape (float) – Decay shape exponent (> 0).
tp (float) – Time to reach peak amplitude (> 0).
td (float) – Time to start decay phase (td > tp).

See also

Gamma: Alternative smooth envelope.
BetaSingle: Beta-based envelope function.

static compute(t, amplitude, decay, shape, tp, td)[source]#

class sgsim.Functions.Linear[source]#

Bases: ParametricFunction

Linear interpolation function.

Provides linear transition between start and end values over the time domain.

Parameters:

start (float) – Starting value at t=0.
end (float) – Ending value at t=max(t).

See also

Bilinear: Piecewise linear with midpoint.
Exponential: Exponential interpolation.

static compute(t, start, end)[source]#

class sgsim.Functions.Bilinear[source]#

Bases: ParametricFunction

Piecewise linear interpolation function.

Provides two-segment linear transition through a specified midpoint, useful for modeling parameters with intermediate changes.

Parameters:

start (float) – Starting value at t=0.
mid (float) – Value at midpoint time.
end (float) – Ending value at t=max(t).
t_mid (float) – Time at midpoint (0 < t_mid < max(t)).

See also

Linear: Simple linear interpolation.
Exponential: Smooth exponential transition.

static compute(t, start, mid, end, t_mid)[source]#

class sgsim.Functions.Exponential[source]#

Bases: ParametricFunction

Exponential interpolation function.

Provides smooth exponential transition between start and end values, useful for parameters varying over orders of magnitude.

Parameters:

start (float) – Starting value at t=0 (> 0).
end (float) – Ending value at t=max(t) (> 0).

See also

Linear: Linear interpolation.
Bilinear: Piecewise linear with midpoint.

static compute(t, start, end)[source]#

class sgsim.Functions.Constant[source]#

Bases: ParametricFunction

Constant value function.

Provides time-invariant parameter values throughout the time domain.

Parameters:: value (float) – Constant value for all time points.

See also

Linear: Time-varying linear function.

static compute(t, value)[source]#