study_submit
Purpose and availability
Queue an isolated study and return its durable job ID immediately. Use study_status and study_evidence; no engineering approval.
Before invocation
Inspect the current definition and exact version/project binding before invoking. Required fields, enums, bounds and consent fields below are authoritative. Omit no required input and do not invent unavailable values.
Exact input schema
{
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "short-circuit"
}
}
},
"then": {
"required": [
"fault"
]
}
},
{
"if": {
"properties": {
"kind": {
"const": "corrective-ac"
}
}
},
"then": {
"required": [
"profile",
"source_profile",
"outages",
"dispatch"
]
}
}
],
"properties": {
"branch_monitors": {
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 64,
"type": "array",
"uniqueItems": true
},
"bus_monitors": {
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 64,
"type": "array",
"uniqueItems": true
},
"compare_opendss": {
"description": "Run the isolated pinned OpenDSS cross-check for supported 3ph/1ph max/min line-only external-equivalent networks and ideal switch states. Transformers/shunts return not-comparable. Agreement is not physical qualification.",
"type": "boolean"
},
"controls": {
"items": {
"additionalProperties": false,
"properties": {
"axis": {
"enum": [
"P",
"Q"
]
},
"load_id": {
"minLength": 1,
"type": "string"
},
"step": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"load_id",
"axis",
"step"
],
"type": "object"
},
"maxItems": 16,
"minItems": 1,
"type": "array"
},
"direction_mw": {
"exclusiveMinimum": 0,
"maximum": 1000000,
"type": "number"
},
"dispatch": {
"items": {
"additionalProperties": false,
"properties": {
"generator_id": {
"minLength": 1,
"type": "string"
},
"max_down_mw": {
"maximum": 2000,
"minimum": 0,
"type": "number"
},
"max_up_mw": {
"maximum": 2000,
"minimum": 0,
"type": "number"
}
},
"required": [
"generator_id",
"max_up_mw",
"max_down_mw"
],
"type": "object"
},
"maxItems": 128,
"minItems": 1,
"type": "array"
},
"expected_artifact": {
"pattern": "^[a-f0-9]{64}$",
"type": "string"
},
"fault": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"case": {
"const": "max"
}
},
"required": [
"case"
]
},
"then": {
"properties": {
"sources": {
"items": {
"required": [
"s_sc_mva",
"rx"
]
}
}
}
}
},
{
"if": {
"properties": {
"case": {
"const": "min"
}
},
"required": [
"case"
]
},
"then": {
"properties": {
"sources": {
"items": {
"required": [
"s_sc_min_mva",
"rx_min"
]
}
}
},
"required": [
"line_data"
]
}
},
{
"if": {
"properties": {
"case": {
"const": "max"
}
},
"required": [
"case"
]
},
"then": {
"properties": {
"line_data": {
"maxProperties": 0
}
}
}
},
{
"if": {
"properties": {
"case": {
"const": "max"
},
"fault": {
"const": "1ph"
}
},
"required": [
"fault",
"case"
]
},
"then": {
"properties": {
"sources": {
"items": {
"required": [
"x0x",
"r0x0"
]
}
}
}
}
},
{
"if": {
"properties": {
"case": {
"const": "min"
},
"fault": {
"const": "1ph"
}
},
"required": [
"fault",
"case"
]
},
"then": {
"properties": {
"sources": {
"items": {
"required": [
"x0x_min",
"r0x0_min"
]
}
}
}
}
},
{
"if": {
"properties": {
"fault": {
"const": "3ph"
}
},
"required": [
"fault"
]
},
"then": {
"properties": {
"transformer2w_data": {
"maxProperties": 0
},
"zero_sequence": {
"maxProperties": 0
}
}
}
}
],
"description": "IEC 60909 input. Use native source IDs and bus IDs from project_inspect. Maximum cases require each source's s_sc_mva and rx; minimum cases require s_sc_min_mva and rx_min. 1ph transformer cases require exact source-backed transformer2w_data; no winding/grounding information is inferred.",
"properties": {
"buses": {
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 96,
"minItems": 1,
"type": "array",
"uniqueItems": true
},
"case": {
"enum": [
"max",
"min"
],
"type": "string"
},
"fault": {
"enum": [
"3ph",
"1ph"
],
"type": "string"
},
"line_data": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"endtemp_degree": {
"maximum": 250,
"minimum": 20,
"type": "number"
},
"r20_pu": {
"minimum": 0,
"type": "number"
},
"reference": {
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
"required": [
"r20_pu",
"endtemp_degree",
"reference"
],
"type": "object"
},
"description": "For minimum cases, include R20, end temperature and source reference for every active line.",
"type": "object"
},
"ratings": {
"description": "Optional declared assembly or bounded radial breaker current-duty ratings. No TRV or installed-equipment qualification is implied.",
"items": {
"additionalProperties": false,
"properties": {
"applied_voltage_kv": {
"exclusiveMinimum": 0,
"type": "number"
},
"bus": {
"minLength": 1,
"type": "string"
},
"class": {
"enum": [
"busbar-switchgear-assembly",
"circuit-breaker"
]
},
"contact_separation_s": {
"exclusiveMinimum": 0,
"type": "number"
},
"dc_component_limit_percent_at_separation": {
"exclusiveMinimum": 0,
"maximum": 100,
"type": "number"
},
"duty_profile": {
"const": "far-from-generator-radial/1"
},
"equipment_id": {
"minLength": 1,
"type": "string"
},
"frequency_hz": {
"exclusiveMinimum": 0,
"type": "number"
},
"installed_bus_id": {
"minLength": 1,
"type": "string"
},
"interrupting_rating_ka": {
"exclusiveMinimum": 0,
"type": "number"
},
"interrupting_time_s": {
"exclusiveMinimum": 0,
"type": "number"
},
"line_id": {
"minLength": 1,
"type": "string"
},
"peak_making_rating_ka": {
"exclusiveMinimum": 0,
"type": "number"
},
"peak_withstand_ka": {
"exclusiveMinimum": 0,
"type": "number"
},
"rated_voltage_kv": {
"exclusiveMinimum": 0,
"type": "number"
},
"reference": {
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"short_time_duration_s": {
"exclusiveMinimum": 0,
"type": "number"
},
"short_time_withstand_ka": {
"exclusiveMinimum": 0,
"type": "number"
},
"source_regime_reference": {
"minLength": 1,
"type": "string"
},
"terminal": {
"enum": [
"from",
"to"
]
},
"voltage_kv": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"bus",
"class",
"reference"
],
"type": "object"
},
"maxItems": 96,
"type": "array"
},
"sources": {
"items": {
"additionalProperties": false,
"properties": {
"bus": {
"minLength": 1,
"type": "string"
},
"r0x0": {
"minimum": 0,
"type": "number"
},
"r0x0_min": {
"minimum": 0,
"type": "number"
},
"reference": {
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"rx": {
"minimum": 0,
"type": "number"
},
"rx_min": {
"minimum": 0,
"type": "number"
},
"s_sc_min_mva": {
"exclusiveMinimum": 0,
"type": "number"
},
"s_sc_mva": {
"exclusiveMinimum": 0,
"type": "number"
},
"source_id": {
"minLength": 1,
"type": "string"
},
"x0x": {
"exclusiveMinimum": 0,
"type": "number"
},
"x0x_min": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"source_id",
"bus",
"reference"
],
"type": "object"
},
"maxItems": 384,
"minItems": 1,
"type": "array"
},
"tk_seconds": {
"exclusiveMinimum": 0,
"maximum": 10,
"type": "number"
},
"transformer2w_data": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"mag0_percent": {
"minimum": 0,
"type": "number"
},
"mag0_rx": {
"minimum": 0,
"type": "number"
},
"reference": {
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"si0_hv_partial": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"vector_group": {
"enum": [
"Yy",
"Yyn",
"Yd",
"YNy",
"YNyn",
"YNd",
"Dy",
"Dyn",
"Dd"
],
"type": "string"
},
"vk0_percent": {
"minimum": 0,
"type": "number"
},
"vkr0_percent": {
"minimum": 0,
"type": "number"
},
"xn_ohm": {
"minimum": 0,
"type": "number"
}
},
"required": [
"vector_group",
"vk0_percent",
"vkr0_percent",
"mag0_percent",
"mag0_rx",
"si0_hv_partial",
"xn_ohm",
"reference"
],
"type": "object"
},
"description": "For 1ph transformer faults, source-backed pandapower 3.5.5 vector-group and zero-sequence data keyed by native transformer ID.",
"type": "object"
},
"transformer3w_data": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"reference": {
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"shift_lv_degree": {
"type": "number"
},
"shift_mv_degree": {
"type": "number"
},
"vector_group": {
"enum": [
"ddd",
"ddy",
"dyd",
"dyy",
"ydd",
"ydy",
"yyd",
"yyy",
"ynyd",
"yndy",
"yynd",
"ydyn",
"ynynd",
"yndyn",
"yndd",
"ynyy",
"dynyn"
],
"type": "string"
},
"vk0_hv_percent": {
"minimum": 0,
"type": "number"
},
"vk0_lv_percent": {
"minimum": 0,
"type": "number"
},
"vk0_mv_percent": {
"minimum": 0,
"type": "number"
},
"vkr0_hv_percent": {
"minimum": 0,
"type": "number"
},
"vkr0_lv_percent": {
"minimum": 0,
"type": "number"
},
"vkr0_mv_percent": {
"minimum": 0,
"type": "number"
}
},
"required": [
"shift_mv_degree",
"shift_lv_degree",
"reference"
],
"type": "object"
},
"description": "Every active 3-winding transformer requires source-bound phase shifts; 1ph faults additionally require an admitted vector group and all three winding zero-sequence impedances.",
"type": "object"
},
"zero_sequence": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"b0_pu": {
"type": "number"
},
"g0_pu": {
"minimum": 0,
"type": "number"
},
"r0_pu": {
"minimum": 0,
"type": "number"
},
"reference": {
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"x0_pu": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"r0_pu",
"x0_pu",
"reference"
],
"type": "object"
},
"description": "For 1ph faults, source-backed line R0/X0 in pu keyed by native line ID. Optional B0/G0 override native model shunt values; reference and all quantities are preserved in the study receipt.",
"type": "object"
}
},
"required": [
"fault",
"case",
"tk_seconds",
"buses",
"sources"
],
"type": "object"
},
"kind": {
"enum": [
"readiness",
"power-flow",
"exchange",
"scenarios",
"timeseries",
"outages",
"optimization",
"corrective-ac",
"short-circuit",
"loadability",
"pv-curve",
"sensitivity"
],
"type": "string"
},
"loads": {
"items": {
"type": "string"
},
"type": "array",
"uniqueItems": true
},
"max_extra_mw": {
"exclusiveMinimum": 0,
"maximum": 1000000,
"type": "number"
},
"max_points": {
"maximum": 128,
"minimum": 2,
"type": "integer"
},
"monitors": {
"items": {
"type": "string"
},
"maxItems": 64,
"type": "array",
"uniqueItems": true
},
"n1": {
"type": "boolean"
},
"outages": {
"items": {
"type": "string"
},
"type": "array"
},
"participation": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"weight": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"id",
"weight"
],
"type": "object"
},
"maxItems": 64,
"type": "array"
},
"profile": {
"const": "powersystem-corrective-ac/v1"
},
"protection": {
"additionalProperties": false,
"description": "Optional powersystem-protection/v1 radial feeder coordination; requires an exactly source-bound 3ph short-circuit input.",
"properties": {
"devices": {
"items": {
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "manufacturer-tcc"
}
}
},
"then": {
"required": [
"manufacturer_curve_id",
"device_model",
"settings_reference",
"rated_voltage_kv",
"ambient_c",
"preload_condition",
"breaker_delay_s"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "idmt-relay"
}
}
},
"then": {
"required": [
"ct_primary_a",
"ct_secondary_a",
"pickup_secondary_a",
"curve_type",
"time_multiplier",
"grading_seconds"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "fuse"
}
}
},
"then": {
"required": [
"curve",
"curve_selection",
"catalog_version",
"catalog_entry_sha256"
]
}
}
],
"properties": {
"ambient_c": {
"type": "number"
},
"breaker_delay_s": {
"minimum": 0,
"type": "number"
},
"catalog_entry_sha256": {
"pattern": "^[a-f0-9]{64}$",
"type": "string"
},
"catalog_version": {
"type": "string"
},
"ct_primary_a": {
"exclusiveMinimum": 0,
"type": "number"
},
"ct_secondary_a": {
"exclusiveMinimum": 0,
"type": "number"
},
"curve": {
"minLength": 1,
"type": "string"
},
"curve_selection": {
"enum": [
"average",
"minimum-melt",
"total-clear"
]
},
"curve_type": {
"enum": [
"standard_inverse",
"very_inverse",
"extremely_inverse",
"long_inverse"
]
},
"device_model": {
"minLength": 1,
"type": "string"
},
"grading_seconds": {
"minimum": 0,
"type": "number"
},
"id": {
"minLength": 1,
"type": "string"
},
"line_id": {
"minLength": 1,
"type": "string"
},
"manufacturer_curve_id": {
"pattern": "^[a-f0-9]{64}$",
"type": "string"
},
"pickup_secondary_a": {
"exclusiveMinimum": 0,
"type": "number"
},
"preload_condition": {
"minLength": 1,
"type": "string"
},
"rated_voltage_kv": {
"exclusiveMinimum": 0,
"type": "number"
},
"settings_reference": {
"minLength": 1,
"type": "string"
},
"source_reference": {
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"terminal": {
"enum": [
"from",
"to"
]
},
"time_multiplier": {
"exclusiveMinimum": 0,
"type": "number"
},
"type": {
"enum": [
"idmt-relay",
"fuse",
"manufacturer-tcc"
]
}
},
"required": [
"id",
"line_id",
"terminal",
"type",
"source_reference"
],
"type": "object"
},
"maxItems": 256,
"minItems": 1,
"type": "array"
},
"fault": {
"const": "3ph"
},
"minimum_grading_margin_s": {
"exclusiveMinimum": 0,
"type": "number"
},
"review_state": {
"const": "unreviewed"
},
"scenario_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"schema": {
"const": "powersystem-protection/v1"
},
"simulate_backup_failure": {
"description": "Requires simulate_primary_failure. Also assume the first backup failed to open, then open the next in-range device terminal and re-solve. Relay curve times are from fault inception; no physical or cumulative breaker timing is modeled.",
"type": "boolean"
},
"simulate_primary_failure": {
"description": "Optional isolated scenario: assume primary failed to open, then open the timed backup line terminal and re-solve. Ideal switching only; not physical breaker operation.",
"type": "boolean"
}
},
"required": [
"schema",
"review_state",
"fault",
"scenario_id",
"minimum_grading_margin_s",
"devices"
],
"type": "object"
},
"protection_definition_id": {
"pattern": "^[a-f0-9]{64}$",
"type": "string"
},
"reactive_mode": {
"enum": [
"constant-pf",
"q-fixed"
],
"type": "string"
},
"scenario": {
"type": "integer"
},
"scenarios": {
"items": {
"type": "integer"
},
"type": "array"
},
"solver_config": {
"additionalProperties": false,
"description": "Versioned solver-only interior for nonlinear AC-OPF Q search. It does not alter the frozen model or strict final Q-limit checks; omitted means zero margin.",
"properties": {
"q_search_margin_mvar": {
"description": "Optional optimizer search margin in MVAr; accepted result is still checked against original exact model limits.",
"maximum": 0.01,
"minimum": 0,
"type": "number"
},
"schema": {
"const": "powersystem-corrective-ac-solver-config/v1"
}
},
"required": [
"schema",
"q_search_margin_mvar"
],
"type": "object"
},
"source_profile": {
"additionalProperties": false,
"properties": {
"cost_currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"id": {
"maxLength": 128,
"minLength": 1,
"type": "string"
},
"license_or_applicability": {
"maxLength": 512,
"minLength": 1,
"type": "string"
},
"reference": {
"maxLength": 1024,
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"reference",
"license_or_applicability",
"cost_currency"
],
"type": "object"
},
"step_mw": {
"exclusiveMinimum": 0,
"type": "number"
},
"times": {
"items": {
"type": "integer"
},
"type": "array"
},
"tolerance_mw": {
"exclusiveMinimum": 0,
"type": "number"
}
},
"required": [
"kind"
],
"type": "object"
}Results, errors and safety
Inspect the structured result and retained IDs/artifacts. Errors, unsupported profiles, missing data and cancellation remain explicit. A successful call grants no human engineering approval. Do not retry inference automatically. See Workflows, History and Project tools.