[FBumann]

Prompt: Do a pr onto specsolve main now, renaming it
And adjust other related names too.
So it's more intuitive overall

Note

The following content was generated by AI.

Piece is now Term, in _engine/terms.py. A term is linear, quadratic or constant. This removes the words "piece", "term piece", "const piece" and "constant part". The compiler's quadratic flag is now admits_quadratic. Behaviour does not change. The rename also covers the engine code that #2051 added.

What was renamed

before	after
_engine/pieces.py	_engine/terms.py
Piece	Term
kinds 'term', 'quad', 'const'	'linear', 'quadratic', 'constant'
CompiledExpression.terms, .consts, .quads	.linear, .constant, .quadratic
Compiler.expression(..., quadratic=)	Compiler.expression(..., admits_quadratic=)
map_pieces	map_terms
refuse_a_piece_without_the_dims	refuse_a_term_without_the_dims
join_mul, join_quad, join_pow	times_constant, times_variable, to_the_power
spread_piece (from #2051)	spread_term
_parameter_piece, _variable_piece, _solved_piece, _dual_piece, _sum_piece, _group_piece, _at_piece, _remap_piece	the same names ending in _term
translate_piece, window_piece	translate_term, window_term

• The flag was renamed after a follow-up question about the names. It is a permission, not a kind of term: it says whether the position may hold a product of two variables. With its old name, a local quadratic list shadowed it. Now the locals in product, quotient and _build_constraint use the plain names linear, quadratic and constant, like the fields of CompiledExpression. Its docstring no longer says that a constraint row cannot hold a product, which was false for a quadratic constraint.
• The flag stays, because its assert checks the compiler against mathspec's is_quadratic, and declares_quadratic also decides which constraints the solver capability check sees.
• Lists of frames that were waiting to be concatenated, which were also called pieces, are now frames (and aligned in readback).
• The docstrings, the architecture page (node table, module table and glossary), verification.md, the test names and the test prose use the new words. grep -i piece src/specsolve/_engine finds only piecewise.
• One user-visible string changed. The a constant summed beside a term is accepted by check and the linopy lane, refused by the engine #1137 refusal now says "a constant term of the expression" instead of "a constant part". The tests match on specsolve cannot build and Declare the parameter over, and both phrases are unchanged.

Verification

The head c8dc90b holds main with #2051 merged in. Its tree is the same as the tree of 20db613, where these were run with Xpress 10 installed:

• ruff check . and ruff format --check . pass.
• pyrefly check reports 0 errors.
• pytest -n 4: 5976 passed, 458 skipped, 4 xfailed.
• python -m tests.fuzz --seeds 0:1000 --baseline tests/fuzz/baseline.json: every finding is one that the baseline already holds.
• pixi run check was not run, because pixi is not installed here. Its parts were run directly.

Not done

• tests/linopy_lane and tests/fuzz keep the words terms and const, because there they are linopy's own API.
• Unrelated uses of "piece" stay. In _strategy.py and _archive.py, "pieces" means slices of a table. piecewise and the GenX curve's "piece" are language words.
• The local name p for a term, the cval and coeff columns, constant_scalar and the __const {i}__ alias are unchanged. Renaming them would add churn and remove no concept.
• a constant summed beside a term is accepted by check and the linopy lane, refused by the engine #1137 is a separate change: a constant term beside a linear one, under a sum along a dimension that the constant does not carry. Mathspec's per-node dims (feat(program): each expression node states the dimensions it is read over energy-models/mathspec#899) may let the engine spread the constant term before the sum, instead of refusing it.
• Departure from AGENTS.md: a pass that is only a rename normally gets sent back. This one was asked for, and it removes a concept, because "piece" and "term" were two words for one thing.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WjaoQERHiPueVjahe7oKSG

Summary by CodeRabbit

• Refactor
  • Updated expression terminology to distinguish linear, quadratic, and constant terms.
  • Reorganized how expressions are represented and processed across compilation, evaluation, and assembly. Existing calculation behavior, including handling of missing values and quadratic expressions, is preserved.
• Documentation
  • Updated architecture and verification guidance to use consistent terminology for expression components.

[read-the-docs-community]

Documentation build overview

📚 specsolve | 🛠️ Build #35551157 | 📁 Comparing c8dc90b against latest (5a78e3f)

  🔍 Preview build  

110 files changed · ± 110 modified

± Modified

• development/architecture/index.html
• development/verification/index.html
• examples/facility_location/index.html
• examples/genx_piecewise_fuel/index.html
• examples/multi_period/index.html
• examples/osemosys_utopia/index.html
• examples/piecewise/index.html
• examples/piecewise_conversion/index.html
• examples/piecewise_ragged/index.html
• examples/pypsa_ac_dc/index.html
• and 100 more...

[codspeed]

Merging this PR will degrade performance by 67.75%

❌ 1 regressed benchmark
✅ 103 untouched benchmarks
⏩ 307 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	test_read[commitment-s-specsolve-parquet]	220.7 KB	684.3 KB	-67.75%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing claude/determined-johnson-irmuuz (c8dc90b) with main (582e5c1)²}

