Generated CLI Surface

Generated by scripts/render_public_surface.py. Do not edit directly.

Canonical Methods

• acpf
• acpf-warm
• fdpf
• dcpf
• dc-opf
• ac-opf
• scopf
• hvdc
• contingency
• n-2
• orpd
• ots
• injection-capability
• nerc-atc

Solver Backends

• default
• highs
• gurobi
• cplex
• copt
• ipopt

Full Help Output

AC/DC power flow solver

Usage: surge-solve [OPTIONS] <CASE_FILE>

Arguments:
  <CASE_FILE>  Path to the case file (.m, .raw, .cdf, .surge.json, .surge.json.zst, or .surge.bin)

Options:
  -m, --method <METHOD>
          Canonical solution method [default: acpf] [possible values: acpf, acpf-warm, fdpf, dcpf, dc-opf, ac-opf, scopf, hvdc, contingency, n-2, orpd, ots, injection-capability, nerc-atc]
  -t, --tolerance <TOLERANCE>
          Convergence tolerance in per-unit [default: 1e-8]
      --max-iter <MAX_ITER>
          Maximum iterations [default: 500]
      --flat-start
          Use flat start (Vm=1.0, Va=0.0) instead of case data voltages
      --cont-flat-start
          Initialize each N-1 contingency from flat start instead of base-case warm start
      --no-q-limits
          Disable reactive power limit enforcement (PV→PQ switching)
      --q-sharing <Q_SHARING>
          Reactive power sharing mode among generators at the same bus [default: capability] [possible values: capability, mbase, equal]
      --angle-reference <ANGLE_REFERENCE>
          Voltage angle reference convention for output angles [default: preserve-initial] [possible values: preserve-initial, zero, distributed-load, distributed-generation, distributed-inertia]
  -o, --output <OUTPUT>
          Output format: text, json [default: text] [possible values: text, json]
      --detail <DETAIL>
          Text output detail level: auto uses full tables for small cases and summaries for larger ones [default: auto] [possible values: auto, summary, full]
      --screening <SCREENING>
          Contingency screening mode: off, lodf, fdpf [default: off] [possible values: off, lodf, fdpf]
      --thermal-threshold <THERMAL_THRESHOLD>
          Thermal overload threshold (percent of rate_a) [default: 100.0]
      --ac-opf-max-iter <AC_OPF_MAX_ITER>
          Maximum NLP iterations for AC-OPF. 0 = auto: max(500, n_buses / 20) [default: 0]
      --no-capability-curves
          Disable generator P-Q capability curve (D-curve) constraints in AC-OPF
      --ac-discrete-mode <AC_DISCRETE_MODE>
          AC-OPF discrete control mode [default: continuous] [possible values: continuous, round-and-check]
      --optimize-svc
          Co-optimize SVC/STATCOM susceptance as continuous NLP variables in AC-OPF
      --optimize-tcsc
          Co-optimize TCSC compensating reactance as continuous NLP variables in AC-OPF
      --dc-opf-warm-start <DC_OPF_WARM_START>
          Seed AC-OPF initial angles from a DC-OPF solution [default: auto] [possible values: auto, yes, no]
      --dc-cost-mode <DC_COST_MODE>
          DC-OPF cost formulation: qp (exact quadratic) or lp (PWL tangent-line approximation). DC-OPF defaults to qp; SCOPF defaults to lp [possible values: qp, lp]
      --dc-pwl-breakpoints <DC_PWL_BREAKPOINTS>
          Number of PWL breakpoints per generator when --dc-cost-mode lp is used (default: 20) [default: 20]
      --scopf-formulation <SCOPF_FORMULATION>
          SCOPF formulation: dc (default) or ac [default: dc] [possible values: dc, ac]
      --scopf-mode <SCOPF_MODE>
          SCOPF mode: preventive (default) or corrective [default: preventive] [possible values: preventive, corrective]
      --scopf-viol-tol <SCOPF_VIOL_TOL>
          SCOPF: violation tolerance in per-unit (default: 0.01 = 1 MW at 100 MVA) [default: 0.01]
      --scopf-max-cuts <SCOPF_MAX_CUTS>
          SCOPF: maximum cuts to add per iteration [default: 100]
      --scopf-max-iter <SCOPF_MAX_ITER>
          SCOPF: maximum constraint generation iterations [default: 20]
      --contingency-rating <CONTINGENCY_RATING>
          SCOPF: post-contingency thermal rating (rate-a, rate-b, rate-c) [default: rate-a] [possible values: rate-a, rate-b, rate-c]
      --no-flowgates
          SCOPF: disable flowgate and interface constraints
      --no-voltage-security
          SCOPF: disable post-contingency voltage limits in AC-SCOPF
      --no-angle-limits
          SCOPF: disable branch angle-difference constraints
      --gen-limit-penalty <GEN_LIMIT_PENALTY>
          Penalty cost ($/MW) for soft generator Pmin/Pmax limits in DC-OPF and SCOPF. When set, hard generator bounds are relaxed and violations are penalized
      --use-loss-factors
          Enable iterative loss factor compensation in DC-OPF and SCOPF
      --loss-iterations <LOSS_ITERATIONS>
          Maximum loss factor iterations (default: 3) [default: 3]
      --loss-tolerance <LOSS_TOLERANCE>
          Loss factor convergence tolerance (default: 1e-3) [default: 0.001]
      --export <EXPORT>
          Export a full solved-state artifact to this file path (JSON or JSON.zst)
      --export-format <EXPORT_FORMAT>
          Convert format override for --convert: matpower, psse33, psse35, surge-json, surge-bin, xiidm, dss, epc, ucte, cgmes, cgmes3
      --solver <SOLVER>
          Solver backend [default: default] [possible values: default, highs, gurobi, cplex, copt, ipopt]
      --orpd-objective <ORPD_OBJECTIVE>
          ORPD objective: loss, voltage, or combined [default: loss] [possible values: loss, voltage, combined]
      --orpd-v-ref <ORPD_V_REF>
          ORPD voltage target in per-unit for voltage and combined objectives [default: 1.0]
      --orpd-loss-weight <ORPD_LOSS_WEIGHT>
          ORPD weight on active losses for the combined objective [default: 1.0]
      --orpd-voltage-weight <ORPD_VOLTAGE_WEIGHT>
          ORPD weight on voltage deviation for the combined objective [default: 1.0]
      --hvdc-method <HVDC_METHOD>
          HVDC solver method: auto, sequential, block_coupled, hybrid (default: auto) [default: auto] [possible values: auto, sequential, block_coupled, hybrid]
      --hvdc-dc-tol <HVDC_DC_TOL>
          Inner DC solver tolerance for explicit DC-network HVDC methods [default: 1e-8]
      --hvdc-dc-max-iter <HVDC_DC_MAX_ITER>
          Inner DC solver iteration limit for explicit DC-network HVDC methods [default: 50]
      --include-hvdc
          Enable HVDC in AC-OPF (auto-detects from network data if not specified)
      --parse-only
          Parse the case file and print a summary without solving
      --convert <CONVERT>
          Convert case file to another format without solving (output path)
      --voltage-stress-mode <VOLTAGE_STRESS_MODE>
          Contingency voltage stability mode: off, proxy, or exact_l_index [default: proxy] [possible values: off, proxy, exact_l_index]
      --l-index-threshold <L_INDEX_THRESHOLD>
          L-index threshold for exact_l_index voltage stress mode (default: 0.7) [default: 0.7]
      --enforce-interchange
          Enforce area interchange targets from network area schedules
      --discrete-controls
          Enable discrete controls (PAR, OLTC, switched shunts) in contingency analysis
      --store-voltages
          Store post-contingency bus voltages and branch flows in JSON output
      --source-buses <SOURCE_BUSES>
          Source bus numbers for transfer path (nerc-atc method)
      --sink-buses <SINK_BUSES>
          Sink bus numbers for transfer path (nerc-atc method)
      --post-ctg-rating-frac <POST_CTG_RATING_FRAC>
          Post-contingency rating fraction for injection-capability (default: 1.0) [default: 1.0]
  -v, --verbose...
          Increase logging verbosity (-v = info, -vv = debug, -vvv = trace)
  -q, --quiet
          Quiet mode — suppress all output except errors
      --log-format <LOG_FORMAT>
          Log output format: text (default) or json [default: text] [possible values: text, json]
  -h, --help
          Print help
  -V, --version
          Print version