Simulation#

Generate autoregressive signals, classical dynamical systems, noise, and sensor mixtures. Frequency-based AR construction uses Hz; coefficient schedules specify variation over sample indices.

Autoregressive Signals#

neuralfieldmanifold.simulation.coefficients_from_modes(frequencies_hz, pole_radii, *, sampling_rate_hz)[source]#

Build AR(2K) coefficients from conjugate oscillatory pole pairs.

neuralfieldmanifold.simulation.ar(coefficients, *, n_samples, noise_std=1.0, seed=42, innovations=None, initial_lags=None)[source]#

Stationary AR with newest-lag-first coefficients, returned as float32.

The first order samples are zero unless initial_lags (oldest first) is supplied. Innovations are additive samples, already scaled; supplying them bypasses random number generation.

neuralfieldmanifold.simulation.tvar(coefficients, *, noise_std=0.3, seed=42, burn_in_samples=500, target_power=None, power_window_samples=40, max_abs=1000000.0, innovations=None)[source]#

Simulate a signal with time-varying autoregressive coefficients.

Parameters:

  • coefficients (array_like, shape (n_samples, order)) – Coefficient path, with lag 1 first.

  • noise_std (float) – Standard deviation of generated Gaussian innovations.

  • seed (int) – Random seed.

  • burn_in_samples (int) – Number of initial samples to discard. Burn-in uses the first coefficient vector.

  • target_power (float or None) – Optional rolling mean-square power target. Enables per-sample multiplicative correction, clipped to 0.8-1.2, and rejects signals whose final rolling power exceeds the target.

  • power_window_samples (int) – Window length for power control.

  • max_abs (float) – Maximum permitted absolute amplitude.

  • innovations (array_like or None) – Additive noise, already scaled, including burn-in samples.

Returns:

Simulated signal with float32 dtype.

Return type:

ndarray, shape (n_samples,)

Raises:

SimulationRejected – If the amplitude or rolling-power bounds are exceeded.

exception neuralfieldmanifold.simulation.SimulationRejected[source]#

A generated signal exceeded the requested amplitude or power bounds.

Dynamical Systems#

neuralfieldmanifold.simulation.lorenz(n_samples=12000, *, dt=0.005, sigma=10.0, rho=28.0, beta=2.6666666666666665, initial_state=(1.0, 1.0, 1.0))[source]#

Integrate the Lorenz system with fourth-order Runge-Kutta steps.

Parameters:

  • n_samples (int) – Number of integration steps.

  • dt (float) – Time step.

  • sigma (float) – Lorenz system parameters.

  • rho (float) – Lorenz system parameters.

  • beta (float) – Lorenz system parameters.

  • initial_state (tuple of float) – Initial x, y, and z coordinates.

Returns:

Trajectory beginning after the first integration step. The initial transient is included.

Return type:

ndarray, shape (n_samples, 3)

neuralfieldmanifold.simulation.ornstein_uhlenbeck(n_samples, *, dt=0.005, theta=2.0, mean=0.0, sigma=1.0, initial=0.0, seed=0, method='exact', innovations=None)[source]#

OU process using exact or Euler transitions; first state follows one step.

Supplied innovations are standard-normal draws, not scaled noise.

neuralfieldmanifold.simulation.rotating_var(n_samples, *, burn_in_samples=300, alpha=(0.45, 0.35, 0.3), beta=(-0.1, -0.08, -0.06), periods_samples=(500.0, 900.0), noise_scale=1.0, seed=0, innovations=None)[source]#

Three-dimensional rotating VAR(2), returned as a NumPy array.

Innovations have shape (n_samples + burn_in_samples, 3) and are supplied already scaled when provided.

Noise#

neuralfieldmanifold.simulation.white_noise(n_samples, *, seed=0)[source]#

Return standard-normal samples from NumPy’s default generator.

neuralfieldmanifold.simulation.colored_noise(n_samples, *, exponent=1.0, seed=0, spectrum=None)[source]#

Generate zero-mean, unit-variance noise with a power-law spectrum.

Parameters:

  • n_samples (int) – Number of output samples, at least two.

  • exponent (float) – Spectral exponent; power is proportional to 1/f**exponent.

  • seed (int) – Seed for the NumPy random generator.

  • spectrum (array_like of complex or None) – Optional unweighted Fourier bins, shape (n_samples // 2 + 1,). When supplied, these replace the random Fourier coefficients.

Returns:

Real-valued colored noise.

Return type:

ndarray, shape (n_samples,)

Source Mixing#

neuralfieldmanifold.simulation.oscillatory_ar(frequencies_hz, pole_radii, *, sampling_rate_hz, n_samples, noise_std=0.05, seed=0, random_initialization=False, amplitude=1.0)[source]#

Generate an oscillatory AR source scaled to the requested amplitude.

The AR characteristic polynomial combines conjugate pole pairs. The output is divided by its standard deviation and multiplied by amplitude.

random_initialization=True initializes the lag history with Gaussian draws. Otherwise the initial history is zero.

neuralfieldmanifold.simulation.mixing_matrix(*, n_sensors, n_sources, spatial_spread)[source]#

Row-normalized Gaussian distance weights on uniformly spaced locations.

Coefficient Schedules#

neuralfieldmanifold.simulation.schedules.sinusoid(n_samples, order, rng, freq_jitter=0.15, amp_jitter=0.15)[source]#

Sinusoidal coefficient schedule with per-lag variation.

Each lag gets a distinct base frequency, amplitude, and offset with small random jitter for stochastic diversity across samples.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

  • freq_jitter (float, optional) – Relative frequency jitter range. Default is 0.15.

  • amp_jitter (float, optional) – Relative amplitude jitter range. Default is 0.15.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray

neuralfieldmanifold.simulation.schedules.fourier(n_samples, order, rng, M=3, amp_jitter=0.2)[source]#

Fourier-series coefficient schedule with decaying harmonics.

Each lag is represented by a truncated Fourier series with M harmonics whose amplitudes decay as 1 / m^1.2.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

  • M (int, optional) – Number of Fourier harmonics per lag. Default is 3.

  • amp_jitter (float, optional) – Relative amplitude jitter per harmonic. Default is 0.2.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray

neuralfieldmanifold.simulation.schedules.quasiperiodic(n_samples, order, rng, freq_jitter=0.15)[source]#

Quasiperiodic coefficient schedule with two incommensurate frequencies.

Each lag combines two sinusoidal components whose frequency ratio is irrational, producing non-repeating oscillatory patterns.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

  • freq_jitter (float, optional) – Relative frequency jitter range. Default is 0.15.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray

neuralfieldmanifold.simulation.schedules.polynomial_drift(n_samples, order, rng, degree=3, coef_jitter=0.3)[source]#

Polynomial-drift coefficient schedule.

Each lag’s trajectory is a random polynomial of the given degree centred on the lag-specific offset.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

  • degree (int, optional) – Polynomial degree. Default is 3.

  • coef_jitter (float, optional) – Relative jitter on polynomial coefficients. Default is 0.3.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray

neuralfieldmanifold.simulation.schedules.logistic_transition(n_samples, order, rng)[source]#

Single logistic-transition coefficient schedule.

Each lag transitions between two distinct levels via a sigmoid whose centre and steepness are randomised.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray

neuralfieldmanifold.simulation.schedules.multi_sigmoid(n_samples, order, rng, J=3)[source]#

Multi-sigmoid step coefficient schedule.

Superimposes J sigmoid transitions of random magnitude and steepness around each lag’s baseline offset.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

  • J (int, optional) – Number of sigmoid steps per lag. Default is 3.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray

neuralfieldmanifold.simulation.schedules.gaussian_bumps(n_samples, order, rng, J=4)[source]#

Gaussian-bump coefficient schedule.

Overlays J Gaussian-shaped bumps of random centre, width, and sign on each lag’s baseline offset.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

  • J (int, optional) – Number of Gaussian bumps per lag. Default is 4.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray

neuralfieldmanifold.simulation.schedules.smooth_random(n_samples, order, rng)[source]#

Smooth random (GP-like) coefficient schedule.

Generates spectrally shaped Gaussian noise with a long correlation length, producing smooth, aperiodic coefficient trajectories centred on each lag’s baseline.

Parameters:

  • n_samples (int) – Length of the time series.

  • order (int) – AR order (number of lags).

  • rng (np.random.Generator) – NumPy random generator instance.

Returns:

a – Time-varying AR coefficients of shape (n_samples, order).

Return type:

np.ndarray