Skip to content

Release v0.4.0 — RANS turbulence, multigrid, checkpoint/restart - #244

Merged
shaia merged 12 commits into
masterfrom
release/v0.4.0
Oct 4, 2026
Merged

shaia merged 12 commits into
masterfrom
release/v0.4.0

Conversation

@shaia

@shaia shaia commented Oct 3, 2026

Copy link
Copy Markdown
Owner

Summary

Cuts v0.4.0, the turbulence milestone. Merging this PR changes VERSION on master, which triggers version-release.yml: 5-platform build, physics validation, Doxygen, then the v0.4.0 tag and GitHub Release.

44 PRs (#200–#243) have landed since v0.3.0. They add RANS k-ε / Spalart-Allmaras with wall functions (validated against channel DNS), geometric multigrid and GMRES(m), implicit viscous stepping, upwind convection, checkpoint/restart and .cfdnn inference. The Poisson configuration API changed incompatibly.

Commits

Commit Change
fdf3f4e Rewrite the [Unreleased] CHANGELOG as 0.4.0 release notes. It was written one PR at a time, so it described steps between unreleased states, e.g. checkpoint format versions 3→8 and a "breaking" wall-law signature, for features a 0.3.0 user never had. Those are folded into their features. Adds a summary, an Upgrading from 0.3.0 list, entries for four PRs that had none (#203, #219, #222, #228), and replaces the deleted POISSON_SOLVER_* names
607c0e7 Fix examples/performance_comparison.c. It never called grid_initialize_uniform(), so every solver ran on a grid whose spacing was zero, and it ignored init and step statuses. The projection rows timed solves failing at max_iterations (the run took over 300 s), and *_optimized rows printed inf without AVX2. Found by the release gate's example run
a408d32 Fix the README example and stale doc names. The README example now compiles (it lacked <stdio.h> and cfd/core/cfd_init.h). cfd_cleanup() → cfd_finalize() in three docs. The solver table no longer claims NEON Navier-Stokes kernels and now lists explicit_euler_gpu. Fixes three broken links
1461235 Release v0.4.0. Bumps the version in VERSION, both project() lines in lib/CMakeLists.txt, cfd_version.h, Doxyfile, the README badge and docs/index.md. Adds the ## [0.4.0] heading and compare links in the CHANGELOG, and updates the ROADMAP current state and milestones
0eaf935 Stamp .cfdnn files from the Python exporter as 0.4.0. It still recorded 0.3.0, a release that never had the format
6c3e5a6 Describe performance_comparison as it now runs in docs/guides/examples.md, and fix an index anchor

The only library source changes are the version files and one header doc comment (params.omega → params.sor.omega).

Testing

Before merging

Not in this PR (follow-ups)

  • API reference: docs/reference/api-reference.md is missing 215 of 287 exported functions, and still names cfd_get_version(), write_field_to_csv() and grid_t, which don't exist.
  • Other docs: docs/reference/solvers.md has no RK2/RK4 section, and three examples are missing from examples.md.
  • Wiki: last updated for v0.2.0 (step 8 of the release, after the merge).
  • Library gaps found by the example run:
    • solver_init accepts a grid that was never initialized.
    • A Poisson solve that hits max_iterations leaves cfd_get_last_error() as (null).

🤖 Generated with Claude Code

shaia added 6 commits October 3, 2026 18:09
The section was written PR by PR, so it described steps between unreleased
states: checkpoint format versions 3 through 8 and a "breaking" wall-law
signature, for features a 0.3.0 user never had, plus fixes to code that was
added and then deleted. Fold those into their features, name what actually
breaks for a 0.3.0 user, replace the deleted POISSON_SOLVER_* preset names,
and add entries for the .cfdnn engine (#222), the 3D time step (#219), the
BC OpenMP gate (#228) and run-path truncation (#203), which had none.
…solves

The example never called grid_initialize_uniform(), so every solver ran on a
grid with zero spacing, and it ignored init and step statuses. The projection
rows timed pressure solves failing at max_iterations, which pushed the run
past five minutes, and backends missing from the build printed inf. Found by
the release gate's example run.
The README's basic-usage snippet called cfd_init() and fprintf(stderr, ...)
without their headers, so it did not compile as published. Three docs told
readers to call cfd_cleanup(), which the library has never exported; the
function is cfd_finalize(). The solver table credited NEON with Navier-Stokes
kernels that do not exist and omitted explicit_euler_gpu, and three links
pointed at a wrong relative path or into the gitignored .claude directory.
Found by the v0.4.0 release documentation checks.
The exporter records the library release it was written against, the same
field the C writer fills from cfd_version.h, and still said 0.3.0, a release
that never had the format. The release bump's file list missed it.
The guide showed a config table and a run_simulation_step loop the example
never had, and none of the init and step status checks it now depends on.
Note that its Optimized rows are skipped on a build without AVX2, that
clock() reads CPU time on Linux and macOS, and fix the index anchor that
pointed at section 4 instead of 5.
Copilot AI balanced review requested due to automatic review settings October 3, 2026 19:31
@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown

🎉 Version Update Detected

This PR updates the version from 0.3.0 to 0.4.0.

✅ What happens next:

  • All platforms will be built and tested
  • Artifacts will be kept for 30 days (instead of 7 days)
  • When this PR is merged, a release will be automatically created

📦 Release artifacts will include:

  • Windows binaries (x64, x86)
  • Linux binaries (GCC, Clang)
  • macOS binaries (Intel, Apple Silicon)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The benchmark still masks initialization and step failures, and the required cross-architecture validation did not run successfully.

Review effort: Balanced
Findings: 3 Medium severity

Open (3)
What changed in this PR

Prepares v0.4.0 release metadata, documentation, and examples for the turbulence milestone.

Changes:

  • Bumps all version identifiers to 0.4.0.
  • Rewrites release notes and updates documentation.
  • Fixes performance-example initialization and status handling.
File Description
VERSION Triggers the v0.4.0 release.
tools/​cfdnn/​cfdnn.py Updates exporter version stamp.
ROADMAP.md Marks v0.4.0 complete.
README.md Fixes example and backend documentation.
lib/​include/​cfd/​solvers/​poisson_solver.h Corrects parameter documentation.
lib/​include/​cfd/​core/​cfd_version.h Updates version macros.
lib/​CMakeLists.txt Updates CMake project versions.
examples/​performance_comparison.c Initializes grids and checks solver statuses.
Doxyfile Updates documentation version.
docs/​reference/​api-reference.md Corrects initialization API names.
docs/​index.md Updates version, links, and API name.
docs/​guides/​examples.md Documents corrected benchmark behavior.
CHANGELOG.md Adds consolidated v0.4.0 release notes.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread VERSION Resolved
Comment thread examples/performance_comparison.c Resolved
Comment thread examples/performance_comparison.c Resolved
…e run otherwise

Addresses the two Copilot findings on PR #244. Every init failure was printed
as a skip, so an INVALID or NOMEM refusal looked like a backend this build
lacks; and a failed init or step left a void helper that main ignored, so the
run printed "Benchmark completed" and exited 0. Only CFD_ERROR_UNSUPPORTED is
a skip now; any other failure, including a solver the registry cannot create,
is returned, counted, and makes main exit nonzero. Checked by injecting an
unknown pressure_solver (every init refuses: exit 1) and dt = -0.001 (every
step refuses: 16 failed runs, exit 1); the clean run exits 0.

Siblings deferred: custom_source_terms, minimal_example, minimal_example_3d,
runtime_comparison, solver_selection and steady_flow_multigrid also discard
init and step statuses. They predate this release and the release does not
touch them, so they get their own PR rather than widening this one.
Copilot AI balanced review requested due to automatic review settings October 4, 2026 04:39
@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown

🎉 Version Update Detected

This PR updates the version from 0.3.0 to 0.4.0.

✅ What happens next:

  • All platforms will be built and tested
  • Artifacts will be kept for 30 days (instead of 7 days)
  • When this PR is merged, a release will be automatically created

📦 Release artifacts will include:

  • Windows binaries (x64, x86)
  • Linux binaries (GCC, Clang)
  • macOS binaries (Intel, Apple Silicon)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The benchmark mishandles unavailable OpenMP builds, and release-date and lifecycle documentation corrections remain unresolved.

Review effort: Balanced
Findings: 2 Medium severity

Open (2)
Resolved since last review (2)
Previously missed (1)

In code that hasn't changed since last review

Low severity Document initialized flag as current lifecycle state

docs/​reference/​api-reference.md:27

This describes the flag as permanently true once initialization has ever run, but cfd_finalize() resets it to zero (lib/src/core/cfd_init.c:28-34). Document the current initialized state so callers do not rely on the wrong lifecycle semantics.

Comment thread examples/performance_comparison.c Resolved
shaia added 3 commits October 4, 2026 08:12
Addresses Copilot's re-review of PR #244. The reference said
cfd_is_initialized() stays non-zero once cfd_init() has run, but
cfd_finalize() resets the flag, so it reports the current state. The same
block, and architecture.md, said cfd_init() uses pthread_once or
InitOnceExecuteOnce; it is an atomic compare-and-swap on that flag.
…only one init refuses

Addresses Copilot's re-review of PR #244. A build without OpenMP never
registers the _omp solvers, so cfd_solver_create() failed with
CFD_ERROR_NOT_FOUND before init could say CFD_ERROR_UNSUPPORTED, and the
example counted the OpenMP rows as failures and exited 1 (reproduced on a
-DCMAKE_DISABLE_FIND_PACKAGE_OpenMP=ON build: 8 "not registered" failures).
cfd_solver_create_checked() refuses an unavailable backend with
CFD_ERROR_UNSUPPORTED before the name lookup, so the example uses it and
skips that status at creation as it does at init; a name that is genuinely
unregistered is still a failure. Both builds now exit 0: without OpenMP,
8 rows timed and 16 skipped; with it, 16 timed and 8 skipped.

The deferred sibling examples (solver_selection, runtime_comparison,
custom_source_terms) also create optional-backend solvers with plain
cfd_solver_create(); they are part of the same follow-up PR.
The release branch was cut on 2026-10-03 but merges after the cross-arch
validation re-run, on 2026-10-04.
Copilot AI balanced review requested due to automatic review settings October 4, 2026 05:15
@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown

🎉 Version Update Detected

This PR updates the version from 0.3.0 to 0.4.0.

✅ What happens next:

  • All platforms will be built and tested
  • Artifacts will be kept for 30 days (instead of 7 days)
  • When this PR is merged, a release will be automatically created

📦 Release artifacts will include:

  • Windows binaries (x64, x86)
  • Linux binaries (GCC, Clang)
  • macOS binaries (Intel, Apple Silicon)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

The exporter version bump lacks regression coverage, and Unix OpenMP benchmark timings remain non-comparable.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)
Resolved since last review (1)
Previously missed (2)

In code that hasn't changed since last review

Medium severity Add test coverage for exporter version 0.4.0 stamp

tools/​cfdnn/​cfdnn.py:80

The exporter stamp is not covered by the Python tests: test_header_layout_matches_the_documented_offsets checks the fields around it but skips offsets 16–21, and the committed golden header still contains minor version 3. The reported 20/20 suite would therefore pass even if this release-critical bump were reverted. Add an assertion that a freshly serialized model contains (0, 4, 0) at those three uint16 fields (and decide whether the generated golden should be refreshed).

Low severity Use wall-clock time for cross-platform solver benchmarks

docs/​guides/​examples.md:297

This warning documents that the benchmark's headline solver comparison is not valid on Unix: process CPU time charges work across the OpenMP threads while scalar uses one thread, so the reported OpenMP throughput can be penalized roughly by the worker count. Since this example explicitly compares backend performance, measure elapsed wall time instead; examples/runtime_comparison.c:79-90 already provides the repository's cross-platform wall-clock pattern.

shaia added 2 commits October 4, 2026 08:34
Addresses Copilot's review of PR #244. Nothing checked header bytes
[16, 22), so the 0.3.0 -> 0.4.0 exporter bump could be reverted with all
tests passing; that is how the stamp went stale in the first place. The test
reads VERSION rather than a literal, so it needs no edit per release and
fails when a bump misses the exporter (checked: with (0, 3, 0) restored it
fails '(0, 3, 0) != (0, 4, 0)').

The golden header in tests/nn keeps the 0.3.0 stamp it was generated with:
test_cfdnn_python_export skips those bytes and the CRC over them by design,
and regenerating it means retraining with distill_algebraic.py.
Addresses Copilot's review of PR #244. clock() is wall time on Windows but
process CPU time on Linux and macOS, summed over every OpenMP thread, so the
example's headline comparison charged the OpenMP rows for their worker
count. It now reads C11 timespec_get(), the wall_seconds() helper
pressure_driven_channel and steady_flow_multigrid already use. The guide's
snippet and caveat, and the CHANGELOG entry, follow.
Copilot AI balanced review requested due to automatic review settings October 4, 2026 05:40
@github-actions

github-actions Bot commented Oct 4, 2026

Copy link
Copy Markdown

🎉 Version Update Detected

This PR updates the version from 0.3.0 to 0.4.0.

✅ What happens next:

  • All platforms will be built and tested
  • Artifacts will be kept for 30 days (instead of 7 days)
  • When this PR is merged, a release will be automatically created

📦 Release artifacts will include:

  • Windows binaries (x64, x86)
  • Linux binaries (GCC, Clang)
  • macOS binaries (Intel, Apple Silicon)

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

The release-triggering version bump should await completion of cross-architecture validation run 37131663746, which remains in progress.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)

@shaia
shaia merged commit 526098a into master Oct 4, 2026
19 checks passed
@shaia
shaia deleted the release/v0.4.0 branch October 5, 2026 05:46
shaia added a commit that referenced this pull request Nov 18, 2026
…ure (#246)

* Make the examples report solver failures and exit nonzero

Six examples discarded solver_init, solver_step and run_simulation_step
statuses, so a solver that stopped working still printed results and
exited 0, and the release gate's example run could not see it. Each now
checks every status, skips a solver whose backend the build or machine
lacks, and exits 1 on anything else.

solver_selection checks cfd_backend_is_available() before switching to the
AVX2 solver: simulation_set_solver_by_name() reports success even when the
new solver's init fails, so the failure would only show at the first step.
It also creates the directory for its direct-API VTK file, which it wrote
into a missing output/ while printing "Output written to". runtime_comparison
is rebuilt on create_sim() and time_solver(), which separate a missing
backend from a failure; it used to step NULL simulations and divide by zero
timings, and now prints n/a.

Checked on a default build (AVX2 off) and one without OpenMP: all six exit
0, and with a negative dt injected minimal_example, runtime_comparison and
solver_selection exit 1 with the failing step named.

* Skip a validation solver only when its backend is missing

Several harnesses treated any NULL from cfd_solver_create() as "not
available" and skipped, which also hid an unregistered name or an
allocation failure (test_solver_architecture, test_taylor_green_decay,
test_natural_convection, test_ghia_projection_gpu, and the Taylor-Green
backend consistency test, which skipped on any failure at all), while
BackwardFacingStepRe400Test failed instead of skipping on a build without
OpenMP, where the _omp solvers are not registered and creation reports
CFD_ERROR_NOT_FOUND.

tests/validation/solver_availability.h creates solvers with
cfd_solver_create_checked(), which reports a missing backend as
CFD_ERROR_UNSUPPORTED before the name lookup, and marks only that status
unavailable. Every harness that may be handed an optional backend uses it,
including the two cavity-harness sites #245 fixed inline. tg_run_simulation()
also stops ignoring solver_init() and solver_step() statuses.

Exempt: poiseuille_3d_reference.h, taylor_green_3d_reference.h,
test_poiseuille_flow, test_turbulent_channel and the cavity harness's
scalar-only site only ever create the scalar projection, and a NULL there
already fails.

Checked on a default build and on one without OpenMP: the 20 and 21 affected
validation tests pass, BackwardFacingStepRe400Test now skips without
OpenMP, and a misspelled solver in the Taylor-Green consistency test fails
("not created: Resource not found") where it used to print SKIPPED.

* Report a failure with its own message, not the library's last one

failure_reason() printed cfd_get_last_error() whenever a message was stored,
so a failure that set none was reported with an earlier, unrelated message,
such as a backend skipped further up the run. It now uses the stored message
only when cfd_get_last_status() matches the status being reported.
Found by /code-review on this branch in solver_selection; the same helper in
performance_comparison (from #244) gets the same fix.

* Clear the error state before creating a validation solver

Review finding (#246): cfd_solver_create() reports a factory's NULL as
CFD_ERROR_NOMEM only while the last status is still CFD_SUCCESS, and that
status is sticky. An UNSUPPORTED left over from an earlier solver made a later
allocation failure read as unavailable, so validation_create_solver() skipped
exactly the failure it exists to expose.

* Skip an example solver only when its backend is refused

Review findings (#246): runtime_comparison and solver_selection read "not in
the registry" as "backend unavailable", so a misspelled or removed solver
printed n/a or SKIPPED and the example still exited 0. solver_selection also
ignored a failed registry allocation, after which every solver read as
skipped and the run reported zero failures.

Both now probe with cfd_solver_create_checked(), which refuses an unavailable
backend with CFD_ERROR_UNSUPPORTED before the name lookup, and skip only that
status; any other creation failure, an unknown name included, is a failure. A
NULL registry in solver_selection is reported and counted as one.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants