From e66b3fedcb95823591af399cf13766c02a2f6113 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 08:08:38 +0000 Subject: [PATCH 1/4] chore: release 0.4.0 The 0.4.0 section holds all 15 pull requests merged since v0.3.0. Above them, the notes name each break in a file and in the Python API, and the rewrite for it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01B5NaERV1RNkFNcrngYUefA --- CHANGELOG.md | 75 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 64 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 79b9a7ea..0ff6a3ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,23 +10,76 @@ request renames that heading to the version and the day, such as `## 0.1.0 (2026-10-01)`, and edits the section into the release notes. Merging it releases that version ([RELEASING.md](https://github.com/energy-models/mathspec/blob/main/RELEASING.md)). -## Upcoming version +## 0.4.0 (2026-10-21) + +This release renames the named conditions of a file from `masks:` to `conditions:`, and renames most classes of the Python API. A file that 0.3.0 loads may not load in 0.4.0: it fails where it has a `masks:` section, or a named expression whose `dims:` names a dimension that its expression is not indexed over. The language version stays `0`. + +A spec file: + +- A file names its conditions under `conditions:`, and each entry writes its condition under `condition:` instead of `where:`. Another file reads them under `given: conditions:`. A file that still writes `masks:` is refused, and the error names the valid keys ([#907](https://github.com/energy-models/mathspec/pull/907)). + + ```yaml + conditions: + stands: + condition: build_year <= period_year AND period_year < build_year + lifetime + ``` + +- A named expression whose `dims:` names a dimension that its expression is not indexed over is refused at load. Take that dimension out of `dims:`. A merge in which no term of a sum is indexed over a dimension that its readers state is refused too ([#898](https://github.com/energy-models/mathspec/pull/898)). +- The program sorts by name the dimensions that the loader works out: those of a named condition, of a named expression without `dims:`, of a piecewise curve and of a comparison. Every expression node lists its dimensions in the same order. So two files that list `dimensions:` in different orders load to the same program, and the typeset indices print in name order ([#911](https://github.com/energy-models/mathspec/pull/911), [#899](https://github.com/energy-models/mathspec/pull/899)). +- `python -m mathspec diff a.yaml b.yaml` compares two specs. `canonical --check` and `canonical --write` are gone ([#874](https://github.com/energy-models/mathspec/pull/874)). +- `to_yaml()` writes a short list or mapping of names on one line ([#871](https://github.com/energy-models/mathspec/pull/871)). + +The Python API: + +- Only `mathspec`, `mathspec.spec`, `mathspec.program` and `mathspec.errors` are public. Every other module now starts with an underscore, so import from the top level: `from mathspec import to_latex` ([#878](https://github.com/energy-models/mathspec/pull/878)). +- A class in `mathspec.spec` ends in `Spec`: `VariableBlock` is `VariableSpec`, and `MaskBlock` is `ConditionSpec`. `typeset_declaration` is `typeset_line` ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)). +- In `mathspec.program`, four names now mean something else. Code that uses the old meaning raises no error, so rename the four reference nodes first, and then drop the `Declaration` suffixes ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)): + + | 0.3.0 | 0.4.0 | + | --- | --- | + | `Parameter`, `Variable`, `NamedExpression`, `NamedMask` (the reference nodes) | `ParameterReference`, `VariableReference`, `ExpressionReference`, `ConditionReference` | + | `ParameterDeclaration`, `VariableDeclaration`, `ExpressionDeclaration`, `MaskDeclaration` | `Parameter`, `Variable`, `NamedExpression`, `NamedCondition` | + | `ConstraintDeclaration` and every other `*Declaration` | `Constraint`, without the suffix | + +- In `mathspec.program`, a true-or-false expression is a condition: `Predicate` is `Condition`, `PredicateOperator` is `ComparisonOperator`, and `TypedPredicate`, `JoinedPredicate` and `TranslatedPredicate` are `TypedCondition`, `JoinedCondition` and `TranslatedCondition`. `CountComparison.predicate` is `.condition`, `Assumption.predicate` is `.holds`, `MaskDeclaration.where` is `NamedCondition.condition`, and `where_children()` is `condition_children()`. `.masks` on `Spec`, `GivenSpec`, `Program` and `GivenTargets` is `.conditions` ([#904](https://github.com/energy-models/mathspec/pull/904), [#907](https://github.com/energy-models/mathspec/pull/907)). +- Every expression node has a `dims` field, which is required and is part of equality. Code that builds a node by hand must pass it. `dims_of` is gone, so read `node.dims` ([#899](https://github.com/energy-models/mathspec/pull/899)). +- A load whose faults all break a rule on dimensions raises one `DimensionError` that lists each fault. In 0.3.0, a fault under a bare `sum(...)` or an `at(...)` raised a `SchemaError` ([#899](https://github.com/energy-models/mathspec/pull/899)). +- The language reference page `declarations/` is now `parameters-variables-constraints/`, so a link to the old page breaks ([#855](https://github.com/energy-models/mathspec/pull/855)). + +The pull requests in this release: + +### Language -- feat(program): each expression node states the dimensions it is read over ([#899](https://github.com/energy-models/mathspec/pull/899)) -- fix(language): two files that declare their dimensions in different orders load to the same program by sorting dimension lists by name ([#911](https://github.com/energy-models/mathspec/pull/911)) - refactor(language)!: a file names a condition under `conditions:` rather than `masks:` ([#907](https://github.com/energy-models/mathspec/pull/907)) -- refactor(api)!: the docs, the error messages and the program classes call a true-or-false `where` expression a condition rather than a predicate ([#904](https://github.com/energy-models/mathspec/pull/904)) - fix(language)!: a named expression whose `dims:` gives a dimension its expression is not indexed over is refused at load ([#898](https://github.com/energy-models/mathspec/pull/898)) -- docs: the compose guide says how to add or remove a term on a merged spec ([#901](https://github.com/energy-models/mathspec/pull/901)) -- fix(composition): a fragment returned by `override` merges as the file it came from does ([#900](https://github.com/energy-models/mathspec/pull/900)) -- docs: the changelog is listed under Reference rather than About ([#895](https://github.com/energy-models/mathspec/pull/895)) -- docs(pypsa): an extendable unit has a capacity to choose exactly where its active flag is set, as in PyPSA ([#886](https://github.com/energy-models/mathspec/pull/886)) +- fix(language): two files that declare their dimensions in different orders load to the same program by sorting dimension lists by name ([#911](https://github.com/energy-models/mathspec/pull/911)) +- fix(language): a patch that changes a dimension is told that a field it leaves out reads as its default ([#857](https://github.com/energy-models/mathspec/pull/857)) + +### Python API + - refactor(api)!: a module outside spec, program and errors has a name that starts with an underscore ([#878](https://github.com/energy-models/mathspec/pull/878)) -- feat(cli)!: `python -m mathspec diff` compares two specs in the canonical form, and `canonical` no longer rewrites or checks a file ([#874](https://github.com/energy-models/mathspec/pull/874)) +- refactor(api)!: a spec class ends in `Spec`, a program class takes its construct's name, and the docs call one named item an entry ([#855](https://github.com/energy-models/mathspec/pull/855)) +- refactor(api)!: the docs, the error messages and the program classes call a true-or-false `where` expression a condition rather than a predicate ([#904](https://github.com/energy-models/mathspec/pull/904)) +- feat(program): each expression node states the dimensions it is read over ([#899](https://github.com/energy-models/mathspec/pull/899)) + +### Writing, comparing and composing specs + - feat(spec)!: a spec written back out puts short lists and mappings of names on one line ([#871](https://github.com/energy-models/mathspec/pull/871)) +- feat(cli)!: `python -m mathspec diff` compares two specs in the canonical form, and `canonical` no longer rewrites or checks a file ([#874](https://github.com/energy-models/mathspec/pull/874)) +- fix(composition): a fragment returned by `override` merges as the file it came from does ([#900](https://github.com/energy-models/mathspec/pull/900)) + +### Typesetting + - feat(typesetting): the legend keys its notation in a table rather than in paragraphs ([#870](https://github.com/energy-models/mathspec/pull/870)) -- refactor(api)!: a spec class ends in `Spec`, a program class takes its construct's name, and the docs call one named item an entry ([#855](https://github.com/energy-models/mathspec/pull/855)) -- fix(language): a patch that changes a dimension is told that a field it leaves out reads as its default ([#857](https://github.com/energy-models/mathspec/pull/857)) + +### Documentation + +- docs: the compose guide says how to add or remove a term on a merged spec ([#901](https://github.com/energy-models/mathspec/pull/901)) +- docs: the changelog is listed under Reference rather than About ([#895](https://github.com/energy-models/mathspec/pull/895)) + +### PyPSA example + +- docs(pypsa): an extendable unit has a capacity to choose exactly where its active flag is set, as in PyPSA ([#886](https://github.com/energy-models/mathspec/pull/886)) ## 0.3.0 (2026-10-15) From 0db2a67963179ff488d3f7adc33177cfcc316a70 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 08:32:46 +0000 Subject: [PATCH 2/4] chore: the 0.4.0 notes say what to change in a file and in Python code Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01B5NaERV1RNkFNcrngYUefA --- CHANGELOG.md | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ff6a3ae..9ed3611f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,11 +12,15 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp ## 0.4.0 (2026-10-21) -This release renames the named conditions of a file from `masks:` to `conditions:`, and renames most classes of the Python API. A file that 0.3.0 loads may not load in 0.4.0: it fails where it has a `masks:` section, or a named expression whose `dims:` names a dimension that its expression is not indexed over. The language version stays `0`. +**This release will not load most files written for 0.3.x.** -A spec file: +This release makes the words for conditions and masks clearer. A file now names its conditions under `conditions:` instead of `masks:`. A condition is a true-or-false expression, such as `capacity > 0`. To mask means what a `where:` does with a condition: it keeps the coordinates where the condition is true, and drops the others. An assumption's `holds:` reads a condition too, but it only checks the data and masks nothing. So a named condition is not always a mask, and the section is now called `conditions:`. -- A file names its conditions under `conditions:`, and each entry writes its condition under `condition:` instead of `where:`. Another file reads them under `given: conditions:`. A file that still writes `masks:` is refused, and the error names the valid keys ([#907](https://github.com/energy-models/mathspec/pull/907)). +This release also makes most modules of mathspec private, so the public API is smaller. The language version stays `0`. + +### What to change in a spec file + +- Rename `masks:` to `conditions:`, and `given: masks:` to `given: conditions:`. Inside an entry, write the condition under `condition:` instead of `where:`. The loader refuses a file that still writes `masks:`, and the error lists the keys it accepts ([#907](https://github.com/energy-models/mathspec/pull/907)). ```yaml conditions: @@ -24,27 +28,34 @@ A spec file: condition: build_year <= period_year AND period_year < build_year + lifetime ``` -- A named expression whose `dims:` names a dimension that its expression is not indexed over is refused at load. Take that dimension out of `dims:`. A merge in which no term of a sum is indexed over a dimension that its readers state is refused too ([#898](https://github.com/energy-models/mathspec/pull/898)). -- The program sorts by name the dimensions that the loader works out: those of a named condition, of a named expression without `dims:`, of a piecewise curve and of a comparison. Every expression node lists its dimensions in the same order. So two files that list `dimensions:` in different orders load to the same program, and the typeset indices print in name order ([#911](https://github.com/energy-models/mathspec/pull/911), [#899](https://github.com/energy-models/mathspec/pull/899)). -- `python -m mathspec diff a.yaml b.yaml` compares two specs. `canonical --check` and `canonical --write` are gone ([#874](https://github.com/energy-models/mathspec/pull/874)). -- `to_yaml()` writes a short list or mapping of names on one line ([#871](https://github.com/energy-models/mathspec/pull/871)). +- Remove a dimension from a named expression's `dims:` when its expression is not indexed over that dimension. The loader now refuses such an entry. In 0.3.x it loaded, and every reader saw the same value at each coordinate of that dimension. For the same reason, a merge is refused when no term of a sum is indexed over a dimension that the sum's readers name ([#898](https://github.com/energy-models/mathspec/pull/898)). +- Expect index lists in name order. The loader sorts by name the dimensions it works out for an entry, such as a named condition or a named expression without `dims:`. Every expression node lists its dimensions in the same order. So two files that list `dimensions:` in different orders load to the same program, and the typeset index can read `g, t` where it read `t, g` before ([#911](https://github.com/energy-models/mathspec/pull/911), [#899](https://github.com/energy-models/mathspec/pull/899)). +- Compare two specs with `python -m mathspec diff a.yaml b.yaml`. `canonical --check` and `canonical --write` are gone ([#874](https://github.com/energy-models/mathspec/pull/874)). +- Expect `to_yaml()` to write a short list or mapping of names on one line ([#871](https://github.com/energy-models/mathspec/pull/871)). -The Python API: +### What to change in Python code -- Only `mathspec`, `mathspec.spec`, `mathspec.program` and `mathspec.errors` are public. Every other module now starts with an underscore, so import from the top level: `from mathspec import to_latex` ([#878](https://github.com/energy-models/mathspec/pull/878)). -- A class in `mathspec.spec` ends in `Spec`: `VariableBlock` is `VariableSpec`, and `MaskBlock` is `ConditionSpec`. `typeset_declaration` is `typeset_line` ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)). -- In `mathspec.program`, four names now mean something else. Code that uses the old meaning raises no error, so rename the four reference nodes first, and then drop the `Declaration` suffixes ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)): +- Import only from `mathspec`, `mathspec.spec`, `mathspec.program` and `mathspec.errors`. The name of every other module now starts with an underscore. For example, write `from mathspec import to_latex` ([#878](https://github.com/energy-models/mathspec/pull/878)). +- In `mathspec.spec`, every class name ends in `Spec`: `VariableBlock` is now `VariableSpec`, and `MaskBlock` is now `ConditionSpec`. `typeset_declaration` is now `typeset_line` ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)). +- In `mathspec.program`, rename with care: four names now mean something else. Old code that uses them raises no error, because each name still exists. So rename the reference nodes first, and only then drop the `Declaration` suffixes ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)): - | 0.3.0 | 0.4.0 | + | 0.3.x | 0.4.0 | | --- | --- | | `Parameter`, `Variable`, `NamedExpression`, `NamedMask` (the reference nodes) | `ParameterReference`, `VariableReference`, `ExpressionReference`, `ConditionReference` | | `ParameterDeclaration`, `VariableDeclaration`, `ExpressionDeclaration`, `MaskDeclaration` | `Parameter`, `Variable`, `NamedExpression`, `NamedCondition` | | `ConstraintDeclaration` and every other `*Declaration` | `Constraint`, without the suffix | -- In `mathspec.program`, a true-or-false expression is a condition: `Predicate` is `Condition`, `PredicateOperator` is `ComparisonOperator`, and `TypedPredicate`, `JoinedPredicate` and `TranslatedPredicate` are `TypedCondition`, `JoinedCondition` and `TranslatedCondition`. `CountComparison.predicate` is `.condition`, `Assumption.predicate` is `.holds`, `MaskDeclaration.where` is `NamedCondition.condition`, and `where_children()` is `condition_children()`. `.masks` on `Spec`, `GivenSpec`, `Program` and `GivenTargets` is `.conditions` ([#904](https://github.com/energy-models/mathspec/pull/904), [#907](https://github.com/energy-models/mathspec/pull/907)). -- Every expression node has a `dims` field, which is required and is part of equality. Code that builds a node by hand must pass it. `dims_of` is gone, so read `node.dims` ([#899](https://github.com/energy-models/mathspec/pull/899)). -- A load whose faults all break a rule on dimensions raises one `DimensionError` that lists each fault. In 0.3.0, a fault under a bare `sum(...)` or an `at(...)` raised a `SchemaError` ([#899](https://github.com/energy-models/mathspec/pull/899)). -- The language reference page `declarations/` is now `parameters-variables-constraints/`, so a link to the old page breaks ([#855](https://github.com/energy-models/mathspec/pull/855)). +- In `mathspec.program`, replace "predicate" with "condition". `Predicate` is now `Condition`, and `PredicateOperator` is now `ComparisonOperator`. `TypedPredicate`, `JoinedPredicate` and `TranslatedPredicate` are now `TypedCondition`, `JoinedCondition` and `TranslatedCondition`. Four attributes and methods change too: + - `CountComparison.predicate` is now `.condition`. + - `Assumption.predicate` is now `.holds`. + - `MaskDeclaration.where` is now `NamedCondition.condition`. + - `where_children()` is now `condition_children()`. + + `.masks` on `Spec`, `GivenSpec`, `Program` and `GivenTargets` is now `.conditions` ([#904](https://github.com/energy-models/mathspec/pull/904), [#907](https://github.com/energy-models/mathspec/pull/907)). +- Pass `dims` when you build an expression node by hand. Every node now has a required `dims` field, and two nodes are equal only when their `dims` are equal. `dims_of` is gone, so read `node.dims` instead ([#899](https://github.com/energy-models/mathspec/pull/899)). +- Catch `DimensionError` for a load whose faults all break a rule on dimensions. The error lists every fault. In 0.3.x, a fault inside a bare `sum(...)` or an `at(...)` raised `SchemaError` ([#899](https://github.com/energy-models/mathspec/pull/899)). + +The language reference page `declarations/` is now `parameters-variables-constraints/`, so update any link to it ([#855](https://github.com/energy-models/mathspec/pull/855)). The pull requests in this release: From a2bcd8bd5e916c68fb2c2256f66ecfd59c023530 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 08:34:10 +0000 Subject: [PATCH 3/4] chore: the 0.4.0 pull request lines read as plain sentences Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01B5NaERV1RNkFNcrngYUefA --- CHANGELOG.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ed3611f..254ced80 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -61,36 +61,36 @@ The pull requests in this release: ### Language -- refactor(language)!: a file names a condition under `conditions:` rather than `masks:` ([#907](https://github.com/energy-models/mathspec/pull/907)) -- fix(language)!: a named expression whose `dims:` gives a dimension its expression is not indexed over is refused at load ([#898](https://github.com/energy-models/mathspec/pull/898)) -- fix(language): two files that declare their dimensions in different orders load to the same program by sorting dimension lists by name ([#911](https://github.com/energy-models/mathspec/pull/911)) -- fix(language): a patch that changes a dimension is told that a field it leaves out reads as its default ([#857](https://github.com/energy-models/mathspec/pull/857)) +- refactor(language)!: a file names its conditions under `conditions:` instead of `masks:` ([#907](https://github.com/energy-models/mathspec/pull/907)) +- fix(language)!: the loader refuses a named expression whose `dims:` names a dimension that its expression is not indexed over ([#898](https://github.com/energy-models/mathspec/pull/898)) +- fix(language): two files that list their dimensions in different orders load to the same program, because the loader sorts dimension lists by name ([#911](https://github.com/energy-models/mathspec/pull/911)) +- fix(language): when a patch changes a dimension, the error says that a field the patch leaves out takes its default value ([#857](https://github.com/energy-models/mathspec/pull/857)) ### Python API -- refactor(api)!: a module outside spec, program and errors has a name that starts with an underscore ([#878](https://github.com/energy-models/mathspec/pull/878)) -- refactor(api)!: a spec class ends in `Spec`, a program class takes its construct's name, and the docs call one named item an entry ([#855](https://github.com/energy-models/mathspec/pull/855)) -- refactor(api)!: the docs, the error messages and the program classes call a true-or-false `where` expression a condition rather than a predicate ([#904](https://github.com/energy-models/mathspec/pull/904)) -- feat(program): each expression node states the dimensions it is read over ([#899](https://github.com/energy-models/mathspec/pull/899)) +- refactor(api)!: every module except `spec`, `program` and `errors` is private, and its name starts with an underscore ([#878](https://github.com/energy-models/mathspec/pull/878)) +- refactor(api)!: the name of a class in `mathspec.spec` ends in `Spec`, a class in `mathspec.program` takes the name of what it declares, and the docs call one named item an entry ([#855](https://github.com/energy-models/mathspec/pull/855)) +- refactor(api)!: the docs, the error messages and the classes in `mathspec.program` call a true-or-false expression a condition instead of a predicate ([#904](https://github.com/energy-models/mathspec/pull/904)) +- feat(program)!: each expression node in the program lists the dimensions it is indexed over ([#899](https://github.com/energy-models/mathspec/pull/899)) ### Writing, comparing and composing specs -- feat(spec)!: a spec written back out puts short lists and mappings of names on one line ([#871](https://github.com/energy-models/mathspec/pull/871)) -- feat(cli)!: `python -m mathspec diff` compares two specs in the canonical form, and `canonical` no longer rewrites or checks a file ([#874](https://github.com/energy-models/mathspec/pull/874)) -- fix(composition): a fragment returned by `override` merges as the file it came from does ([#900](https://github.com/energy-models/mathspec/pull/900)) +- feat(spec)!: `to_yaml()` writes a short list or mapping of names on one line ([#871](https://github.com/energy-models/mathspec/pull/871)) +- feat(cli)!: `python -m mathspec diff` compares two specs in their canonical form, and `canonical` no longer checks or rewrites a file ([#874](https://github.com/energy-models/mathspec/pull/874)) +- fix(composition): a fragment that `override` returns merges in the same way as the file it came from ([#900](https://github.com/energy-models/mathspec/pull/900)) ### Typesetting -- feat(typesetting): the legend keys its notation in a table rather than in paragraphs ([#870](https://github.com/energy-models/mathspec/pull/870)) +- feat(typesetting): the legend lists its notation in a table instead of in paragraphs ([#870](https://github.com/energy-models/mathspec/pull/870)) ### Documentation -- docs: the compose guide says how to add or remove a term on a merged spec ([#901](https://github.com/energy-models/mathspec/pull/901)) -- docs: the changelog is listed under Reference rather than About ([#895](https://github.com/energy-models/mathspec/pull/895)) +- docs: the composition guide shows how to add a term to a merged spec, or remove one ([#901](https://github.com/energy-models/mathspec/pull/901)) +- docs: the changelog is now under Reference instead of About ([#895](https://github.com/energy-models/mathspec/pull/895)) ### PyPSA example -- docs(pypsa): an extendable unit has a capacity to choose exactly where its active flag is set, as in PyPSA ([#886](https://github.com/energy-models/mathspec/pull/886)) +- docs(pypsa): an extendable unit has a capacity to choose only where its active flag is set, as in PyPSA ([#886](https://github.com/energy-models/mathspec/pull/886)) ## 0.3.0 (2026-10-15) From 12bc26e76efa5eed43d5c95c3997de3c258a0cec Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 13:32:33 +0000 Subject: [PATCH 4/4] chore: each 0.4.0 migration bullet says only what to change Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015vU4ni6oQbTr8PM7EaYqDu --- CHANGELOG.md | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65a2e3b0..426e3dec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ This release also makes most modules of mathspec private, so the public API is s ### What to change in a spec file -- Rename `masks:` to `conditions:`, and `given: masks:` to `given: conditions:`. Inside an entry, write the condition under `condition:` instead of `where:`. The loader refuses a file that still writes `masks:`, and the error lists the keys it accepts ([#907](https://github.com/energy-models/mathspec/pull/907)). +- Rename `masks:` to `conditions:`, also under `given:`, and `where:` to `condition:` inside each entry ([#907](https://github.com/energy-models/mathspec/pull/907)). ```yaml conditions: @@ -28,17 +28,17 @@ This release also makes most modules of mathspec private, so the public API is s condition: build_year <= period_year AND period_year < build_year + lifetime ``` -- Remove a dimension from a named expression's `dims:` when its expression is not indexed over that dimension. The loader now refuses such an entry. In 0.3.x it loaded, and every reader saw the same value at each coordinate of that dimension. For the same reason, a merge is refused when no term of a sum is indexed over a dimension that the sum's readers name ([#898](https://github.com/energy-models/mathspec/pull/898)). -- Expect index lists in name order. The loader sorts by name the dimensions it works out for an entry, such as a named condition or a named expression without `dims:`. Every expression node lists its dimensions in the same order. So two files that list `dimensions:` in different orders load to the same program, and the typeset index can read `g, t` where it read `t, g` before ([#911](https://github.com/energy-models/mathspec/pull/911), [#899](https://github.com/energy-models/mathspec/pull/899)). -- Rewrite a condition that uses `<`, `<=`, `>` or `>=` on a `str` or `bool` value. The loader now refuses it, and the error names the rewrite. In 0.3.x, `generator < 'b9'` compared the labels byte by byte, so `'b10'` came before `'b9'` whatever the order of the dimension. Compare a `str` with `==` or `!=`. To select by place along a dimension declared `ordered: true`, use `position(generator) < 3`. Test a `bool` parameter by its bare name, `flag` or `not flag` ([#931](https://github.com/energy-models/mathspec/pull/931)). -- Compare two specs with `python -m mathspec diff a.yaml b.yaml`. `canonical --check` and `canonical --write` are gone ([#874](https://github.com/energy-models/mathspec/pull/874)). +- Remove from a named expression's `dims:` each dimension that its expression is not indexed over ([#898](https://github.com/energy-models/mathspec/pull/898)). +- Replace `<`, `<=`, `>` or `>=` on a `str` or `bool` value with `==` or `!=`, with `position()` on an ordered dimension, or with the bare name of a `bool` parameter ([#931](https://github.com/energy-models/mathspec/pull/931)). +- Replace `canonical --check` and `canonical --write` with `python -m mathspec diff a.yaml b.yaml` ([#874](https://github.com/energy-models/mathspec/pull/874)). +- Expect dimension lists in name order, also in typeset output ([#911](https://github.com/energy-models/mathspec/pull/911), [#899](https://github.com/energy-models/mathspec/pull/899)). - Expect `to_yaml()` to write a short list or mapping of names on one line ([#871](https://github.com/energy-models/mathspec/pull/871)). ### What to change in Python code -- Import only from `mathspec`, `mathspec.spec`, `mathspec.program` and `mathspec.errors`. The name of every other module now starts with an underscore. For example, write `from mathspec import to_latex` ([#878](https://github.com/energy-models/mathspec/pull/878)). -- In `mathspec.spec`, every class name ends in `Spec`: `VariableBlock` is now `VariableSpec`, and `MaskBlock` is now `ConditionSpec`. `typeset_declaration` is now `typeset_line` ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)). -- In `mathspec.program`, rename with care: four names now mean something else. Old code that uses them raises no error, because each name still exists. So rename the reference nodes first, and only then drop the `Declaration` suffixes ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)): +- Import only from `mathspec`, `mathspec.spec`, `mathspec.program` and `mathspec.errors` ([#878](https://github.com/energy-models/mathspec/pull/878)). +- In `mathspec.spec`, rename `VariableBlock` to `VariableSpec`, `MaskBlock` to `ConditionSpec`, and every other class in the same way. Rename `typeset_declaration` to `typeset_line` ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)). +- In `mathspec.program`, rename the reference nodes before you remove the `Declaration` suffixes. Four names now mean something else, and old code that uses them raises no error ([#855](https://github.com/energy-models/mathspec/pull/855), [#907](https://github.com/energy-models/mathspec/pull/907)): | 0.3.x | 0.4.0 | | --- | --- | @@ -46,17 +46,15 @@ This release also makes most modules of mathspec private, so the public API is s | `ParameterDeclaration`, `VariableDeclaration`, `ExpressionDeclaration`, `MaskDeclaration` | `Parameter`, `Variable`, `NamedExpression`, `NamedCondition` | | `ConstraintDeclaration` and every other `*Declaration` | `Constraint`, without the suffix | -- In `mathspec.program`, replace "predicate" with "condition". `Predicate` is now `Condition`, and `PredicateOperator` is now `ComparisonOperator`. `TypedPredicate`, `JoinedPredicate` and `TranslatedPredicate` are now `TypedCondition`, `JoinedCondition` and `TranslatedCondition`. Four attributes and methods change too: - - `CountComparison.predicate` is now `.condition`. - - `Assumption.predicate` is now `.holds`. - - `MaskDeclaration.where` is now `NamedCondition.condition`. - - `where_children()` is now `condition_children()`. - - `.masks` on `Spec`, `GivenSpec`, `Program` and `GivenTargets` is now `.conditions` ([#904](https://github.com/energy-models/mathspec/pull/904), [#907](https://github.com/energy-models/mathspec/pull/907)). -- Pass `dims` when you build an expression node by hand. Every node now has a required `dims` field, and two nodes are equal only when their `dims` are equal. `dims_of` is gone, so read `node.dims` instead ([#899](https://github.com/energy-models/mathspec/pull/899)). -- Catch `DimensionError` for a load whose faults all break a rule on dimensions. The error lists every fault. In 0.3.x, a fault inside a bare `sum(...)` or an `at(...)` raised `SchemaError` ([#899](https://github.com/energy-models/mathspec/pull/899)). - -The language reference page `declarations/` is now `parameters-variables-constraints/`, so update any link to it ([#855](https://github.com/energy-models/mathspec/pull/855)). +- In `mathspec.program`, replace `Predicate` with `Condition` in every class name, but rename `PredicateOperator` to `ComparisonOperator`. Also rename ([#904](https://github.com/energy-models/mathspec/pull/904), [#907](https://github.com/energy-models/mathspec/pull/907)): + - `CountComparison.predicate` to `.condition` + - `Assumption.predicate` to `.holds` + - `MaskDeclaration.where` to `NamedCondition.condition` + - `where_children()` to `condition_children()` + - `.masks` to `.conditions` on `Spec`, `GivenSpec`, `Program` and `GivenTargets` +- Pass `dims` to an expression node that you build by hand, and read `node.dims` instead of `dims_of` ([#899](https://github.com/energy-models/mathspec/pull/899)). +- Catch `DimensionError` instead of `SchemaError` for a dimension fault inside `sum(...)` or `at(...)` ([#899](https://github.com/energy-models/mathspec/pull/899)). +- Change links to the reference page `declarations/` to `parameters-variables-constraints/` ([#855](https://github.com/energy-models/mathspec/pull/855)). The pull requests in this release: