Programmatic API

The simulator_api module provides a Python function for running simulations without the CLI.

run_simulation()

from simulator_api import run_simulation

frames = run_simulation(
    atmosphere_params=None,
    simulation_params=None,
    use_gpu=True,
    generate_dataset=False,
    num_datasets=1,
    config=None,
)

Parameters

Parameter	Type	Default	Description
atmosphere_params	dict or None	None	Override atmosphere parameters
simulation_params	dict or None	None	Override simulation parameters
use_gpu	bool	True	Use GPU-accelerated simulator
generate_dataset	bool	False	Generate multiple datasets
num_datasets	int	1	Number of datasets (when generate_dataset=True)
config	dict or None	None	Full config dict (overrides loading from file)

Atmosphere Parameter Keys

Key	Type	Description
num_layers	int	Number of atmospheric layers
total_r0	float	Fried parameter (meters)
phase_screen_size	int	Grid size in pixels
delta	float	Pixel scale (meters)
ground_wind_speed	float	Ground wind speed (m/s)
L0	float	Outer scale (meters)
wavefront_wavelength	float	Wavelength (meters)
satellite_zenith_angle_starting	float	Zenith angle (degrees)

Simulation Parameter Keys

Key	Type	Description
whole_simulation_time	float	Total duration (seconds)
per_tick_simulation	float	Time step (seconds)
satellite_orbit	float	Orbit altitude (meters)

Return Value

• Single run: np.ndarray of shape (steps, 2, nx_size, nx_size)
  • Channel 0: phase (radians)
  • Channel 1: amplitude (unitless)
• Dataset mode: np.ndarray of shape (num_datasets, steps, 2, nx_size, nx_size)

Errors

Raises ValueError if an unknown parameter key is passed in atmosphere_params or simulation_params.

Examples

Basic Run

from simulator_api import run_simulation

frames = run_simulation()
print(f"Shape: {frames.shape}")
# Shape: (100, 2, 2048, 2048)

Custom Atmosphere

frames = run_simulation(
    atmosphere_params={
        'num_layers': 10,
        'total_r0': 0.15,
        'phase_screen_size': 1024,
    }
)

Custom Simulation Duration

frames = run_simulation(
    simulation_params={
        'whole_simulation_time': 0.05,
        'per_tick_simulation': 0.0005,
    }
)
# Produces 100 time steps at 0.5 ms resolution

Generate a Dataset

dataset = run_simulation(
    generate_dataset=True,
    num_datasets=5,
    atmosphere_params={'phase_screen_size': 512},
)
print(dataset.shape)
# (5, steps, 2, 512, 512)

Provide a Full Config

from core.utils import load_config

config = load_config('my_config.json')
frames = run_simulation(config=config)

note

The programmatic API always uses the simulate_turb() runner (single-shot GPU). For streaming mode, use the CLI with --runner chunked.