Simulation Settings

This page describes the simulation customizations available in the settings file (simulation.toml).

Refer to Default Simulation Settings for a default file.

SimulationSettings

Property	Type	Description	Required	Default
project	Project	Project settings	True
exports	Exports	Exports settings	False
frequency	Frequency	Frequency settings	False
helics	Helics	HELICS settings	False
logging	Logging	Logging settings	False
monte_carlo	MonteCarlo	Monte Carlo settings	False
plots	Plots	Plots settings	False
profiles	Profiles	Profiles settings	False
reports	Reports	Reports settings	False

Project

Property	Type	Description	Required	Default
project_path	string	Base path of project. Join with ‘active_project’ to get full path	True
active_project	string	Active project name. Join with ‘project_path’ to get full path	True
scenarios	array	List of scenarios	False	[]
active_scenario	string	Name of active scenario	False
start_time	string	Start time of simulation	False	2020-01-01 00:00:00.0
simulation_duration_min	number	Simulation duration in minutes.	False	1440.0
step_resolution_sec	number	Time step resolution in seconds	False	900.0
loadshape_start_time	string	Start time of loadshape profiles	False	2020-01-01 00:00:00.0
simulation_range	SimulationRange	Restrict control algorithms and data collection to these hours. Useful for skipping night when simulating PV Systems.	False	{‘start’: ‘00:00:00’, ‘end’: ‘23:59:59’}
simulation_type	SimulationType	Type of simulation to run. dynamic qsts snapshot	False	qsts
control_mode	ControlMode	Simulation control mode Static Time	False	Static
max_control_iterations	integer	Maximum outer loop control iterations	False	50
convergence_error_threshold	number	Convergence error threshold as a percent	False	0.0
error_tolerance	number	Error tolerance in per unit	False	0.001
max_error_tolerance	number	Abort simulation if a convergence error exceeds this value.	False	0.0
skip_export_on_convergence_error	boolean	Do not export data at a time point if there is a convergence error.	False	True
dss_file	string	OpenDSS master filename	False	Master.dss
dss_file_absolute_path	boolean	Set to true if ‘dss_file’ is an absolute path.	False	False
disable_pydss_controllers	boolean	Allows disabling of the control algorithms	False	False
use_controller_registry	boolean	Use local controller registry.	False	False

Scenario

Property	Type	Description	Required	Default
name	string	Name of scenario	True
post_process_infos	array	Post-process script descriptors	False	[]
snapshot_time_point_selection_config	SnapshotTimePointSelectionConfig	Descriptor for auto-selecting snapshot time points	False	{‘mode’: ‘none’, ‘start_time’: ‘2020-01-01T00:00:00’, ‘search_duration_min’: 1440.0}

ScenarioPostProcess

Property	Type	Description	Required	Default
script	string	Post-process script	True
config_file	string	Post-process config file	True

SnapshotTimePointSelectionConfig

Property	Type	Description	Required	Default
mode	SnapshotTimePointSelectionMode	Mode max_pv_load_ratio max_load daytime_min_load pv_minus_load none	False	none
start_time	string	Start time in the load shape profiles	False	2020-1-1 00:00:00.0
search_duration_min	number	Duration in minutes to search in the load shape profiles	False	1440.0

Exports

Property	Type	Description	Required	Default
export_results	boolean	Set to true to export circuit element values at each time point.	False	False
export_elements	boolean	Set to true to export static information for all circuit elements.	False	True
export_element_types	array	Restrict ‘export_elements’ to these element types. Default is all types	False	[]
export_data_tables	boolean	Set to true to export circuit element data in tabular files. While it does duplicate data, it provides a way to preserve a human-readable dataset that does not require PyDSS to interpret.	False	True
export_pv_profiles	boolean	Set to true to export PV profiles to tabular files.	False	False
export_data_in_memory	boolean	Set to true to keep circuit element data in memory rather than periodically flushing to an HDF5 file. This can be faster but will consume more memory.	False	False
export_node_names_by_type	boolean	Set to true to export node names by primary/secondary type to a file.	False	False
export_event_log	boolean	Set to true to export the OpenDSS event log.	False	True
export_format	FileFormat	Controls the file format used if export_data_tables is true. csv h5	False	h5
export_compression	boolean	Set to true to compress data exported with ‘export_data_tables’.	False	False
hdf_max_chunk_bytes	integer	The chunk size in bytes to use for exported data in the HDF5 data store. The value is passed to the h5py package. Refer to http://docs.h5py.org/en/stable/high/dataset.html#chunked-storage for more information.	False	524288

Frequency

Property	Type	Description	Required	Default
enable_frequency_sweep	boolean	Enable harmonic sweep. Works with only ‘Static’ and ‘QSTS’ simulation modes.	False	False
fundamental_frequency	number	Fundamental system frequeny in Hertz	False	60.0
start_frequency	number	Start system frequeny in Hertz	False	1.0
end_frequency	number	End system frequeny in Hertz	False	15.0
frequency_increment	number	As multiple of fundamental	False	2.0
neglect_shunt_admittance	boolean	Neglect shunt addmittance for frequency sweep	False	False
percentage_load_in_series	number	Percent of load that is series RL for Harmonic studies	False	50.0

Helics

Property	Type	Description	Required	Default
co_simulation_mode	boolean	Set to true to enable the HELICS interface for co-simulation.	False	False
iterative_mode	boolean	Iterative mode	False	False
error_tolerance	number	Error tolerance	False	0.0001
max_co_iterations	integer	Max number of co-simulation iterations	False	15
broker	string	Broker name	False	mainbroker
broker_port	integer	Broker port	False	0
federate_name	string	Name of the federate	False	PyDSS
time_delta	number	The property controlling the minimum time delta for a federate.	False	0.01
core_type	string	Core type to be use for communication	False	zmq
uninterruptible	boolean	Can the federate be interrupted	False	True
logging_level	integer	Logging level for the federate. Refer to HELICS documentation.	False	5

Logging

Property	Type	Description	Required	Default
logging_level	LoggingLevel	PyDSS minimum logging level debug info warning error	False	info
enable_console	boolean	Set to true to enable console logging.	False	True
enable_file	boolean	Set to true to enable logging to a file.	False	True
clear_old_log_file	boolean	Set to true to clear and overwrite any existing log files.	False	False
log_time_step_updates	boolean	Set to true to log each completed time step.	False	True

MonteCarlo

Property	Type	Description	Required	Default
num_scenarios	integer	Number of Monte Carlo scenarios	False	-1

Plots

Property	Type	Description	Required	Default
create_dynamic_plots	boolean	Enable rendering of dynamic plots using bokeh. Dependent on ‘open_plots_in_browser’	False	False
open_plots_in_browser	boolean	Open plots in a browser.	False	True

Profiles

Property	Type	Description	Required	Default
use_profile_manager	boolean	Set to true to enable the Profile Manager.	False	False
source_type	FileFormat	File format for source data csv h5	False	h5
source	string	File containing source data	False	Profiles_backup.hdf5
profile_mapping	string	Profile mapping	False
is_relative_path	boolean	Source file path is relative	False	True
settings	object	Profiles settings	False	{}

Reports

Property	Type	Description	Required	Default
format	FileFormat	Controls the file format. csv h5	False	h5
granularity	ReportGranularity	Specifies the granularity on which data is collected. per_element_per_time_point per_element_total all_elements_per_time_point all_elements_total	False	per_element_per_time_point
types	array	Reports to collect.	False	[]

SimulationRange

Property	Type	Description	Required	Default
start	string	Time to start running control algorithms each day.	False	00:00:00
end	string	Time to stop running control algorithms each day.	False	23:59:59

CapacitorStateChangeCountReport

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False

FeederLossesReport

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False

PvClippingReport

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False
diff_tolerance_percent_pmpp	number	TBD	False	1.0
denominator_tolerance_percent_pmpp	number	TBD	False	1.0

PvCurtailmentReport

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False
diff_tolerance_percent_pmpp	number	TBD	False	1.0
denominator_tolerance_percent_pmpp	number	TBD	False	1.0

RegControlTapNumberChangeCountsReport

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False

ThermalMetricsReport

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False
transformer_window_size_hours	integer	Transformer window size hours	False	2
transformer_loading_percent_threshold	integer	Transformer loading percent threshold	False	150
transformer_loading_percent_moving_average_threshold	integer	Transformer loading percent moving average threshold	False	120
line_window_size_hours	integer	Line window size hours	False	1
line_loading_percent_threshold	integer	Line loading percent threshold	False	120
line_loading_percent_moving_average_threshold	integer	Line loading percent moving average threshold	False	100
store_per_element_data	boolean	Set to true to store metrics for each line and transformer.	False	True

VoltageMetricsReport

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False
window_size_minutes	integer	Window size minutes	False	60
range_a_limits	array	ANSI Range A voltage limits	False	[0.95, 1.05]
range_b_limits	array	ANSI Range B voltage limits	False	[0.9, 1.0583]
store_per_element_data	boolean	Set to true to store metrics for each node.	False	True

ReportBase

Property	Type	Description	Required	Default
enabled	boolean	Set to true to enable the report	False	False
scenarios	array	Scenarios to which the report applies. Default is all scenarios.	False	[]
store_all_time_points	boolean	Set to true to store data for all time points. If false, store aggregated metrics in memory.	False	False

• Default Simulation Settings