tellegen.dev

{
  "type": "object",
  "properties": {
    "case_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "expected_case_revision": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "study": {
      "additionalProperties": false,
      "properties": {
        "decisions": {
          "anyOf": [
            {
              "$ref": "#/$defs/DecisionSpace"
            },
            {
              "type": "null"
            }
          ]
        },
        "display": {
          "anyOf": [
            {
              "$ref": "#/$defs/CreateDisplay"
            },
            {
              "type": "null"
            }
          ]
        },
        "formulation": {
          "enum": [
            "dcopf",
            "acpf",
            "socwr"
          ],
          "type": "string"
        },
        "interpretation": {
          "default": "",
          "type": "string"
        },
        "model_details": {
          "anyOf": [
            {
              "$ref": "#/$defs/ModelDetails"
            },
            {
              "type": "null"
            }
          ]
        },
        "objective": {
          "anyOf": [
            {
              "$ref": "#/$defs/StudyObjective"
            },
            {
              "type": "null"
            }
          ]
        },
        "request": {
          "default": "",
          "type": "string"
        },
        "solution": {
          "description": "A saved solution must belong to the supplied instance.",
          "type": [
            "string",
            "null"
          ]
        },
        "success_value": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "title": {
          "type": "string"
        },
        "view": {
          "anyOf": [
            {
              "$ref": "#/$defs/SolveResponse"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "title",
        "formulation"
      ],
      "type": "object"
    },
    "goal": {
      "additionalProperties": false,
      "properties": {
        "decisions": {
          "anyOf": [
            {
              "$ref": "#/$defs/DecisionSpace"
            },
            {
              "type": "null"
            }
          ]
        },
        "display": {
          "anyOf": [
            {
              "$ref": "#/$defs/CreateDisplay"
            },
            {
              "type": "null"
            }
          ]
        },
        "formulation": {
          "enum": [
            "dcopf",
            "acpf",
            "socwr"
          ],
          "type": "string"
        },
        "interpretation": {
          "default": "",
          "type": "string"
        },
        "model_details": {
          "anyOf": [
            {
              "$ref": "#/$defs/ModelDetails"
            },
            {
              "type": "null"
            }
          ]
        },
        "objective": {
          "anyOf": [
            {
              "$ref": "#/$defs/StudyObjective"
            },
            {
              "type": "null"
            }
          ]
        },
        "request": {
          "default": "",
          "type": "string"
        },
        "solution": {
          "description": "A saved solution must belong to the supplied instance.",
          "type": [
            "string",
            "null"
          ]
        },
        "success_value": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "title": {
          "type": "string"
        },
        "view": {
          "anyOf": [
            {
              "$ref": "#/$defs/SolveResponse"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "title",
        "formulation"
      ],
      "type": "object",
      "description": "Legacy alias for study."
    }
  },
  "required": [
    "case_id",
    "expected_case_revision"
  ],
  "additionalProperties": false,
  "oneOf": [
    {
      "required": [
        "study"
      ],
      "not": {
        "required": [
          "goal"
        ]
      }
    },
    {
      "required": [
        "goal"
      ],
      "not": {
        "required": [
          "study"
        ]
      }
    }
  ],
  "$defs": {
    "DecisionSpace": {
      "additionalProperties": false,
      "description": "The feasible set, distinct from both the inner problem and the outer goal.",
      "properties": {
        "demand": {
          "anyOf": [
            {
              "$ref": "#/$defs/DemandConstraint"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_changed_elements": {
          "format": "uint",
          "maximum": 65536,
          "minimum": 1,
          "type": "integer"
        },
        "total_budget": {
          "format": "double",
          "minimum": 0,
          "type": "number"
        },
        "variables": {
          "items": {
            "$ref": "#/$defs/DecisionVariable"
          },
          "maxItems": 65536,
          "minItems": 1,
          "type": "array"
        }
      },
      "required": [
        "variables",
        "total_budget",
        "max_changed_elements"
      ],
      "type": "object"
    },
    "DemandConstraint": {
      "oneOf": [
        {
          "additionalProperties": false,
          "description": "Allocate this additional MW across the declared demand decisions.",
          "properties": {
            "increase_mw": {
              "format": "double",
              "type": "number"
            },
            "kind": {
              "const": "placement",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "increase_mw"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Preserve the existing total MW across the declared demand decisions.",
          "properties": {
            "kind": {
              "const": "redistribution",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        }
      ]
    },
    "DecisionVariable": {
      "additionalProperties": false,
      "description": "Bounds and increments apply to changes from the goal's anchor state in a Study.",
      "properties": {
        "budget_weight": {
          "description": "Budget consumption per absolute unit of intervention.",
          "format": "double",
          "type": "number"
        },
        "element": {
          "$ref": "#/$defs/ElementKey"
        },
        "id": {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        "increment": {
          "format": "double",
          "type": "number"
        },
        "intervention": {
          "$ref": "#/$defs/Intervention"
        },
        "lower": {
          "format": "double",
          "type": "number"
        },
        "upper": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "id",
        "element",
        "intervention",
        "lower",
        "upper",
        "increment",
        "budget_weight"
      ],
      "type": "object"
    },
    "ElementKey": {
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "string"
        }
      ]
    },
    "Intervention": {
      "description": "A numerical intervention supported by the existing solvers.",
      "enum": [
        "branch_rating",
        "active_demand"
      ],
      "type": "string"
    },
    "CreateDisplay": {
      "additionalProperties": false,
      "properties": {
        "camera": {
          "anyOf": [
            {
              "$ref": "#/$defs/Camera"
            },
            {
              "type": "null"
            }
          ]
        },
        "case_id": {
          "type": "string"
        },
        "diagram_camera": {
          "anyOf": [
            {
              "$ref": "#/$defs/DiagramCamera"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "geo_layer": {
          "type": "string"
        },
        "layers": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "case_id",
        "geo_layer"
      ],
      "type": "object"
    },
    "Camera": {
      "additionalProperties": false,
      "properties": {
        "bearing": {
          "format": "double",
          "type": "number"
        },
        "center": {
          "items": {
            "format": "double",
            "type": "number"
          },
          "maxItems": 2,
          "minItems": 2,
          "type": "array"
        },
        "pitch": {
          "format": "double",
          "type": "number"
        },
        "zoom": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "center",
        "zoom",
        "bearing",
        "pitch"
      ],
      "type": "object"
    },
    "DiagramCamera": {
      "additionalProperties": false,
      "properties": {
        "center": {
          "items": {
            "format": "double",
            "type": "number"
          },
          "maxItems": 2,
          "minItems": 2,
          "type": "array"
        },
        "scale": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "center",
        "scale"
      ],
      "type": "object"
    },
    "ModelDetails": {
      "properties": {
        "approximations": {
          "items": {
            "$ref": "#/$defs/CostApproximation"
          },
          "type": "array"
        },
        "method": {
          "$ref": "#/$defs/CostPreparation"
        },
        "model": {
          "type": "string"
        },
        "quantity": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "units": {
          "type": "string"
        }
      },
      "required": [
        "method",
        "source",
        "model",
        "quantity",
        "units",
        "approximations"
      ],
      "type": "object"
    },
    "CostApproximation": {
      "properties": {
        "bus": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "generator": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "max_breakpoint_error": {
          "format": "double",
          "type": "number"
        },
        "model_cost": {
          "$ref": "#/$defs/GenCost"
        },
        "rms_breakpoint_error": {
          "format": "double",
          "type": "number"
        },
        "source_cost": {
          "$ref": "#/$defs/GenCost"
        }
      },
      "required": [
        "generator",
        "bus",
        "source_cost",
        "model_cost",
        "rms_breakpoint_error",
        "max_breakpoint_error"
      ],
      "type": "object"
    },
    "GenCost": {
      "description": "A generator cost curve (`mpc.gencost` row).",
      "properties": {
        "coeffs": {
          "description": "Raw coefficients, highest order first for the polynomial model:\n`[c_{k-1}, …, c1, c0]`.",
          "items": {
            "format": "double",
            "type": "number"
          },
          "type": "array"
        },
        "model": {
          "description": "1 = piecewise linear, 2 = polynomial.",
          "format": "uint8",
          "maximum": 255,
          "minimum": 0,
          "type": "integer"
        },
        "ncost": {
          "description": "Number of cost coefficients (polynomial) or breakpoints (piecewise).",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "shutdown": {
          "format": "double",
          "type": "number"
        },
        "startup": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "model",
        "startup",
        "shutdown",
        "ncost",
        "coeffs"
      ],
      "type": "object"
    },
    "CostPreparation": {
      "enum": [
        "exact",
        "convex_quadratic_fit"
      ],
      "type": "string"
    },
    "StudyObjective": {
      "description": "A scalar goal over the exact operating point and explicit interventions.",
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "weighted_observable",
              "type": "string"
            },
            "operand": {
              "$ref": "#/$defs/Operand"
            },
            "weights": {
              "items": {
                "$ref": "#/$defs/ObservableWeight"
              },
              "maxItems": 65536,
              "minItems": 1,
              "type": "array"
            }
          },
          "required": [
            "kind",
            "operand",
            "weights"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "sum",
              "type": "string"
            },
            "terms": {
              "items": {
                "$ref": "#/$defs/StudyObjective"
              },
              "maxItems": 65536,
              "minItems": 1,
              "type": "array"
            }
          },
          "required": [
            "kind",
            "terms"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "expression": {
              "$ref": "#/$defs/StudyObjective"
            },
            "factor": {
              "format": "double",
              "type": "number"
            },
            "kind": {
              "const": "scale",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "factor",
            "expression"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "expression": {
              "$ref": "#/$defs/StudyObjective"
            },
            "kind": {
              "const": "squared_target",
              "type": "string"
            },
            "target": {
              "format": "double",
              "type": "number"
            }
          },
          "required": [
            "kind",
            "target",
            "expression"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "decision": {
              "type": "string"
            },
            "kind": {
              "const": "intervention_penalty",
              "type": "string"
            },
            "linear": {
              "format": "double",
              "type": "number"
            },
            "quadratic": {
              "format": "double",
              "type": "number"
            }
          },
          "required": [
            "kind",
            "decision",
            "linear",
            "quadratic"
          ],
          "type": "object"
        }
      ]
    },
    "Operand": {
      "description": "What a sensitivity is taken *of*, named for the physical power quantity rather\nthan a formulation's internal variable. The orthogonal sub-axes (active/reactive,\nfrom/to, voltage representation) are visible to the type system; each formulation\nmaps a request to its own KKT rows or returns [`SensError::Unsupported`].\n\nThe dialects fold into one vocabulary: DC `Angle` is `Voltage(Angle)`, the conic\nsquared magnitude `w` is `Voltage(Squared)`, the nodal price is `Price(Active)`.",
      "oneOf": [
        {
          "additionalProperties": false,
          "description": "Nodal-balance dual (the LMP for active power, the reactive price for\nreactive), per bus.",
          "properties": {
            "Price": {
              "$ref": "#/$defs/Power"
            }
          },
          "required": [
            "Price"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Generator dispatch `pg` / `qg`, per generator.",
          "properties": {
            "Dispatch": {
              "$ref": "#/$defs/Power"
            }
          },
          "required": [
            "Dispatch"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Branch active/reactive flow at the from/to end, per branch.",
          "properties": {
            "Flow": {
              "properties": {
                "end": {
                  "$ref": "#/$defs/End"
                },
                "power": {
                  "$ref": "#/$defs/Power"
                }
              },
              "required": [
                "power",
                "end"
              ],
              "type": "object"
            }
          },
          "required": [
            "Flow"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Bus voltage in the formulation's representation (`vm` / `va` / `w` / `wr` /\n`wi`), per bus.",
          "properties": {
            "Voltage": {
              "$ref": "#/$defs/VoltageKind"
            }
          },
          "required": [
            "Voltage"
          ],
          "type": "object"
        }
      ]
    },
    "Power": {
      "description": "Active or reactive power. The orthogonal P/Q sub-axis shared by prices,\ndispatch, flows, and demand.",
      "enum": [
        "Active",
        "Reactive"
      ],
      "type": "string"
    },
    "End": {
      "description": "Which end of a branch a flow is measured at.",
      "enum": [
        "From",
        "To"
      ],
      "type": "string"
    },
    "VoltageKind": {
      "description": "How a voltage operand is represented: polar (`Magnitude`, `Angle`) for the AC\npower flow, or the W-space lift (`Squared` = `|V|²`, `ProductReal` = `Re(Vi Vj*)`,\n`ProductImag` = `Im(Vi Vj*)`) for the conic relaxation.",
      "enum": [
        "Magnitude",
        "Angle",
        "Squared",
        "ProductReal",
        "ProductImag"
      ],
      "type": "string"
    },
    "ObservableWeight": {
      "additionalProperties": false,
      "description": "A weighted observable in the units reported by the selected formulation.",
      "properties": {
        "element": {
          "$ref": "#/$defs/ElementKey"
        },
        "weight": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "element",
        "weight"
      ],
      "type": "object"
    },
    "SolveResponse": {
      "description": "The formulation-agnostic solve result. A superset: every block is optional, and\neach formulation fills what it produces. Powers are MW/MVAr, nodal values are\nin objective units per selected power unit, angles radians, `vm` per unit, and\n`w = |V|^2` per unit squared. Element ids\nare the original bus/branch/generator ids, so the frontend joins straight onto\nits case.",
      "properties": {
        "dispatch": {
          "items": {
            "$ref": "#/$defs/GenDispatch"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "flows": {
          "items": {
            "$ref": "#/$defs/BranchFlow"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "formulation": {
          "$ref": "#/$defs/Problem",
          "description": "The formulation that produced this, echoed for the client."
        },
        "injections": {
          "description": "Nodal injections (acpf), MW/MVAr.",
          "items": {
            "$ref": "#/$defs/BusInjection"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "iterations": {
          "anyOf": [
            {
              "$ref": "#/$defs/Iterations"
            },
            {
              "type": "null"
            }
          ]
        },
        "lmp": {
          "description": "Active nodal price when the solved OPF declares a network generator\ncost objective. Feasibility solves leave this absent.",
          "items": {
            "$ref": "#/$defs/BusScalar"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "lmp_q": {
          "description": "Reactive nodal price. Always `None` in this build; the field is retained for\nwire-format stability.",
          "items": {
            "$ref": "#/$defs/BusScalar"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "objective": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "sensitivities": {
          "description": "One self-describing matrix per requested cell, in request order. Each carries\nits own row/column element ids and the served-unit label.",
          "items": {
            "$ref": "#/$defs/SensitivityMatrix"
          },
          "type": "array"
        },
        "status": {
          "$ref": "#/$defs/SolveStatus"
        },
        "va": {
          "description": "Voltage angle, radians (every path except socwr, which is W-space).",
          "items": {
            "$ref": "#/$defs/BusScalar"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "vm": {
          "description": "Voltage magnitude, per unit (ACPF or square root of SOCWR squared magnitude).",
          "items": {
            "$ref": "#/$defs/BusScalar"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "w": {
          "description": "Squared voltage magnitude `w = |V|^2`, per unit squared (socwr). The conic\nrelaxation does not guarantee a globally consistent set of voltage angles.",
          "items": {
            "$ref": "#/$defs/BusScalar"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "wi": {
          "items": {
            "$ref": "#/$defs/BranchScalar"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "wr": {
          "description": "Real and imaginary oriented branch voltage products (SOCWR).",
          "items": {
            "$ref": "#/$defs/BranchScalar"
          },
          "type": [
            "array",
            "null"
          ]
        }
      },
      "required": [
        "formulation",
        "status"
      ],
      "type": "object"
    },
    "GenDispatch": {
      "description": "Generator dispatch, keyed by original generator id. `qg` is `None` on the DC paths.",
      "properties": {
        "bus": {
          "description": "Original bus identity, allowing exact aggregation of co-located dispatch.",
          "format": "uint",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "gen": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "pg": {
          "format": "double",
          "type": "number"
        },
        "qg": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "gen",
        "pg"
      ],
      "type": "object"
    },
    "BranchFlow": {
      "description": "Branch flows, keyed by original branch id (plus the row uid when carried, as in\n[`BusScalar`]). `pf` (from-end active, MW) and `loading` (|S|/limit,\ndimensionless) are present on every formulation that has flows; the reactive\nand to-end legs are `None` on the DC paths.",
      "properties": {
        "branch": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "loading": {
          "format": "double",
          "type": "number"
        },
        "pf": {
          "format": "double",
          "type": "number"
        },
        "pt": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "qf": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "qt": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        },
        "uid": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "branch",
        "pf",
        "loading"
      ],
      "type": "object"
    },
    "Problem": {
      "description": "Which problem to solve. The convex/power flow solve paths, as the lowercase JSON\ntags `\"dcpf\"`/`\"dcopf\"`/`\"acpf\"`/`\"socwr\"`. A plain (not internally tagged) enum\nso a request that omits it defaults to [`DcOpf`](Problem::DcOpf), and `{}` is a\nvalid base-case DC OPF request.\n\nThe `\"acopf\"` tag (full nonlinear AC OPF) is retained for wire-format stability\nbut is not solved by this build: [`capabilities_json`] reports it unavailable and\nrequesting it returns a clean `Err`.",
      "oneOf": [
        {
          "const": "dcpf",
          "description": "DC power flow: angles and flows at the fixed generator setpoints. No prices,\nno dispatch, no sensitivity.",
          "type": "string"
        },
        {
          "const": "dcopf",
          "description": "DC OPF: the LMP / dispatch / flow workhorse. Differentiable via the DC KKT.",
          "type": "string"
        },
        {
          "const": "acpf",
          "description": "AC polar Newton power flow. Voltages and nodal injections. Differentiable\nvia the AC Newton system.",
          "type": "string"
        },
        {
          "const": "socwr",
          "description": "SOCWR (Jabr) conic relaxation of AC OPF. Differentiable via the conic KKT.",
          "type": "string"
        },
        {
          "const": "acopf",
          "description": "Full nonlinear AC OPF. Not available in this build (the dispatch errors\ncleanly); the tag is kept so the JSON format stays stable.",
          "type": "string"
        }
      ]
    },
    "BusInjection": {
      "description": "A nodal net injection (MW / MVAr), keyed by original bus id (plus the row uid\nwhen carried, as in [`BusScalar`]). Injections describe the net nodal power balance.",
      "properties": {
        "bus": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "p": {
          "format": "double",
          "type": "number"
        },
        "q": {
          "format": "double",
          "type": "number"
        },
        "uid": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "bus",
        "p",
        "q"
      ],
      "type": "object"
    },
    "Iterations": {
      "anyOf": [
        {
          "description": "Interior-point iterate trace (dcopf / socwr).",
          "items": {
            "$ref": "#/$defs/SolveIteration"
          },
          "type": "array"
        },
        {
          "description": "Newton iteration count and final infinity-norm mismatch (acpf).",
          "properties": {
            "count": {
              "format": "uint",
              "minimum": 0,
              "type": "integer"
            },
            "residual": {
              "format": "double",
              "type": "number"
            }
          },
          "required": [
            "count",
            "residual"
          ],
          "type": "object"
        }
      ],
      "description": "The convergence record. OPF paths carry the full interior-point trace (for the\nsolve-card sparkline); the AC power flow carries its Newton count and final\nmismatch. Untagged: the OPF arm serializes to the same bare array the DC OPF\nalways returned."
    },
    "SolveIteration": {
      "description": "One interior-point iterate: the iteration index, the primal objective, and\nthe primal and dual residuals. Collected once per Clarabel iteration to draw\nthe convergence plot. Shape matches the frontend `SolveIteration`.",
      "properties": {
        "inf_du": {
          "format": "double",
          "type": "number"
        },
        "inf_pr": {
          "format": "double",
          "type": "number"
        },
        "iter": {
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "objective": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "iter",
        "objective",
        "inf_pr",
        "inf_du"
      ],
      "type": "object"
    },
    "BusScalar": {
      "description": "A scalar keyed by original bus id (LMP, voltage, angle, squared magnitude).\n`uid` is the bus's powerio row uid when the solved network carried one, so an\noverlay can re-key on stable identity instead of the positional id.",
      "properties": {
        "bus": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "uid": {
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "bus",
        "value"
      ],
      "type": "object"
    },
    "SensitivityMatrix": {
      "description": "A self-describing sensitivity result: `values[r][c] = d(rows[r])/d(cols[c])`,\nwith row and column metadata naming each quantity and its source element, and the\nserved-unit label.",
      "properties": {
        "cols": {
          "items": {
            "$ref": "#/$defs/ColMeta"
          },
          "type": "array"
        },
        "rows": {
          "items": {
            "$ref": "#/$defs/RowMeta"
          },
          "type": "array"
        },
        "units": {
          "type": "string"
        },
        "values": {
          "description": "`values[r][c] = d(operand_r)/d(parameter_c)`, in the units named by `units`. The\nengine produces per-unit values; the api edge rescales to served units.",
          "items": {
            "items": {
              "format": "double",
              "type": "number"
            },
            "type": "array"
          },
          "type": "array"
        }
      },
      "required": [
        "values",
        "rows",
        "cols",
        "units"
      ],
      "type": "object"
    },
    "ColMeta": {
      "description": "Identity and quantity metadata for one column of a [`SensitivityMatrix`].",
      "properties": {
        "element": {
          "$ref": "#/$defs/ElementId"
        },
        "index": {
          "description": "Dense index of the element this column varies.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "parameter": {
          "$ref": "#/$defs/Parameter"
        }
      },
      "required": [
        "parameter",
        "element",
        "index"
      ],
      "type": "object"
    },
    "ElementId": {
      "description": "A source-id reference for a dense row or column, so a [`SensitivityMatrix`]\nself-describes and the api serializes it without re-deriving id maps.",
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "Bus": {
              "format": "uint",
              "minimum": 0,
              "type": "integer"
            }
          },
          "required": [
            "Bus"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "Branch": {
              "format": "uint",
              "minimum": 0,
              "type": "integer"
            }
          },
          "required": [
            "Branch"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "Generator": {
              "format": "uint",
              "minimum": 0,
              "type": "integer"
            }
          },
          "required": [
            "Generator"
          ],
          "type": "object"
        }
      ]
    },
    "Parameter": {
      "description": "What a sensitivity is taken *with respect to* — the parameter whose hand-derived\n`dK/dp` column drives the solve.",
      "oneOf": [
        {
          "additionalProperties": false,
          "description": "Bus active/reactive demand `pd` / `qd`, per bus.",
          "properties": {
            "Demand": {
              "$ref": "#/$defs/Power"
            }
          },
          "required": [
            "Demand"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Generation cost coefficient, per generator.",
          "properties": {
            "Cost": {
              "$ref": "#/$defs/CostTerm"
            }
          },
          "required": [
            "Cost"
          ],
          "type": "object"
        },
        {
          "const": "LineLimit",
          "description": "DC thermal limit `fmax` / AC-conic apparent-power `|S|` limit, per branch.",
          "type": "string"
        },
        {
          "additionalProperties": false,
          "description": "Branch series admittance `g` / `b`, per branch.",
          "properties": {
            "SeriesAdmittance": {
              "$ref": "#/$defs/GB"
            }
          },
          "required": [
            "SeriesAdmittance"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Bus shunt admittance `gs` / `bs`, per bus.",
          "properties": {
            "ShuntAdmittance": {
              "$ref": "#/$defs/GB"
            }
          },
          "required": [
            "ShuntAdmittance"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Voltage-magnitude bound right-hand side (the `w = |V|²` bound), per bus.",
          "properties": {
            "VoltageBound": {
              "$ref": "#/$defs/Bound"
            }
          },
          "required": [
            "VoltageBound"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Generator output bound right-hand side (`pmax` / `pmin` / `qmax` / `qmin`),\nper generator.",
          "properties": {
            "GenBound": {
              "properties": {
                "bound": {
                  "$ref": "#/$defs/Bound"
                },
                "power": {
                  "$ref": "#/$defs/Power"
                }
              },
              "required": [
                "power",
                "bound"
              ],
              "type": "object"
            }
          },
          "required": [
            "GenBound"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "description": "Transformer tap ratio / phase shift, per branch.",
          "properties": {
            "Transformer": {
              "$ref": "#/$defs/TapKind"
            }
          },
          "required": [
            "Transformer"
          ],
          "type": "object"
        },
        {
          "const": "Switching",
          "description": "Branch switching state `sw` in `[0, 1]`, per branch.",
          "type": "string"
        }
      ]
    },
    "CostTerm": {
      "description": "Which generation-cost coefficient: the quadratic `cq` or the linear `cl`.",
      "enum": [
        "Quadratic",
        "Linear"
      ],
      "type": "string"
    },
    "GB": {
      "description": "Conductance `g` or susceptance `b`, the real/imaginary parts of an admittance.",
      "enum": [
        "Conductance",
        "Susceptance"
      ],
      "type": "string"
    },
    "Bound": {
      "description": "A min or max bound, e.g. the lower/upper voltage-magnitude limit.",
      "enum": [
        "Min",
        "Max"
      ],
      "type": "string"
    },
    "TapKind": {
      "description": "A transformer control: the tap ratio or the phase-shift angle.",
      "enum": [
        "Ratio",
        "PhaseShift"
      ],
      "type": "string"
    },
    "RowMeta": {
      "description": "Identity and quantity metadata for one row of a [`SensitivityMatrix`].",
      "properties": {
        "element": {
          "$ref": "#/$defs/ElementId"
        },
        "index": {
          "description": "Dense index of the element this row reports.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "operand": {
          "$ref": "#/$defs/Operand"
        }
      },
      "required": [
        "operand",
        "element",
        "index"
      ],
      "type": "object"
    },
    "SolveStatus": {
      "description": "A solve outcome that succeeded. A failed solve is the `Err` arm of a solve entry.",
      "oneOf": [
        {
          "const": "optimal",
          "description": "An OPF reached optimality.",
          "type": "string"
        },
        {
          "const": "feasible",
          "description": "A power flow converged to a feasible point.",
          "type": "string"
        }
      ]
    },
    "BranchScalar": {
      "description": "A branch-indexed voltage product, in squared per unit.",
      "properties": {
        "branch": {
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "value": {
          "format": "double",
          "type": "number"
        }
      },
      "required": [
        "branch",
        "value"
      ],
      "type": "object"
    }
  }
}