Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
name: release

# Publishes ymf to TestPyPI (pre-release tags) or PyPI (final tags) with Trusted
# Publishing: GitHub mints a short-lived OIDC token per job, so there is no API
# token and no secret anywhere. It does nothing until all of these are true:
# 1. the project and this workflow are registered as a Trusted Publisher on
# test.pypi.org and pypi.org (RELEASING.md, steps 1-2: cekees's to do),
# 2. the GitHub environments `testpypi` and `pypi` exist (RELEASING.md, step 3),
# 3. a matching tag is pushed. Nothing here runs on a branch or a pull request.
# Tags: `v0.3.0rc1`, `v0.3.0a1`, `v0.3.0b2` go to TestPyPI; `v0.3.0` goes to PyPI.
# setuptools_scm turns the tag into the version, and the build job refuses to go
# on when the two disagree, so a mistyped tag cannot publish the wrong version.
on:
push:
tags:
- "v[0-9]+.[0-9]+.[0-9]+"
- "v[0-9]+.[0-9]+.[0-9]+a[0-9]+"
- "v[0-9]+.[0-9]+.[0-9]+b[0-9]+"
- "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"

permissions:
contents: read

jobs:
build:
runs-on: ubuntu-latest
outputs:
prerelease: ${{ steps.version.outputs.prerelease }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0 # setuptools_scm needs the tags
persist-credentials: false

- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"

- name: Build, check and smoke-test the distributions
run: |
python -m pip install --upgrade pip build twine
tools/check_dist.sh "$RUNNER_TEMP/check"
mkdir dist
cp "$RUNNER_TEMP"/check/dist/* dist/

- name: The tag and the built version agree
id: version
run: |
python - <<'PY'
import glob, os, re
from packaging.version import Version
tag = os.environ["GITHUB_REF_NAME"]
wheel = glob.glob("dist/ymf-*.whl")
assert len(wheel) == 1, wheel
built = Version(re.match(r"ymf-([^-]+)-", os.path.basename(wheel[0])).group(1))
assert tag == "v" + str(built), f"tag {tag} builds version {built}"
assert not built.local and not built.dev, f"not a release version: {built}"
with open(os.environ["GITHUB_OUTPUT"], "a") as f:
f.write(f"prerelease={'true' if built.is_prerelease else 'false'}\n")
print("version", built, "prerelease", built.is_prerelease)
PY

- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: dist
path: dist/
if-no-files-found: error

publish-testpypi:
needs: build
if: needs.build.outputs.prerelease == 'true'
runs-on: ubuntu-latest
environment:
name: testpypi # not created by this PR: RELEASING.md step 3
url: https://test.pypi.org/p/ymf
permissions:
id-token: write # the OIDC token Trusted Publishing exchanges
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: dist
path: dist/
- uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
with:
repository-url: https://test.pypi.org/legacy/

publish-pypi:
needs: build
if: needs.build.outputs.prerelease == 'false'
runs-on: ubuntu-latest
environment:
name: pypi # not created by this PR: RELEASING.md step 3
url: https://pypi.org/p/ymf
permissions:
id-token: write
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: dist
path: dist/
- uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
7 changes: 7 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# What the sdist ships: setuptools_scm adds every git-tracked file (source,
# tests with their fixtures, examples, docs, README, LICENSE), so this only
# prunes. Nothing generated or local may ride along.
prune .github
global-exclude *.pyc __pycache__ *.log .coverage .DS_Store
# What ymf_run and the examples write beside themselves
global-exclude examples/*.archive.ymf
68 changes: 68 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Releasing ymf

A release is a git tag. `.github/workflows/release.yml` builds the sdist and
wheel from the tagged commit, checks them (`tools/check_dist.sh`: size,
contents, `twine check`, a fresh-venv install that runs), and publishes with
PyPI Trusted Publishing (OIDC: no API token, no secret). The version is
whatever `setuptools_scm` derives from the tag; the workflow refuses a tag that
does not equal `v<built version>`.

| tag | goes to |
|---|---|
| `v0.3.0rc1`, `v0.3.0a1`, `v0.3.0b1` | TestPyPI (environment `testpypi`) |
| `v0.3.0` | PyPI (environment `pypi`) |

The tag `v0.2.0` already exists from before this workflow; it is not re-pushed
and nothing publishes it. Pick the first published version knowing that.

## What the maintainer does by hand (once)

Name check, 2026-11-16: `ymf` returns 404 on pypi.org and test.pypi.org (JSON
API and simple index), so it is free today. PyPI can still refuse a name that
is confusingly close to an existing project, and a project registered
meanwhile wins: do step 1 soon.

1. **TestPyPI**: log in at test.pypi.org (a separate account from PyPI), then
*Your account → Publishing → Add a new pending publisher*: project name
`ymf`, owner `proteustoolkit` (or `cekees` to rehearse from the fork),
repository `ymf`, workflow `release.yml`, environment `testpypi`.
2. **PyPI**: the same at pypi.org, environment `pypi`. A *pending* publisher
creates the project on the first upload, so nothing is uploaded to claim
the name.
3. **GitHub environments** on the repository that will run the workflow:
Settings → Environments → create `testpypi` and `pypi`. For `pypi`, add
yourself as a required reviewer so a final tag waits for a click; leave
`testpypi` unprotected. No secrets are added to either.
4. **Push a pre-release tag** from a commit on `main` whose CI is green:

```bash
git tag -a v0.3.0rc1 -m "ymf 0.3.0rc1" && git push origin v0.3.0rc1
```

Then try it the way a user would:

```bash
python -m venv /tmp/t && /tmp/t/bin/pip install --index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ "ymf[frontend]==0.3.0rc1"
```

(the extra index supplies pyyaml and the extras' dependencies, which are
not on TestPyPI). A TestPyPI file name can never be reused: a mistake is
fixed by `rc2`, not by re-uploading.
5. When rc installs and runs, tag `v0.3.0` the same way for PyPI.

To rehearse the build without publishing, run `tools/check_dist.sh` (set
`SETUPTOOLS_SCM_PRETEND_VERSION=0.3.0rc1` off a tag).

## Pinning from proteus CI (not done here)

proteus's workflows install ymf from `git+https://github.com/proteustoolkit/ymf.git@main`,
a moving branch, in the environment files and in the comment block of
`.github/workflows/sdist.yml`. After a tagged release exists, the proteus-side
change is: replace `@main` with the tag (`@v0.3.0`, or `ymf==0.3.0` from PyPI
once it is there; before that, TestPyPI needs the extra-index form above and
is not worth using in CI), in every environment file and workflow that names
it, and update the comment. The pin moves by a one-line PR per ymf release; a
ymf change that proteus needs merges in ymf, is tagged, and then the proteus PR
bumps the pin. That is a proteus change: it needs its own PR and is not part of
this one.
10 changes: 10 additions & 0 deletions docs/changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,16 @@ rediscover why a thing is the way it is. Open gaps are in

## 2026-11

- **2026-11-16: C42 round 4, the spaces vocabulary (C8's choices).** A `finite_element` entry stated only family and
order; C8 (proteus FemTools rounds 1-5) added the basis, the node set, the Bernstein operator and the geometry order as
choices a run depends on. `ymf.spaces`: `basis` (`lagrange`, `bernstein`, `monomial`), `nodes` (`gll`, `equispaced`),
`bernstein_operator`, and `geometry_order` beside the spaces, each checked on load (nodes only with a Lagrange basis,
the Bernstein operator only with a Bernstein basis, the vector families RT/BDM/RTF/N1curl take neither, lowest orders
RT0, BDM1, N1curl0, geometry order >= 1); `resolve` fills the defaults proteus uses (`lagrange`, `gll`, exact
Bernstein conversion, affine geometry), so two spellings of one space resolve equal. `implemented_in_proteus` records
what FemTools has (information, never a refusal). Existing specs are unchanged. proteus CI installs ymf from
`proteustoolkit/ymf@main`, so proteus sees this only after the ymf merge.

- **2026-11-08: C42 round 3, the words a dispatcher maps (C5 decisions
16, 18-21 of 2026-11-06).** proteus's DispatchTable coined the labels it
matched on; they are `ymf.vocabulary` now, stated by the spec, checked on
Expand Down
7 changes: 6 additions & 1 deletion docs/problem-specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,12 @@ usually `finite_element` and `from_weak_form` (a weak form's label, which
may be omitted when the document has only one — see
[Branching](#branching-one-problem-several-solution-paths)). `finite_element` takes
`fields`, or `velocity` and `pressure` for mixed problems, each as
`{family: CG|DG|RT|BDM|RTF|N1curl, order: n}`. The `solver` block takes
`{family: CG|DG|RT|BDM|RTF|N1curl, order: n}`, and, where they apply, `basis`
(`lagrange | bernstein | monomial`), `nodes` (`gll | equispaced`, Lagrange basis) and
`bernstein_operator` (Bernstein basis); `finite_element` also takes `geometry_order` (the degree of
the mesh map, 1 = affine). The words, their defaults and the order numbering of the vector
families (RT0 is `order: 0`, BDM1 is `order: 1`) are in `ymf.spaces`, which checks them on load.
The `solver` block takes
`type` (`linear | nonlinear | time_marching | saddle_point`),
`linear_solver` (`direct | iterative`, or a package: `petsc | mumps | umfpack
| superlu`), `petsc_options`,
Expand Down
37 changes: 37 additions & 0 deletions examples/poisson_spaces.ymf
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# ============================================================
# YMF Example: Poisson on the unit square, the space stated in full
#
# Extends poisson.ymf with discretizations that say which space they use
# beyond its family and order (ymf.spaces): the basis, where a Lagrange
# basis puts its nodes, how Bernstein data is imposed, the degree of the
# mesh map, and the mixed form's H(div) pair. Every default is the one
# proteus's FemTools uses, so P3_gll is `{family: CG, order: 3}` written out.
#
# python -c "import ymf.spaces as s; print(s.resolve({'family': 'CG', 'order': 3}))"
# ============================================================

extends: poisson.ymf

solution_paths:
discretizations:
- name: "P3_gll"
provenance: human_specified
finite_element:
fields: {family: CG, order: 3, basis: lagrange, nodes: gll}
geometry_order: 1
mesh: {cells: [4, 8, 16]}
solver: {type: linear, linear_solver: petsc, tolerance: 1.0e-12}

- name: "P4_equispaced" # for comparison: the Lebesgue constant grows from p = 4
provenance: human_specified
finite_element:
fields: {family: CG, order: 4, basis: lagrange, nodes: equispaced}
mesh: {cells: [4, 8]}
solver: {type: linear, linear_solver: petsc, tolerance: 1.0e-12}

- name: "P3_bernstein_exact" # bounds-preserving basis, data converted exactly (order p + 1)
provenance: human_specified
finite_element:
fields: {family: CG, order: 3, basis: bernstein, bernstein_operator: false}
mesh: {cells: [4, 8, 16]}
solver: {type: linear, linear_solver: petsc, tolerance: 1.0e-12}
2 changes: 1 addition & 1 deletion examples/validate_spec.py
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ def describe(path: Path) -> bool:
if str(disc.get("from_weak_form")) in (wf["label"], str(index)):
fe = disc.get("finite_element", {})
spaces = ", ".join("%s %s%s" % (k, v["family"], v["order"])
for k, v in fe.items())
for k, v in fe.items() if isinstance(v, dict))
print(" discretization %r: %s; %s solver"
% (disc["name"], spaces or "-", disc["solver"].get("type", "-")))
for exact in paths["analytical"]:
Expand Down
43 changes: 41 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
[build-system]
requires = ["setuptools>=68", "wheel", "setuptools_scm>=8"]
# setuptools>=77 for the SPDX `license` expression and `license-files` (PEP 639).
requires = ["setuptools>=77", "setuptools_scm>=8"]
build-backend = "setuptools.build_meta"

[project]
Expand All @@ -8,8 +9,27 @@ dynamic = ["version"]
description = "YAML Modeling Format for computational physics — problem specification, VVUQ, and multi-backend dispatch."
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
# Where the version comes from: setuptools_scm, from the git tag (`v0.3.0`,
# `v0.3.0rc1`). A tagged commit builds exactly the tag; any other commit builds
# a `.devN+gHASH` version, which PyPI and TestPyPI refuse (release.yml checks
# that the tag and the built version agree before it uploads).
license = "MIT"
license-files = ["LICENSE"]
authors = [{ name = "cekees" }]
keywords = ["yaml", "simulation", "computational-physics", "pde", "verification", "uncertainty-quantification"]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Science/Research",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",
"Topic :: Scientific/Engineering",
"Topic :: Scientific/Engineering :: Physics",
]
# Core runtime dependency, kept to exactly one on purpose: a solver that
# writes YMF archives (see ymf.archive) must not inherit the validation
# stack. Everything heavier sits behind the extras below, which only the
Expand All @@ -18,6 +38,13 @@ dependencies = [
"pyyaml>=6.0",
]

[project.urls]
Homepage = "https://github.com/proteustoolkit/ymf"
Documentation = "https://github.com/proteustoolkit/ymf/tree/main/docs"
Source = "https://github.com/proteustoolkit/ymf"
Issues = "https://github.com/proteustoolkit/ymf/issues"
Changelog = "https://github.com/proteustoolkit/ymf/blob/main/docs/changes.md"

[project.scripts]
# Converts a .ymf archive to the .xmf a viewer reads. In the core, so it
# works without the ymf[spec] validation stack.
Expand All @@ -39,6 +66,18 @@ frontend = ["strictyaml>=1.7", "pint>=0.23", "sympy>=1.12"]
# What examples/write_archive.py and read_archive.py need to make and read
# the HDF5 side of an archive. A solver brings its own.
examples = ["numpy", "h5py"]
# Tests: what `pytest tests` needs so that nothing skips (CI's `dev` leg).
# There is no `docs` extra on purpose: docs/ is plain markdown with no build
# step, so there is nothing for one to install.
test = [
"pytest>=7.0",
"pytest-cov",
"strictyaml>=1.7",
"pint>=0.23",
"numpy",
"h5py",
"sympy>=1.12",
]
dev = [
"pytest>=7.0",
"pytest-cov",
Expand Down
20 changes: 17 additions & 3 deletions src/ymf/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,25 @@
}
)

# A space: family and order, and where they apply the basis, the nodes of a
# Lagrange basis and the Bernstein operator (ymf.spaces, checked on load).
SpaceDef = Map(
{
"family": FEFamilyEnum,
"order": Int(),
Optional("basis"): Str(),
Optional("nodes"): Str(),
Optional("bernstein_operator"): Bool(),
}
)

FiniteElementDef = Map(
{
Optional("velocity"): Map({"family": FEFamilyEnum, "order": Int()}),
Optional("pressure"): Map({"family": FEFamilyEnum, "order": Int()}),
Optional("fields"): Map({"family": FEFamilyEnum, "order": Int()}),
Optional("velocity"): SpaceDef,
Optional("pressure"): SpaceDef,
Optional("fields"): SpaceDef,
# the polynomial degree of the mesh map: 1 = affine, 2 = quadratic ... (ymf.spaces)
Optional("geometry_order"): Int(),
}
)

Expand Down
Loading
Loading