Data Sources¶
DISCO currently supports OpenDSS models stored in several source formats, namely Generic Models, SourceTree1, SourceTree2, GEM, EPRI.
The following sections show how to prepare the source feeder models which are used as input paths for transforming models with a given analysis type.
Generic Power Flow Models¶
You can use this format to run power-flow simulations on your own OpenDSS models. Unlike simulations run in the other formats, DISCO will not make any dynamic changes to the models (as it does for DC-AC ratio for PVSystems).
Refer to these input JSON files as examples:
This test file demonstrates the workflow.
Note
If you enable external controls for PVSystems through PyDSS then the file specified as
opendss_model_file must contain the PVSystem definitions.
The inputs must conform to the JSON schemas below.
PowerFlowSnapshotSimulationModel¶
{
"title": "PowerFlowSimulationBaseModel",
"description": "Defines a snapshot power-flow simulation.",
"type": "object",
"properties": {
"jobs": {
"title": "jobs",
"description": "Jobs to run as part of the simulation.",
"type": "array",
"items": {
"$ref": "#/definitions/PowerFlowGenericModel"
}
},
"include_control_mode": {
"title": "include_control_mode",
"description": "Include a control mode (such as volt-var controls) scenario for each job.",
"default": true,
"type": "boolean"
},
"include_pf1": {
"title": "include_pf1",
"description": "Include a Power Factor 1 scenario for each job.",
"default": true,
"type": "boolean"
},
"model_type": {
"title": "Model Type",
"default": "PowerFlowSnapshotSimulationModel",
"type": "string"
},
"start_time": {
"title": "start_time",
"description": "Start time of simulation. May be overridden by auto-time-point-selection.",
"default": "2020-04-15 14:00:00",
"type": "string",
"format": "date-time"
}
},
"required": [
"jobs"
],
"additionalProperties": false,
"definitions": {
"ControllerType": {
"title": "ControllerType",
"description": "An enumeration.",
"enum": [
"FaultController",
"GenController",
"MotorStall",
"MotorStallSimple",
"PvController",
"PvDynamic",
"PvFrequencyRideThru",
"PvVoltageRideThru",
"SocketController",
"StorageController",
"ThermostaticLoad",
"xmfrController"
]
},
"PyDSSControllerModel": {
"title": "PyDSSControllerModel",
"description": "PV Controller on deployment",
"type": "object",
"properties": {
"controller_type": {
"title": "controller_type",
"description": "The controller type defined in PyDSS.",
"example_value": "PvController",
"allOf": [
{
"$ref": "#/definitions/ControllerType"
}
]
},
"name": {
"title": "name",
"description": "The name of the controller",
"maxLength": 120,
"example_value": "ctrl-name",
"type": "string"
},
"targets": {
"title": "targets",
"description": "The PV system files that need to apply controller.",
"anyOf": [
{
"type": "string",
"format": "file-path"
},
{
"type": "array",
"items": {
"type": "string",
"format": "file-path"
}
}
]
}
},
"required": [
"controller_type",
"name"
]
},
"PowerFlowGenericModel": {
"title": "PowerFlowGenericModel",
"description": "Parameters for each job in a power-flow simulation",
"type": "object",
"properties": {
"model_type": {
"title": "model_type",
"description": "Model type",
"default": "PowerFlowGenericModel",
"type": "string"
},
"name": {
"title": "name",
"description": "Unique name identifying the job",
"type": "string"
},
"blocked_by": {
"title": "blocked_by",
"description": "Names of jobs that must finish before this job starts",
"default": [],
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"job_order": {
"title": "job_order",
"description": "The execution order of the simulation job.",
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "number",
"minimum": 0.0
}
]
},
"opendss_model_file": {
"title": "opendss_model_file",
"description": "Path to file used load the simulation model files",
"type": "string"
},
"estimated_run_minutes": {
"title": "estimated_run_minutes",
"description": "Optionally advises the job execution manager on how long the job will run",
"type": "integer"
},
"substation": {
"title": "substation",
"description": "Substation for the job",
"type": "string"
},
"feeder": {
"title": "feeder",
"description": "Feeder for the job",
"type": "string"
},
"pydss_controllers": {
"title": "pydss_controllers",
"description": "Apply these PyDSS controllers to each corresponding element type. If empty, use pf1.",
"default": [],
"type": "array",
"items": {
"$ref": "#/definitions/PyDSSControllerModel"
}
},
"project_data": {
"title": "project_data",
"description": "Optional user-defined metadata for the job",
"type": "object"
}
},
"required": [
"name",
"opendss_model_file",
"project_data"
]
}
}
}
PowerFlowTimeSeriesSimulationModel¶
{
"title": "PowerFlowSimulationBaseModel",
"description": "Defines a time-series power-flow simulation.",
"type": "object",
"properties": {
"jobs": {
"title": "jobs",
"description": "Jobs to run as part of the simulation.",
"type": "array",
"items": {
"$ref": "#/definitions/PowerFlowGenericModel"
}
},
"include_control_mode": {
"title": "include_control_mode",
"description": "Include a control mode (such as volt-var controls) scenario for each job.",
"default": true,
"type": "boolean"
},
"include_pf1": {
"title": "include_pf1",
"description": "Include a Power Factor 1 scenario for each job.",
"default": true,
"type": "boolean"
},
"model_type": {
"title": "Model Type",
"default": "PowerFlowTimeSeriesSimulationModel",
"type": "string"
},
"start_time": {
"title": "start_time",
"description": "Start time of simulation.",
"default": "2020-01-01 00:00:00",
"type": "string",
"format": "date-time"
},
"end_time": {
"title": "end_time",
"description": "End time of simulation.",
"default": "2020-12-31 23:45:00",
"type": "string",
"format": "date-time"
},
"step_resolution": {
"title": "step_resolution",
"description": "Step resolution of simulation in seconds.",
"default": 900,
"type": "integer"
}
},
"required": [
"jobs"
],
"additionalProperties": false,
"definitions": {
"ControllerType": {
"title": "ControllerType",
"description": "An enumeration.",
"enum": [
"FaultController",
"GenController",
"MotorStall",
"MotorStallSimple",
"PvController",
"PvDynamic",
"PvFrequencyRideThru",
"PvVoltageRideThru",
"SocketController",
"StorageController",
"ThermostaticLoad",
"xmfrController"
]
},
"PyDSSControllerModel": {
"title": "PyDSSControllerModel",
"description": "PV Controller on deployment",
"type": "object",
"properties": {
"controller_type": {
"title": "controller_type",
"description": "The controller type defined in PyDSS.",
"example_value": "PvController",
"allOf": [
{
"$ref": "#/definitions/ControllerType"
}
]
},
"name": {
"title": "name",
"description": "The name of the controller",
"maxLength": 120,
"example_value": "ctrl-name",
"type": "string"
},
"targets": {
"title": "targets",
"description": "The PV system files that need to apply controller.",
"anyOf": [
{
"type": "string",
"format": "file-path"
},
{
"type": "array",
"items": {
"type": "string",
"format": "file-path"
}
}
]
}
},
"required": [
"controller_type",
"name"
]
},
"PowerFlowGenericModel": {
"title": "PowerFlowGenericModel",
"description": "Parameters for each job in a power-flow simulation",
"type": "object",
"properties": {
"model_type": {
"title": "model_type",
"description": "Model type",
"default": "PowerFlowGenericModel",
"type": "string"
},
"name": {
"title": "name",
"description": "Unique name identifying the job",
"type": "string"
},
"blocked_by": {
"title": "blocked_by",
"description": "Names of jobs that must finish before this job starts",
"default": [],
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"job_order": {
"title": "job_order",
"description": "The execution order of the simulation job.",
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "number",
"minimum": 0.0
}
]
},
"opendss_model_file": {
"title": "opendss_model_file",
"description": "Path to file used load the simulation model files",
"type": "string"
},
"estimated_run_minutes": {
"title": "estimated_run_minutes",
"description": "Optionally advises the job execution manager on how long the job will run",
"type": "integer"
},
"substation": {
"title": "substation",
"description": "Substation for the job",
"type": "string"
},
"feeder": {
"title": "feeder",
"description": "Feeder for the job",
"type": "string"
},
"pydss_controllers": {
"title": "pydss_controllers",
"description": "Apply these PyDSS controllers to each corresponding element type. If empty, use pf1.",
"default": [],
"type": "array",
"items": {
"$ref": "#/definitions/PyDSSControllerModel"
}
},
"project_data": {
"title": "project_data",
"description": "Optional user-defined metadata for the job",
"type": "object"
}
},
"required": [
"name",
"opendss_model_file",
"project_data"
]
}
}
}
SourceTree1 Model¶
This format requires the following directory structure:
source_model_directory
├── format.toml
├── <substation>
│ ├── *.dss
│ └── <substation>--<feeder>
│ ├── *.dss
│ └── hc_pv_deployments
│ ├── feeder_summary.csv
│ └── <placement>
│ ├── <sample>
│ │ ├── <penetration-level>
│ │ │ └── PVSystems.dss
│ │ │ └── PVSystems.dss
│ │ └── pv_config.json
└── profiles
└── <profile>.csv
Where in format.toml, it defines type = "SourceTree1Model".
To see how to generate the PV deployments data in hc_pv_deployments directory, please
refer to SourceTree1 PV Deployments.
The SMART-DS dataset is an open-source dataset which is in the SourceTree1 format. This dataset is prepared for performing DISCO hosting capacity analysis after some pre-processing which is described in the link below:
SourceTree2 Model¶
This format requires the following directory structure:
source_model_directory
├── inputs
│ ├── <feeder>
│ │ ├── LoadShapes
│ │ │ ├── <profile>.csv
│ │ ├── OpenDSS
│ │ │ ├── *.dss
│ │ ├── PVDeployments
│ │ │ └── new
│ │ │ ├── <dc-ac-ratio>
│ │ │ │ ├── <scale>
│ │ │ │ │ ├── <placement>
│ │ │ │ │ │ ├── <sample>
│ │ │ │ │ │ │ ├── PV_Gen_<sample>_<penetration-level>.txt
├── format.toml
Where in format.toml, it defines type = "SourceTree2Model".
GEM Model¶
A GEM config file (JSON) contains paths to source models on a filesystem along with descriptor schema that describe all feeders and their possible deployments.
Here is an example JSON file:
{
"include_voltage_deviation": false,
"path_base": "gem/feeder_models",
"type": "GemModel",
"feeders": [
{
"base_case": "deployment0",
"deployments": [
{
"dc_ac_ratios": [],
"kva_to_kw_ratings": [],
"loadshape_file": null,
"loadshape_location": null,
"name": "deployment0",
"placement_type": null,
"project_data": {
"pydss_other_loads_dss_files": {
"2010-03-11_12-00-00-000": ["/data/path/loads1.dss"],
"2010-12-25_15-00-00-000": ["/data/path/loads2.dss"]
},
"pydss_other_pvs_dss_files": {
"2010-03-11_12-00-00-000": ["/data/path/pvs1.dss"],
"2010-12-25_15-00-00-000": ["/data/path/pvs2.dss"],
}
},
"pv_locations": [],
"sample": null,
"pydss_controllers": null,
"job_order": 0
}
],
"end_time": "2010-08-11_15:00:00.000",
"simulation_type": "Snapshot",
"load_multipliers": [
0.3,
1.0,
0.2,
0.9
],
"loadshape_location": null,
"name": "MyFeeder",
"opendss_location": "/opendss/location/path/",
"start_time": "2010-08-11_15:00:00.000",
"step_resolution": 900
},
]
}
Rules:
start_timeandend_timemust be set with timestamps.If
simulation_type == "Snapshot", thenstart_timeandend_timemust be the same.
dc_ac_ratios,kva_to_kw_ratingsmay be empty arrays to represent no-PV scenarios.
pydss_controllershas three attributes,
controller_type: One controller type defined in PyDSS, for example, “PvController”.
name: One controller name registered in PyDSS registry.
targets(optional): null, a DSS file, or a list of DSS files. If null, then DISCO automatically sets the deployment file.
EPRI Model¶
The source URL of EPRI J1, K1, and M1 feeder models is https://dpv.epri.com/feeder_models.html. You can download the source data with this command:
$ disco download-source epri J1 K1 M1 --directory ./epri-feeders