Add objective function documentation

[Copilot]

Users have no way to discover available objective functions or learn how to write custom ones without reading source code.

Changes

• docs/objective_functions.md — New comprehensive guide covering:

  • All built-in string objectives with wrapper compatibility matrix
  • Alias table ("loss" → "loss_min", etc.)
  • Per-wrapper objective function tables (matrix, matrix_bess, pyomo)
  • Custom objective signatures and worked examples for both CVXPY and Pyomo
  • Penalized/soft-constraint objectives and weight parameters
  • Low-level Pyomo API (set_objective, create_penalized_objective, convenience functions)

• README.md — New "Objective Functions" section with summary table, custom objective example, and link to full guide

Usage

# Built-in string objective
result = case.run_opf("loss_min", control_variable="PQ")

# Custom callable (matrix wrapper)
def my_obj(model, xk, **kwargs):
    idx = []
    for ph in "abc":
        if model.phase_exists(ph):
            idx.extend(model.x_maps[ph].pij.to_numpy().tolist())
    return cp.sum(xk[idx] ** 2)

result = case.run_opf(objective=my_obj, control_variable="PQ", wrapper="matrix")

# Custom callable (pyomo wrapper)
def my_rule(model):
    return sum(
        (model.p_flow[j, p, t] ** 2 + model.q_flow[j, p, t] ** 2) * model.r[j, p + p]
        for j, p in model.branch_phase_set for t in model.time_set
    )

result = case.run_opf(objective=my_rule, control_variable="PQ", wrapper="pyomo")

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Improve documentation of using objective functions.</issue_title>
<issue_description>At the moment, the user has no way of knowing what objective functions are available for any given wrapper or model or how to create new custom objective functions.</issue_description>

<agent_instructions>We need the package to be usable by users who do not have the source code and are only using it as a pip install. One place they can look is the readme which is visible on github. We need to improve that readme or if possible have links from that readme to other documentation pages accessible through github.com</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Improve documentation of using objective functions. #10

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[nathantgray]

@copilot The main readme should have tables of objective function options for each wrapper type. Each wrapper section should then link to a docs file for each wrapper. That wrapper doc file should have all of the objective function aliases as well as examples for creating custom objectives and explanations for accessing variables.