Simulation Inputs¶

The power simulation has four inputs the operator controls:

1. Time — wall-clock vs accelerated playback
2. DC source profile — irradiance CSV (PV), wind CSV, EV charge CSV (EVSE)
3. Grid environment — voltage and frequency, static or time-series
4. Nameplate — device ratings from a JSON file or one of the bundled defaults

Each input has both a CLI flag and a Modbus model 30004 register — external test harnesses can change any of them at runtime without restarting the simulator.

Time¶

The simulator's clock can run in wall-clock mode (real time, useful for live demos) or accelerated playback (compressed time, useful for test runs that need to replay a day in a minute).

When --wall_clock no (the default), the simulator runs on its own clock which can be advanced at a configurable rate — see --wind_time_scale in the Wind chapter and the profile-replay rate in the bundled CSVs.

Test harnesses can also override the clock via SunSpec model 30004 without restarting.

DC source profile¶

The DC-side input depends on the device type:

Override with -dc_p PATH / --dc_profile PATH. Files are read once at startup; for runtime changes use the dashboard's Simulation Inputs page or write SunSpec 30004 over Modbus.

CSV format¶

DERSim's profile CSVs are standard comma-separated with a header row. The expected columns differ per profile type:

Irradiance (PV / hybrid-DC / EVSE):

TimeUTC,DC In (W/m^2)
2/24/2018 00:00:00,0
2/24/2018 06:00:00,150
2/24/2018 12:00:00,950
2/24/2018 18:00:00,200

Timestamps are parsed as the playback timeline; rows can be at any cadence (1-second, hourly, etc.) — the simulator interpolates between them. The bundled irradiance.csv is a one-week clear-sky PV profile.

Wind (Wind-T3 / Wind-T4):

# NDBC Station 44025 (Long Island NY offshore buoy)
# 1 week of hourly wind observations, public domain (NOAA / NDBC)
timestamp_utc,wind_speed_m_s
2024-01-01T00:00:00Z,7.2
2024-01-01T01:00:00Z,8.1
2024-01-01T02:00:00Z,7.8

ISO 8601 timestamps. Comment lines starting with # are ignored. The bundled NDBC dataset is real offshore-buoy observation data — realistic for offshore wind tests.

Where to put profile files¶

Three places, in order of precedence:

1. Absolute path — --dc_profile /path/to/profile.csv works anywhere on disk. Recommended for one-off custom profiles.
2. Same directory as the binary — for the PyInstaller and Docker form factors, the simulator looks alongside /app/dersim.
3. Bundled defaults — relative names like irradiance.csv resolve to the simulator's bundled profiles. Useful for day-to-day lab runs; the bundled files are public-domain.

For Docker deployments that need a custom profile, bind-mount the file into the container and reference it by container-internal path:

docker run -v ./my_profile.csv:/profiles/custom.csv \
  ...:latest-amd64 --dc_profile /profiles/custom.csv

Grid environment¶

Grid voltage and frequency drive the inverter's grid-support modes. Both can be static (a single value at startup) or time-series (replayed from a CSV).

For lab runs that need deterministic grid conditions, set constants via SunSpec model 30004:

A SunSpec scanner can write these any time; the next inverter tick picks up the new values. The dashboard's Simulation Inputs page writes the same registers.

Nameplate¶

The nameplate is loaded from either a JSON file (custom) or one of the bundled device defaults:

# Custom nameplate
./sim -f /opt/dersim/profiles/custom_inverter.json

# Bundled device defaults
./sim --device_type PV-3Phase   # alias: PV
./sim --device_type PV-2Phase
./sim --device_type PV-1Phase
./sim --device_type Batt-3Phase # alias: Batt
./sim --device_type Batt-2Phase
./sim --device_type Batt-1Phase
./sim --device_type Wind-T3-3Phase
./sim --device_type Wind-T4-3Phase
./sim --device_type Fuelcell-3Phase
./sim --device_type HybridDC-3Phase

For the EVSE device type, see EVSE Profiles.

JSON nameplate format¶

A nameplate JSON populates one or more SunSpec models with operator-configured initial values. The simulator walks the loaded model list and applies any field declared in the file:

For fields not in the JSON, the simulator uses the bundled device-type defaults.

Runtime changes vs restart-only changes¶

Most fields can change at runtime — the dashboard's Simulation Inputs page and SunSpec model 30004 both write directly into the live state. A handful require a restart:

Everything else — nameplate fields, grid environment, profile choice, SoC, wind override, fuel cell setpoint, hybrid dispatch policy — accepts a live change via the REST API or SunSpec writes.