Footnotes

1. 307 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (603606c) during the generation of this report, so 582e5c1 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 86892225-26e3-4a8a-8c97-7e8606f22d18

Commits

Reviewing files that changed from the base of the PR and between 678a2fd and c8dc90b.

Files selected for processing: 7

• src/specsolve/_engine/assembly.py
• src/specsolve/_engine/compiler.py
• src/specsolve/_engine/coverage.py
• src/specsolve/_engine/readback.py
• src/specsolve/_engine/shifts.py
• src/specsolve/_engine/terms.py
• tests/linopy_lane/coverage.py

Files skipped from review as they are similar to previous changes: 1

• tests/linopy_lane/coverage.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

Walkthrough

The engine replaces Piece with Term and stores compiled expressions in separate linear, quadratic, and constant collections. Compiler operations, assembly, downstream consumers, documentation, and tests use the updated terminology and fields.

Changes: Compiled expression term model

Layer / File(s)	Summary
Term model and compiled expression contract src/specsolve/_engine/terms.py, docs/development/architecture.md, docs/development/verification.md, tests/test_architecture.py, tests/test_docs_site.py	The engine defines Term with linear, quadratic, and constant kinds. CompiledExpression stores these components in separate fields. Documentation and fan-in imports use the term terminology.
Expression compilation and term operations src/specsolve/_engine/compiler.py, src/specsolve/_engine/shifts.py, tests/test_compiler.py, tests/test_absence.py, tests/test_cases.py, tests/test_grouped_sum.py, tests/test_expression_sweep.py	Compiler and shift helpers now use Term values and the separated expression fields. The updated tests inspect the revised fields and retain their described behavior checks.
Assembly and downstream term consumers src/specsolve/_engine/assembly.py, src/specsolve/_engine/coverage.py, src/specsolve/_engine/labels.py, src/specsolve/_engine/predicates.py, src/specsolve/_engine/readback.py, src/specsolve/_engine/scope.py, tests/linopy_lane/coverage.py, tests/test_expression_at_a_point.py, tests/test_expression_reader.py, tests/test_quadratic_objective.py, tests/test_relational.py	Constraint and objective assembly, coverage checks, predicates, readback, scope, and labels now use the updated term representation. Related tests and descriptions use the revised fields and terminology.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Refactor

Merge Risk: Minimal · up to c8dc9

No actionable merge-blocking issue was identified in the term-model migration; the change is ready for normal merge checks.

Security architecture risk: Low · up to c8dc9

The checked paths preserve validation, expression handling, and failure containment. No new security exposure was identified. Remaining risk concerns compatibility with code outside this repository that uses the renamed private interfaces.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The demonstrated propagation scope is expression compilation and its in-process consumers. The checked changes do not expand the public expression route or solver-handoff authority. Attacker provenance, tenant exposure, and external private-interface consumers remain outside the established evidence.

Trust Boundaries and Controls

• observed — The checked data-validation controls remain in place: assembly checks null constants and coefficients before aggregation can conceal missing values, while readback retains coverage and divisor checks. No bypass of these controls was identified in the migrated consumers.

Resilience and Maintainability Implications

• observed — The normal build entrypoint clears the published model, creates fresh construction state, and publishes only after Assembly.run succeeds. Partial assembly mutations therefore do not publish a partial model through that path. Direct reuse and unsynchronized concurrent access remain preexisting limitations, not changes introduced by this PR.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and accurately summarizes the main change: replacing engine “piece” terminology with linear, quadratic, and constant term terminology.
Docstring Coverage		Docstring coverage is 96.67% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentati…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 96.67% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 60 functions across 21 files.

Finishing Touches

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts