Plan: v1 semantics community discussion (open after #717 merges)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 257
- Forks
- 87
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 29
Description
[!NOTE]
This tracking issue was drafted with AI.
Plan for a community Q&A discussion on the v1 arithmetic semantics, to open after #717 merges (so the convention.md and migration-guide links resolve on master).
Prerequisites / checklist
- Enable GitHub Discussions on the repo — currently disabled (
hasDiscussionsEnabled: false); a maintainer/admin repo setting. - Merge #717 and the doc follow-ups (#855 migration-guide coverage, #856 §11 fix) so the links go live on
master. - Open a pinned Q&A discussion from the skeleton below.
- Cross-link the discussion from #714 (bug catalogue) and #717 (the change).
- Notify downstream — PyPSA, PyPSA-Eur, Calliope, flixopt — with a short pointer in their repos (the discussion is passive; maintainers won't see it otherwise).
Why a discussion (and not just issues)
The discussion is the low-friction front door for "will this break my model?" / "intended or a bug?" questions, and Q&A answers can be marked into an FAQ. Concrete, reproducible breakages still get funneled to issues so they stay tracked.
Discussion skeleton (Q&A category, pinned) — draft
Intent line to be handwritten by the poster.
What's changing — linopy is introducing a stricter, opt-in arithmetic convention ("v1") that replaces legacy's silent guesses (filled NaN, positional joins, absent-as-zero) with explicit rules that raise, so a wrong model errors at build time instead of returning a wrong number.
- Rules: link
arithmetics-design/convention.md - Migrate: link
doc/migrating-to-v1.rst(readthedocs) - Fixes: #714 · Change: #717
Timeline — (1) now: opt-in via linopy.options["semantics"] = "v1", legacy default + warns; (2) later minor: v1 default, legacy one more cycle; (3) 1.0: legacy removed.
Try it — set the option; to surface every site, run the suite under legacy with warnings.filterwarnings("error", category=LinopySemanticsWarning).
How to use the thread — questions here (answers marked → FAQ); concrete breakages / gaps in the guide → open an issue and link back; downstream maintainers especially wanted early.
FAQ seed — change anything today? (no) · a warning I don't own? (upstream; silence meanwhile) · why raise? (no silent wrong answers) · when default? (a later minor, announced here) · maintainer recipe? (opt in on a branch → warning-as-error → fix → run v1 → release).
Downstream notice template
linopy v1 arithmetic semantics — opt-in now, default later.
linopy is rolling out a stricter arithmetic convention that raises where it used to guess (NaN fills, positional joins, absent-as-zero). It's opt-in today and warns under legacy, becoming the default in a later release. This likely affects<library>; the migration guide (<link>) has a situation→fix table, and there's a discussion for questions:<link>. Opting in early on a branch (linopy.options["semantics"] = "v1") will surface what changes.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by checking #717, #855, and #856 to confirm the linked convention and migration documents are on master. Then verify whether GitHub Discussions can be enabled and use the supplied skeleton to open a pinned Q&A, cross-link #714 and #717, and notify PyPSA, PyPSA-Eur, Calliope, and flixopt. Done means the discussion and downstream pointers are live.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100