Upgrade Cost Analysis JSON Schemas¶
UpgradeCostAnalysisSimulationModel¶
{
"title": "UpgradeCostAnalysisSimulationModel",
"description": "Defines the jobs in an upgrade cost analysis simulation.",
"type": "object",
"properties": {
"thermal_upgrade_params": {
"title": "Thermal Upgrade Params",
"default": {
"transformer_upper_limit": 1.25,
"line_upper_limit": 1.25,
"line_design_pu": 0.75,
"transformer_design_pu": 0.75,
"voltage_upper_limit": 1.05,
"voltage_lower_limit": 0.95,
"read_external_catalog": false,
"external_catalog": "",
"create_plots": true,
"parallel_transformers_limit": 4,
"parallel_lines_limit": 4,
"upgrade_iteration_threshold": 5,
"timepoint_multipliers": null
},
"allOf": [
{
"$ref": "#/definitions/ThermalUpgradeParamsModel"
}
]
},
"voltage_upgrade_params": {
"title": "Voltage Upgrade Params",
"default": {
"initial_upper_limit": 1.05,
"initial_lower_limit": 0.95,
"final_upper_limit": 1.05,
"final_lower_limit": 0.95,
"nominal_voltage": 120.0,
"create_plots": true,
"capacitor_sweep_voltage_gap": 1.0,
"reg_control_bands": [
1,
2
],
"reg_v_delta": 0.5,
"max_regulators": 4,
"place_new_regulators": true,
"use_ltc_placement": true,
"timepoint_multipliers": null,
"capacitor_action_flag": true,
"existing_regulator_sweep_action": true,
"max_control_iterations": 50
},
"allOf": [
{
"$ref": "#/definitions/VoltageUpgradeParamsModel"
}
]
},
"upgrade_cost_database": {
"title": "upgrade_cost_database",
"description": "Database containing costs for each equipment type",
"type": "string"
},
"calculate_costs": {
"title": "calculate_costs",
"description": "If True, calculate upgrade costs from database.",
"default": true,
"type": "boolean"
},
"upgrade_order": {
"title": "Upgrade Order",
"description": "Order of upgrade algorithm. 'thermal' or 'voltage' can be removed from the simulation by excluding them from this parameter.",
"default": [
"thermal",
"voltage"
],
"type": "array",
"items": {
"type": "string"
}
},
"pydss_controllers": {
"title": "pydss_controllers",
"description": "If enable_pydss_controllers is True, these PyDSS controllers are applied to each corresponding element type.",
"default": {
"pv_controller": null
},
"allOf": [
{
"$ref": "#/definitions/PyDssControllerModels"
}
]
},
"plot_violations": {
"title": "plot_violations",
"description": "If True, create plots of violations before and after simulation.",
"default": true,
"type": "boolean"
},
"enable_pydss_controllers": {
"title": "enable_pydss_controllers",
"description": "Flag to enable/disable use of PyDSS controllers",
"default": false,
"type": "boolean"
},
"include_pf1": {
"title": "include_pf1",
"description": "Include PF1 scenario (no controls) if pydss_controllers are defined.",
"default": true,
"type": "boolean"
},
"dc_ac_ratio": {
"title": "dc_ac_ratio",
"description": "Apply DC-AC ratio for PV Systems",
"type": "number"
},
"jobs": {
"title": "Jobs",
"type": "array",
"items": {
"$ref": "#/definitions/UpgradeCostAnalysisGenericModel"
}
}
},
"required": [
"upgrade_cost_database",
"jobs"
],
"additionalProperties": false,
"definitions": {
"ThermalUpgradeParamsModel": {
"title": "UpgradeParamsBaseModel",
"description": "Thermal Upgrade Parameters for all jobs in a simulation",
"type": "object",
"properties": {
"transformer_upper_limit": {
"title": "transformer_upper_limit",
"description": "Transformer upper limit in per unit (example: 1.25)",
"type": "number"
},
"line_upper_limit": {
"title": "line_upper_limit",
"description": "Line upper limit in per unit (example: 1.25)",
"type": "number"
},
"line_design_pu": {
"title": "line_design_pu",
"description": "Line design in per unit (example: 0.75)",
"type": "number"
},
"transformer_design_pu": {
"title": "transformer_design_pu",
"description": "Transformer design in per unit (example: 0.75)",
"type": "number"
},
"voltage_upper_limit": {
"title": "voltage_upper_limit",
"description": "Voltage upper limit in per unit (example: 1.05)",
"type": "number"
},
"voltage_lower_limit": {
"title": "voltage_lower_limit",
"description": "Voltage lower limit in per unit (example: 0.95)",
"type": "number"
},
"read_external_catalog": {
"title": "read_external_catalog",
"description": "Flag to determine whether external catalog is to be used (example: False)",
"type": "boolean"
},
"external_catalog": {
"title": "external_catalog",
"description": "Location to external upgrades technical catalog json file",
"type": "string"
},
"create_plots": {
"title": "create_plots",
"description": "Flag to enable or disable figure creation",
"default": true,
"type": "boolean"
},
"parallel_transformers_limit": {
"title": "parallel_transformers_limit",
"description": "Parallel transformer limit",
"default": 4,
"type": "integer"
},
"parallel_lines_limit": {
"title": "parallel_lines_limit",
"description": "Parallel lines limit",
"default": 4,
"type": "integer"
},
"upgrade_iteration_threshold": {
"title": "upgrade_iteration_threshold",
"description": "Upgrade iteration threshold",
"default": 5,
"type": "integer"
},
"timepoint_multipliers": {
"title": "timepoint_multipliers",
"description": "Dictionary to provide timepoint multipliers. example: timepoint_multipliers={\"load_multipliers\": {\"with_pv\": [1.2], \"without_pv\": [0.6]}}",
"type": "object"
}
},
"required": [
"transformer_upper_limit",
"line_upper_limit",
"line_design_pu",
"transformer_design_pu",
"voltage_upper_limit",
"voltage_lower_limit",
"read_external_catalog",
"external_catalog"
],
"additionalProperties": false
},
"VoltageUpgradeParamsModel": {
"title": "UpgradeParamsBaseModel",
"description": "Voltage Upgrade Parameters for all jobs in a simulation",
"type": "object",
"properties": {
"initial_upper_limit": {
"title": "initial_upper_limit",
"description": "Initial upper limit in per unit (example: 1.05)",
"type": "number"
},
"initial_lower_limit": {
"title": "initial_lower_limit",
"description": "Initial lower limit in per unit (example: 0.95)",
"type": "number"
},
"final_upper_limit": {
"title": "final_upper_limit",
"description": "Final upper limit in per unit (example: 1.05)",
"type": "number"
},
"final_lower_limit": {
"title": "final_lower_limit",
"description": "Final lower limit in per unit (example: 0.95)",
"type": "number"
},
"nominal_voltage": {
"title": "nominal_voltage",
"description": "Nominal voltage (volts) (example: 120)",
"type": "number"
},
"create_plots": {
"title": "create_plots",
"description": "Flag to enable or disable figure creation",
"default": true,
"type": "boolean"
},
"capacitor_sweep_voltage_gap": {
"title": "capacitor_sweep_voltage_gap",
"description": "Capacitor sweep voltage gap (example: 1)",
"default": 1.0,
"type": "number"
},
"reg_control_bands": {
"title": "reg_control_bands",
"description": "Regulator control bands (example: [1, 2])",
"default": [
1,
2
],
"type": "array",
"items": {
"type": "integer"
}
},
"reg_v_delta": {
"title": "reg_v_delta",
"description": "Regulator voltage delta (example: 0.5)",
"default": 0.5,
"type": "number"
},
"max_regulators": {
"title": "max_regulators",
"description": "Maximum number of regulators",
"default": 4,
"type": "integer"
},
"place_new_regulators": {
"title": "place_new_regulators",
"description": "Flag to enable or disable new regulator placement",
"default": true,
"type": "boolean"
},
"use_ltc_placement": {
"title": "use_ltc_placement",
"description": "Flag to enable or disable substation LTC upgrades module",
"default": true,
"type": "boolean"
},
"timepoint_multipliers": {
"title": "timepoint_multipliers",
"description": "Dictionary to provide timepoint multipliers. example: timepoint_multipliers={\"load_multipliers\": {\"with_pv\": [1.2], \"without_pv\": [0.6]}}",
"type": "object"
},
"capacitor_action_flag": {
"title": "capacitor_action_flag",
"description": "Flag to enable or disable capacitor controls settings sweep module",
"default": true,
"type": "boolean"
},
"existing_regulator_sweep_action": {
"title": "existing_regulator_sweep_action",
"description": "Flag to enable or disable existing regulator controls settings sweep module",
"default": true,
"type": "boolean"
},
"max_control_iterations": {
"title": "max_control_iterations",
"description": "Max control iterations to be set for OpenDSS",
"default": 50,
"type": "integer"
}
},
"required": [
"initial_upper_limit",
"initial_lower_limit",
"final_upper_limit",
"final_lower_limit",
"nominal_voltage"
],
"additionalProperties": false
},
"PvControllerModel": {
"title": "ControllerBaseModel",
"type": "object",
"properties": {
"Control1": {
"title": "Control1",
"description": "TODO",
"type": "string"
},
"Control2": {
"title": "Control1",
"description": "TODO",
"type": "string"
},
"Control3": {
"title": "Control3",
"description": "TODO",
"type": "string"
},
"pf": {
"title": "pf",
"description": "TODO",
"type": "integer"
},
"pfMin": {
"title": "pfMin",
"description": "TODO",
"type": "number"
},
"pfMax": {
"title": "pfMax",
"description": "TODO",
"type": "number"
},
"Pmin": {
"title": "Pmin",
"description": "TODO",
"type": "number"
},
"Pmax": {
"title": "Pmax",
"description": "TODO",
"type": "number"
},
"uMin": {
"title": "uMin",
"description": "TODO",
"type": "number"
},
"uDbMin": {
"title": "uDbMin",
"description": "TODO",
"type": "number"
},
"uDbMax": {
"title": "uDbMax",
"description": "TODO",
"type": "number"
},
"uMax": {
"title": "uMax",
"description": "TODO",
"type": "number"
},
"QlimPU": {
"title": "QlimPU",
"description": "TODO",
"type": "number"
},
"PFlim": {
"title": "PFlim",
"description": "TODO",
"type": "number"
},
"Enable PF limit": {
"title": "EnablePFLimit",
"description": "TODO",
"type": "boolean"
},
"uMinC": {
"title": "uMinC",
"description": "TODO",
"type": "number"
},
"uMaxC": {
"title": "uMaxC",
"description": "TODO",
"type": "number"
},
"PminVW": {
"title": "PminVW",
"description": "TODO",
"type": "number"
},
"VWtype": {
"title": "VWtype",
"description": "TODO",
"type": "string"
},
"%PCutin": {
"title": "PCutin",
"description": "TODO",
"type": "number"
},
"%PCutout": {
"title": "%PCutout",
"description": "TODO",
"type": "number"
},
"Efficiency": {
"title": "Efficiency",
"description": "TODO",
"type": "number"
},
"Priority": {
"title": "Priority",
"description": "TODO",
"type": "string"
},
"DampCoef": {
"title": "DampCoef",
"description": "TODO",
"type": "number"
}
},
"required": [
"Control1",
"pf",
"pfMin",
"pfMax",
"Pmin",
"Pmax",
"uMin",
"uDbMin",
"uDbMax",
"uMax",
"QlimPU",
"PFlim",
"Enable PF limit",
"uMinC",
"uMaxC",
"PminVW",
"VWtype",
"%PCutin",
"%PCutout",
"Efficiency",
"Priority",
"DampCoef"
],
"additionalProperties": false
},
"PyDssControllerModels": {
"title": "UpgradeParamsBaseModel",
"description": "Defines the settings for PyDSS controllers",
"type": "object",
"properties": {
"pv_controller": {
"title": "pv_controller",
"description": "Settings for a PV controller",
"allOf": [
{
"$ref": "#/definitions/PvControllerModel"
}
]
}
},
"additionalProperties": false
},
"UpgradeCostAnalysisGenericModel": {
"title": "UpgradeCostAnalysisGenericModel",
"description": "Parameters for each job in a simulation",
"type": "object",
"properties": {
"model_type": {
"title": "model_type",
"description": "Model type",
"default": "UpgradeCostAnalysisGenericModel",
"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"
}
},
"required": [
"name",
"opendss_model_file"
]
}
}
}
UpgradesCostResultSummaryModel¶
{
"title": "UpgradeParamsBaseModel",
"description": "Contains individual equipment output",
"type": "object",
"properties": {
"name": {
"title": "name",
"description": "Job name",
"type": "string"
},
"equipment_type": {
"title": "equipment_type",
"description": "Type of equipment",
"type": "string"
},
"equipment_name": {
"title": "equipment_name",
"description": "Name of equipment",
"type": "string"
},
"status": {
"title": "status",
"description": "Status",
"type": "string"
},
"total_cost_usd": {
"title": "total_cost_usd",
"description": "Total cost in US dollars",
"type": "number"
},
"parameter1_name": {
"title": "parameter1_name",
"description": "Name of parameter1",
"type": "string"
},
"parameter1_original": {
"title": "parameter1_original",
"description": "Original value of parameter1"
},
"parameter1_upgraded": {
"title": "parameter1_upgraded",
"description": "Upgraded value of parameter1"
},
"parameter2_name": {
"title": "parameter2_name",
"description": "Name of parameter2",
"default": "",
"type": "string"
},
"parameter2_original": {
"title": "parameter2_original",
"description": "Original value of parameter2"
},
"parameter2_upgraded": {
"title": "parameter2_upgraded",
"description": "Upgraded value of parameter2"
},
"parameter3_name": {
"title": "parameter3_name",
"description": "Name of parameter3",
"default": "",
"type": "string"
},
"parameter3_original": {
"title": "parameter3_original",
"description": "Original value of parameter3"
},
"parameter3_upgraded": {
"title": "parameter3_upgraded",
"description": "Upgraded value of parameter3"
}
},
"required": [
"name",
"equipment_type",
"equipment_name",
"status",
"total_cost_usd",
"parameter1_name"
],
"additionalProperties": false
}
JobUpgradeSummaryOutputModel¶
{
"title": "UpgradeParamsBaseModel",
"description": "Contains results from all jobs in the simulation.",
"type": "object",
"properties": {
"results": {
"title": "results",
"description": "Results summary for each job",
"type": "array",
"items": {}
},
"outputs": {
"title": "outputs",
"description": "Outputs for each job in the simulation.",
"allOf": [
{
"$ref": "#/definitions/UpgradeSimulationOutputModel"
}
]
},
"violation_summary": {
"title": "upgrade_summary",
"description": "Contains thermal or voltage upgrade results for each job",
"type": "array",
"items": {
"$ref": "#/definitions/UpgradeViolationResultModel"
}
},
"costs_per_equipment": {
"title": "costs_per_equipment",
"description": "Contains upgrade cost information for each job by equipment type",
"type": "array",
"items": {
"$ref": "#/definitions/TotalUpgradeCostsResultModel"
}
},
"equipment": {
"title": "equipment",
"description": "Contains equipment information for each job",
"type": "array",
"items": {}
}
},
"required": [
"results",
"outputs",
"violation_summary",
"costs_per_equipment",
"equipment"
],
"additionalProperties": false,
"definitions": {
"UpgradeJobOutputModel": {
"title": "UpgradeParamsBaseModel",
"description": "Contains outputs from one job.",
"type": "object",
"properties": {
"upgraded_opendss_model_file": {
"title": "upgraded_opendss_model_file",
"description": "Path to file that will load the upgraded network.",
"type": "string"
},
"feeder_stats": {
"title": "feeder_stats",
"description": "Path to file containing feeder metadata and equipment details before and after upgrades.",
"type": "string"
},
"return_code": {
"title": "return_code",
"description": "Return code from process. Zero is success, non-zero is a failure.",
"type": "integer"
}
},
"required": [
"upgraded_opendss_model_file",
"feeder_stats",
"return_code"
],
"additionalProperties": false
},
"UpgradeSimulationOutputModel": {
"title": "UpgradeParamsBaseModel",
"description": "Contains outputs from all jobs in the simulation.",
"type": "object",
"properties": {
"log_file": {
"title": "log_file",
"description": "Path to log file for the simulation.",
"type": "string"
},
"jobs": {
"title": "jobs",
"description": "Outputs for each job in the simulation.",
"type": "array",
"items": {
"$ref": "#/definitions/UpgradeJobOutputModel"
}
}
},
"required": [
"log_file",
"jobs"
],
"additionalProperties": false
},
"UpgradeViolationResultModel": {
"title": "UpgradeParamsBaseModel",
"description": "Defines result parameters for thermal upgrades.",
"type": "object",
"properties": {
"name": {
"title": "name",
"description": "Job name",
"type": "string"
},
"scenario": {
"title": "scenario",
"description": "Simulation scenario describing the controls being used",
"default": "control_mode",
"type": "string"
},
"stage": {
"title": "stage",
"description": "Stage of upgrades: initial (before upgrades) or final (after upgrades)",
"type": "string"
},
"upgrade_type": {
"title": "upgrade_type",
"description": "Type of upgrade: thermal or voltage",
"type": "string"
},
"simulation_time_s": {
"title": "simulation_time_s",
"description": "Simulation time to perform upgrades (seconds)",
"type": "number"
},
"thermal_violations_present": {
"title": "thermal_violations_present",
"description": "Flag indicating whether thermal violations are present",
"type": "boolean"
},
"voltage_violations_present": {
"title": "voltage_violations_present",
"description": "Flag indicating whether voltage violations are present",
"type": "boolean"
},
"max_bus_voltage": {
"title": "max_bus_voltage",
"description": "Maximum voltage recorded on any bus",
"units": "pu",
"type": "number"
},
"min_bus_voltage": {
"title": "min_bus_voltage",
"description": "Minimum voltage recorded on any bus",
"units": "pu",
"type": "number"
},
"num_voltage_violation_buses": {
"title": "num_voltage_violation_buses",
"description": "Number of buses with voltage violations",
"type": "integer"
},
"num_overvoltage_violation_buses": {
"title": "num_overvoltage_violation_buses",
"description": "Number of buses with voltage above voltage_upper_limit",
"type": "integer"
},
"voltage_upper_limit": {
"title": "voltage_upper_limit",
"description": "Voltage upper limit, the threshold considered for determining overvoltages",
"units": "pu",
"type": "number"
},
"num_undervoltage_violation_buses": {
"title": "num_undervoltage_violation_buses",
"description": "Number of buses with voltage below voltage_lower_limit",
"type": "integer"
},
"voltage_lower_limit": {
"title": "voltage_lower_limit",
"description": "Voltage lower limit, the threshold considered for determining undervoltages",
"units": "pu",
"type": "number"
},
"max_line_loading": {
"title": "max_line_loading",
"description": "Maximum line loading",
"units": "pu",
"type": "number"
},
"max_transformer_loading": {
"title": "max_transformer_loading",
"description": "Maximum transformer loading",
"units": "pu",
"type": "number"
},
"num_line_violations": {
"title": "num_line_violations",
"description": "Number of lines with loading above line upper limit",
"type": "integer"
},
"line_upper_limit": {
"title": "line_upper_limit",
"description": "Line upper limit, the threshold considered for determining line overloading",
"units": "pu",
"type": "number"
},
"num_transformer_violations": {
"title": "num_transformer_violations",
"description": "Number of transformers with loading above transformer upper limit",
"type": "integer"
},
"transformer_upper_limit": {
"title": "transformer_upper_limit",
"description": "Transformer upper limit, the threshold considered for determining transformer overloading",
"units": "pu",
"type": "number"
}
},
"required": [
"name",
"stage",
"upgrade_type",
"simulation_time_s",
"thermal_violations_present",
"voltage_violations_present",
"max_bus_voltage",
"min_bus_voltage",
"num_voltage_violation_buses",
"num_overvoltage_violation_buses",
"voltage_upper_limit",
"num_undervoltage_violation_buses",
"voltage_lower_limit",
"max_line_loading",
"max_transformer_loading",
"num_line_violations",
"line_upper_limit",
"num_transformer_violations",
"transformer_upper_limit"
],
"additionalProperties": false
},
"TotalUpgradeCostsResultModel": {
"title": "UpgradeParamsBaseModel",
"description": "Provides total output costs for upgrading a type of equipment.",
"type": "object",
"properties": {
"name": {
"title": "name",
"description": "Job name",
"type": "string"
},
"type": {
"title": "type",
"description": "Equipment type",
"type": "string"
},
"count": {
"title": "count",
"description": "Count of upgraded equipment",
"type": "integer"
},
"total_cost_usd": {
"title": "total_cost_usd",
"description": "Total cost in US dollars",
"units": "dollars",
"type": "number"
}
},
"required": [
"name",
"type",
"count",
"total_cost_usd"
],
"additionalProperties": false
}
}
}