tellegen.dev

{
  "type": "object",
  "properties": {
    "study_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "expected_revision": {
      "type": "integer",
      "minimum": 0
    },
    "operation": {
      "additionalProperties": false,
      "properties": {
        "goal": {
          "$ref": "#/$defs/GoalRevision"
        },
        "kind": {
          "const": "revise_goal",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "goal"
      ],
      "type": "object"
    }
  },
  "required": [
    "study_id",
    "expected_revision",
    "operation"
  ],
  "additionalProperties": false,
  "$defs": {
    "GoalRevision": {
      "additionalProperties": false,
      "description": "A goal revision retains its own anchor and interpretation.",
      "properties": {
        "anchor_state": {
          "type": "string"
        },
        "decisions": {
          "$ref": "#/$defs/DecisionSpace"
        },
        "interpretation": {
          "type": "string"
        },
        "objective": {
          "$ref": "#/$defs/StudyObjective"
        },
        "parent": {
          "type": [
            "string",
            "null"
          ]
        },
        "request": {
          "type": "string"
        },
        "success_value": {
          "format": "double",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "required": [
        "anchor_state",
        "request",
        "interpretation",
        "objective",
        "decisions"
      ],
      "type": "object"
    },
    "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"
    },
    "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"
    }
  }
}