StochasticModel#

class sgsim.StochasticModel(npts, dt, modulating, upper_frequency, upper_damping, lower_frequency, lower_damping, params=None)[source]#

Bases: Domain

Stochastic ground motion model.

Parameters:

npts (int) – Number of time points.
dt (float) – Time step.
modulating (np.ndarray) – Time-varying modulating function.
upper_frequency (np.ndarray) – Upper frequency function in Hz.
upper_damping (np.ndarray) – Upper damping function.
lower_frequency (np.ndarray) – Lower frequency function in Hz.
lower_damping (np.ndarray) – Lower damping function.
params (dict, optional) – Original parameters dictionary used to create the model.

Examples

>>> params = {
...     'modulating': {'type': 'BetaBasic', 'params': [0.1, 10.0, 1.0, 25.0]},
...     'upper_frequency': {'type': 'Linear', 'params': [8.0, 1.5]},
...     'upper_damping': {'type': 'Constant', 'params': [0.5]},
...     'lower_frequency': {'type': 'Linear', 'params': [1.0, 0.5]},
...     'lower_damping': {'type': 'Constant', 'params': [0.3]},
... }
>>> model = StochasticModel.load_from(params, npts, dt)
>>> model.fas.shape
(1000,)
>>> import matplotlib.pyplot as plt
>>> plt.plot(model.t, model.ac)
>>> plt.show()
>>> plt.plot(model.freq / (2 * np.pi), model.fas)
>>> plt.show()

classmethod load_from(params, npts, dt)[source]#

Create StochasticModel from a parameters dictionary.

Parameters:

params (dict) – Dictionary containing model parameters (usually from ModelFitter.fit()).
npts (int) – Number of time points.
dt (float) – Time step.

Returns:

Initialized stochastic model.

Return type:

StochasticModel

save(filename)[source]#

Save model parameters to a JSON file.

Parameters:: filename (str) – Path to the output JSON file (Recommeded to use .json extension).

Examples

>>> model.save("my_model.json")

property fas#

Fourier amplitude spectrum (FAS) of acceleration.

Returns:: FAS computed using the model’s PSD.
Return type:: ndarray

property fas_vel#

Fourier amplitude spectrum (FAS) of velocity.

Returns:: FAS computed using the model’s PSD.
Return type:: ndarray

property fas_disp#

Fourier amplitude spectrum (FAS) of displacement.

Returns:: FAS computed using the model’s PSD.
Return type:: ndarray

property ce[source]#

Cumulative energy of the stochastic model.

Returns:: Cumulative energy time history.
Return type:: ndarray

property le_ac[source]#

Mean cumulative local extrema count of acceleration.

Returns:: Cumulative count of acceleration local extrema.
Return type:: ndarray

property le_vel[source]#

Mean cumulative local extrema count of velocity.

Returns:: Cumulative count of velocity local extrema.
Return type:: ndarray

property le_disp[source]#

Mean cumulative local extrema count of displacement.

Returns:: Cumulative count of displacement local extrema.
Return type:: ndarray

property zc_ac[source]#

Mean cumulative zero crossing count of acceleration.

Returns:: Cumulative count of acceleration zero crossings.
Return type:: ndarray

property zc_vel[source]#

Mean cumulative zero crossing count of velocity.

Returns:: Cumulative count of velocity zero crossings.
Return type:: ndarray

property zc_disp[source]#

Mean cumulative zero crossing count of displacement.

Returns:: Cumulative count of displacement zero crossings.
Return type:: ndarray

property pmnm_ac[source]#

Mean cumulative PMNM count of acceleration.

Returns:: Cumulative count of acceleration positive-minima and negative-maxima.
Return type:: ndarray

property pmnm_vel[source]#

Mean cumulative PMNM count of velocity.

Returns:: Cumulative count of velocity positive-minima and negative-maxima.
Return type:: ndarray

property pmnm_disp[source]#

Mean cumulative PMNM count of displacement.

Returns:: Cumulative count of displacement positive-minima and negative-maxima.
Return type:: ndarray

simulate(n, tag=None, seed=None)[source]#

Simulate ground motions using the stochastic model.

Parameters:

n (int) – Number of simulations to generate.
tag (any, optional) – Identifier for the simulation batch.
seed (int, optional) – Random seed for reproducibility.

Returns:

Simulated ground motions with acceleration, velocity, and displacement.

Return type:

GroundMotion

simulate_conditional(n, target, metrics, max_iter=100)[source]#

Conditionally simulate ground motions until GoF metrics are met.

Parameters:

n (int) – Number of simulations to generate.
target (GroundMotion) – Target ground motion to compare against.
metrics (dict) – Conditioning metrics with GoF thresholds, e.g., {‘sa’: 0.9}.
max_iter (int, optional) – Maximum attempts per required simulation.

Returns:

Simulated ground motions meeting all GoF thresholds.

Return type:

GroundMotion

Raises:

RuntimeError – If not enough simulations meet thresholds within max_iter * n attempts.

summary()[source]#

Print model parameters.

Returns:: Self for method chaining.
Return type:: Model