Usability and onboarding improvements - #260
Merged
Merged
Conversation
…erence Add a Try it now section showing -pc_type air works with no source changes when PETSc is configured with --download-pflare, plus the minimal registration snippets for standalone builds. Link the PCAIR and PCPFLAREINV manual pages hosted on petsc.org, add Spack as a quick start route, promote the Jupyter notebooks above the docs table, add a supported-configurations table distilled from CI, and link CONTRIBUTING, LICENSE, CITATION.cff and the issue tracker. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The generated pkg-config file hardcoded a stale version (1.24.9); it now reads the new top-level VERSION file. Matching PFLARE_VERSION_* macros are added to include/pflare.h so applications can check the version at compile time, and the build errors out if the two drift apart. Add a CHANGELOG.md seeded from the git history since v1.25.0 and a release checklist in CONTRIBUTING.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ersion The second reference's doi field had a leading space and a full URL where CFF expects a bare DOI, which breaks citation tooling. The third reference was a stale arXiv preprint entry; it is now published as J. Comput. Phys. 565 (2026) 115177 (doi 10.1016/j.jcp.2026.115177), matching the README. Also add top-level version and date-released fields. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Bug report, convergence-help and feature-request forms that prompt for the PFLARE/PETSc versions, the full options string and -ksp_view / -pc_air_print_stats_timings output, pointing at docs/faq.md first for convergence questions. The PR template records the contribution checklist from CONTRIBUTING.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Document the make install / PREFIX / DESTDIR targets and the generated pkg-config file in installation.md, and the standard PETSc -mg_coarse_* options now that a user-supplied coarse-grid solver is supported. Add an FAQ section on solving sparse triangular systems from ILU factorisations with PCAIR, pointing at tests/ilu_factors.c. Fix the stated default smooth type (ff, not f), the duplicated PCAIRSetALump routine name in the options table, and the stale LICENSE.txt reference in CONTRIBUTING.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The PCAIRGet/Set routines forward to Fortran routines that cast pc->data unconditionally, so calling one on a PC of a different type reinterpreted that type's private data as a PC and corrupted memory. Each forwarder now checks the PC type first and raises PETSC_ERR_ARG_WRONG. The PCPFLAREINV routines already go through PetscUseMethod and were safe. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The if/else chain over CFSplittingType in the viewer was missing CF_PMIS_AGG, so -pc_air_cf_splitting_type pmis_agg with -ksp_view or -pc_view printed no CF splitting information at all. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The Fortran binding unconditionally null-padded the output out to index 256, smashing the stack of any caller that passed a smaller buffer. Only the pattern plus its null terminator (at most 11 bytes) is written now, and the required buffer size is stated in the manual page. Also document that PCAIRSetSmoothType truncates patterns longer than 10 characters. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Three PetscOptions* calls passed the Get routine name where PETSc convention is the corresponding Set routine: -pc_air_ddc_its, -pc_air_ddc_fraction and -pc_air_coarsest_subcomm. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add a PEP 517 pyproject.toml so pip install --no-build-isolation --no-deps ./python installs the bindings once the library is built, giving conda-forge and other packagers a standard entry point. The package version is read from the top-level VERSION file and pflare.py is now installed alongside the extension. make python is unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
CFSplittingType, PCPFLAREINVType, PCAIRZType and WhichInverseType are now IntEnum classes matching the C enums, so values are typo-resistant and self-documenting in repr(). The flat module-level names (pflare.CF_PMISR_DDC etc.) still exist as aliases of the members and compare equal to the old ints. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The re-exported bindings had no docstrings, so help() on any pflare function returned nothing. One-line descriptions matching docs/options.md, including the corresponding command line option and default, are now attached to all the get/set routines and the standalone helpers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
After the image build, install the bindings with pip --no-build-isolation --no-deps inside the container, check the installed version matches the VERSION file, and import and solve from outside the source tree so the installed copy is exercised. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
PMIS_AGG is aggregation based; Luby steps only apply to the boundary PMIS pass in parallel and not at all in serial, so print only the strong threshold like the agg branch. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
pflare_defs.c and the .so are generated by make python, and build/ and the egg-info by pip install; a stale in-tree pflare_defs.c can also be picked up by a later pip install against a different petsc4py and produce confusing binary-incompatibility errors, so keep them all out of the tree. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
-I$(CURDIR) is on the include path and macOS filesystems are case insensitive, so a top-level file named VERSION shadowed the C++20 <version> standard header and broke every libc++ include in the Kokkos C++ compiles on the mac CI runners. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The TOML table form (license = {text = ...}) raises a
SetuptoolsDeprecationWarning on setuptools >= 77 and stops being
supported in 2027; the string form is accepted everywhere the CI
builds (the Docker image has setuptools 83 and the macOS venvs
install the latest).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
A set of usability, onboarding and robustness improvements, one commit per change:
Docs & onboarding
VERSIONfile as the single source of truth: read by the generated pkg-config file (which hardcoded a stale 1.24.9), mirrored by newPFLARE_VERSION_*macros inpflare.h(build errors if they drift), and by the pip-installed package versionCHANGELOG.mdseeded back to v1.25.0, with a release checklist in CONTRIBUTING.mdversion:/date-released:-pc_air_print_stats_timingsoutput, plus a PR templatemake install/PREFIX/pkg-config and the-mg_coarse_*user coarse-solver options; new FAQ section on solving ILU triangular factors; fix stated default smooth type (ff)C API robustness
PCAIRGet/Set*on a non-air PC now raisesPETSC_ERR_ARG_WRONGinstead of casting foreignpc->dataand corrupting memory-pc_viewnow prints the CF splitting line forpmis_agg(strong threshold only; Luby steps don't apply to the aggregation)PCAIRGetSmoothTypeno longer null-pads 256 bytes into the caller's buffer; buffer contract documentedPetscOptions*man-page slots corrected to the Set routine namesPython
pyproject.toml:pip install --no-build-isolation --no-deps ./pythonnow works and is tested in thegnu_optCI job (installs, version check againstVERSION, import and a solve from outside the source tree)IntEnumclasses (flat names kept as aliases)help()worksChecklist
make check,make tests_shortand the python test suite passpmis_aggfix is covered by the robustness commits above)🤖 Generated with Claude Code