[FBumann]

Prompt: COuld we add a proper "connection" relation somewhere? (Where: "New example".)

Note

The following content was generated by AI.

What this changes

A new gallery example, "Units with ports" (examples/connection.yaml). One relation lists the bus and role of each unit port, masks efficiency to the output ports, and the balance groups through it by bus. Stacked on #945.

relations:
  connection:
    key: [unit, port]
    values: [bus, role]
    missing: absent
parameters:
  efficiency:
    dims: [unit, port, snapshot]
    where: "connection[role] == 'output'"
    missing: 1
expressions:
  injection:
    dims: [unit, port, snapshot]
    cases:
      draws: { when: "connection[role] == 'input'", expression: -flow }
    otherwise: efficiency * flow
constraints:
  balance:
    dims: [bus, snapshot]
    expression: supply + sum(injection, over=[unit, port], by=connection[bus]) == load

$$\mathit{supply}_{b,t} + \sum_{u,, p ,:, \mathrm{connection.bus}(u, p) = b} \mathit{injection}_{u,p,t} = \mathrm{load}_{b,t}$$

What the example shows, method, gates, and what was not done

What it shows:

• The relation is keyed by port, not by bus, so two ports of one unit may attach to one bus (Branch components with multiple ports at one bus PyPSA/PyPSA#2015).
• A parameter's mask that reads a relation's value column. efficiency has coordinates only at the output ports, and missing: 1 fills only those. The legend prints: only where $\mathrm{connection.role}(u, p) = \text{'output'}$, $1$ where the data has no row.
• A case that reads the same column. An input port puts -flow into its bus. Outside connection, no case claims the coordinate, and efficiency is absent there, so injection is absent and the balance adds only real ports.

Files:

• the spec, examples/connection.yaml
• its page, docs/examples/connection.md. The YAML and math block was written by python -m tools.gallery, not by hand.
• a row in MODELS in tools/gallery.py
• the nav entry in mkdocs.yml
• a bullet in docs/examples/index.md
• the page added to .prettierignore, as a generated page.

Gates on the head, f18b1d7, which merges #945's head after main reached it through #894. The merge had no conflict. With pixi:

• pixi run lint passes.
• pixi run test passes: 3131 passed, 1 skipped. The new spec adds 11 tests through the suite's SPECS corpus.
• pixi run docs-build passes.
• compile-tex failed on every document because the container could not download the TeX bundle. CI compiles connection.tex with the rest.

Earlier, on #945's ff91d15 plus this commit, python -m tools.gallery wrote every other page back unchanged.

With #949. A trial merge of #949 (the case-check fixes) into this head conflicts only in CHANGELOG.md, and pytest gives 3143 passed, 1 skipped.

Not done:

• The PyPSA port keeps link_output and process_output. Moving it to a connection relation would overlap with docs(examples): a link's or a process's output port reads its owner and its bus from one relation #892.
• The -1 on an input port comes from the case draws, not from a cased missing: (Cased missing #940).

Why

The gallery had no spec where one relation is both the map a balance groups through and the mask of a parameter. This is the pattern #944 needs for connections, written with relations as they are.

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #35353749 | 📁 Comparing f18b1d7 against latest (97c44b4)

  🔍 Preview build  

36 files changed · + 1 added · ± 35 modified

+ Added

• examples/connection/index.html

± Modified

• examples/index.html
• reference/api/index.html
• reference/changelog/index.html
• reference/glossary/index.html
• reference/language/index.html
• reference/notation/index.html
• reference/program/index.html
• reference/reading/index.html
• reference/spec/index.html
• examples/pypsa/carrier/index.html
• and 25 more...