Claude’s contributions to Janus

Contents

Claude’s contributions to Janus#

As of august 2026, Janus is revived by the author with the help of Claude Code. This page will collect all interactions between the author and Claude.

2026-09-26 • Deployment of the documentation by GitHub Actions#

Build the HTML documentation in continuous integration, and deploy it to GitHub Pages from GitHub Actions, instead of versioning the generated HTML in docs/. This is the third suggestion of the task Updating the online docs (below), and part of E11 in the Roadmap to v1.0; it was left out of scope of the task Continuous integration.

Current situation: GitHub Pages serves master:/docs, which is regenerated by hand (scripts/empty_docs.py, then python -m sphinx -b html -E -d sphinx/_build/doctrees sphinx docs) and committed. A complete build, made on 2026-09-26 in the janus environment, produces no warning (the warnings related to janus.fft.parallel disappeared with the removal of distributed memory), so that the build can be made strict.

Proceed in the order below, one step at a time. Each step is a separate commit, made by the author: Claude does not commit, nor push. Report on each step in its own sub-paragraph of Claude’s report, and wait for validation before starting the next one.

Out of scope: the PDF version of the documentation, packaging and publication on PyPI (milestone 0.4).

Decision required from the author before step 1: when is the documentation deployed?

  1. at each push to master (the site always reflects master, including the present page and the roadmap as they are being written);

  2. only on request (workflow_dispatch) and/or when a version tag is pushed (the author keeps control of what is published, as today).

In both cases, the documentation is built at each push and pull request, on all branches, so that a broken build is detected; it is never deployed from a pull request, a branch other than master, or the weekly run.

Decision (2026-09-26): option a, the documentation is deployed at each push to master.

2026-09-26 • Step 1 — Workflow#

.github/workflows/docs.yml (new file), or new jobs in .github/workflows/tests.yml: Claude proposes one option in its report, with its reasons.

  • Job build (ubuntu-latest only): same environment as tests.yml (Miniforge, environment.yml, janus activated); pip install --no-build-isolation -e . (autodoc imports the compiled modules); python -m sphinx -b html -E -W --keep-going sphinx _site (any warning fails the build); actions/upload-pages-artifact.

  • Job deploy: needs: build, runs only in the cases chosen by the author (see above); actions/deploy-pages, with permissions: pages: write, id-token: write for this job only, and the github-pages environment. The URL of the deployed site is shown in the summary of the run.

  • concurrency: two deployments must never run at the same time, and a deployment in progress should not be cancelled.

  • .nojekyll: produced by sphinx.ext.githubpages; check that it is not needed with a deployment by GitHub Actions, and keep the extension anyway, since it does no harm.

The workflow only runs once pushed to GitHub, which the author does. Before that, run its commands by hand on a fresh clone. Until step 2 is done, the deploy job fails (GitHub Pages still expects a branch): report whether it should be disabled until then.

2026-09-26 • Step 2 — Switch the source of GitHub Pages#

Made by the author, in Settings → Pages: Source switches from Deploy from a branch (master, /docs) to GitHub Actions. Claude gives the exact procedure in its report of step 1, and how to check the result: the online site is identical to the build of the workflow (e.g. the date of the last update of the present page), and the pages build and deployment workflow of GitHub no longer runs.

2026-09-26 • Step 3 — Remove docs/ from the repository#

Only once the site deployed by the workflow has been checked online.

  • git rm -r docs (made by the author; the history keeps the former HTML files); docs/.buildinfo is removed from .gitignore, and _site/ is added.

  • scripts/empty_docs.py is deleted.

  • sphinx/Makefile and sphinx/make.bat: the ghpages target is removed (the other targets, including latexpdf, are kept).

  • sphinx/installation.rst, section Build the documentation: the documentation is deployed by GitHub Actions (with the rule chosen by the author); to build it locally, python -m sphinx -b html -E sphinx sphinx/_build/html (or make html).

  • CLAUDE.md, Repository layout notes: same update; the rule “only regenerate docs/ when asked” is replaced by the rule of deployment.

  • The reports of the previous tasks are not modified: they describe the situation at their date.

Check that no reference to docs/, empty_docs or ghpages remains outside the present page (git grep), and that the local build still succeeds without warning.

Claude’s report#

Step 1 — Workflow#

New file .github/workflows/docs.yml, rather than new jobs in tests.yml, for two reasons:

  • tests.yml cancels a run in progress when a new push arrives on the same branch (concurrency at the level of the workflow), which must not happen to a deployment; separate files keep a simple rule in each;

  • the Pages permissions stay confined to a workflow that does nothing else. The cost is the duplication of the setup of the environment (about ten lines), and one more build of Janus under Linux at each push (a few minutes).

Content:

  • triggers: push and pull_request (all branches), workflow_dispatch; no schedule, since the weekly run of tests.yml already detects breakage caused by new versions of the dependencies, and a weekly redeployment of an unchanged site is pointless;

  • job build (ubuntu-latest): same setup as tests.yml (Miniforge, environment.yml, conda list, pip install --no-build-isolation -e .), then python -m sphinx -b html -E -W --keep-going -d sphinx/_build/doctrees sphinx sphinx/_build/html, and actions/upload-pages-artifact@v5. The output goes to sphinx/_build/html, which is already git-ignored, rather than _site: the item “add _site/ to .gitignore” of step 3 is therefore no longer needed. A new push to the same branch cancels the build in progress;

  • job deploy: needs: build, runs only for master and outside pull requests, i.e. at each push to master (option a), and also on a manual run from master (workflow_dispatch), which allows a redeployment without a commit, e.g. after step 2. permissions: pages: write, id-token: write for this job only (the workflow otherwise has contents: read), environment github-pages, whose URL is shown in the summary of the run. Deployments run one at a time and are never cancelled (concurrency group shared by all branches, cancel-in-progress: false);

  • versions: actions/upload-pages-artifact@v5 and actions/deploy-pages@v5 are the latest major versions; actions/checkout@v4 and setup-miniconda@v3 as in tests.yml.

.nojekyll: not needed with a deployment by GitHub Actions, since the artifact is published as is, without Jekyll. upload-pages-artifact excludes hidden files by default, so that .nojekyll (and .buildinfo) are not even uploaded. The sphinx.ext.githubpages extension is kept, as agreed.

What was checked:

  • the file is valid YAML (two jobs, build and deploy, and the three triggers);

  • the commands of the build job were run by hand on a fresh clone of master (no setup.cfg, no compiled artifacts), with the present page copied into it, in the existing janus environment: build of Janus OK, build of the documentation OK with -W, i.e. no warning. The environment was not recreated from environment.yml, unlike step 2 of Continuous integration.

  • Incident: pip install -e . in the clone redirected the editable install of the janus environment to the clone. It was restored by pip install --no-build-isolation -e . in the repository; janus is again imported from the repository, the tests give 3043 passed, 111 skipped, and the clone was deleted.

The workflow itself could not be run: it will run when the author pushes it.

Order of the next operations. According to the documentation of deploy-pages, a deployment by GitHub Actions is accepted while Pages uses a source branch only if it comes from that branch. Claude first proposed to push the commit of step 1 to another branch (build only), then to switch the source, then to merge into master. At the author’s suggestion, the order is simpler, and the deploy job never meets the former configuration, so that it needs not be disabled:

  1. step 2: switch the source of GitHub Pages to GitHub Actions, before the commit of step 1 is pushed. The site currently online should remain served until the next deployment; Claude could not check this, so point 2 should follow shortly;

  2. push the commit of step 1, directly to master: the build job runs, then the deploy job publishes the site.

The switch is reversible: if the site disappears and the first deployment fails, switching the source back to Deploy from a branch (master, /docs) restores the former site, since docs/ is only removed at step 3.

Procedure of step 2 (made by the author): Settings → Pages → Build and deployment → Source: choose GitHub Actions instead of Deploy from a branch. GitHub then creates the github-pages environment if it does not exist yet, restricted by default to deployments from the default branch (master). Check: after the deployment of point 2, the Deployments section of the repository shows github-pages deployed by the docs workflow; the online site contains the present task (it is absent from the current docs/); a push to master no longer triggers the pages build and deployment workflow of GitHub.

The author switched the source of GitHub Pages, then pushed the commit of step 1 to master: the site was deployed by the docs workflow (2026-09-26). This completes step 2.

Step 3 — Remove docs/ from the repository#

  • .gitignore: docs/.buildinfo is removed. Nothing is added: the workflow builds into sphinx/_build/html, already ignored (see step 1).

  • scripts/empty_docs.py is deleted.

  • sphinx/Makefile and sphinx/make.bat: the ghpages target is removed, together with the GHPAGESDIR and PYTHON variables, which were only used by this target, and with the Janus-specific target part of help. Both files are again the templates of sphinx-quickstart; make.bat keeps LF line endings in git.

  • sphinx/installation.rst, section Build the documentation: the documentation is deployed by the docs workflow at each push to master, and built without deployment on the other branches and for pull requests; local build with python -m sphinx -b html -E sphinx sphinx/_build/html (-W --keep-going to check the absence of warnings), or make html.

  • CLAUDE.md, Repository layout notes: same update. The rule “only regenerate docs/ when asked” is replaced by a warning: pushing to master publishes the documentation, including the present page and the roadmap.

Not done by Claude, as agreed: git rm -r docs. Since docs/.buildinfo is no longer ignored, it now shows up as untracked; git rm does not remove it, so docs/ should then be deleted altogether (rm -rf docs, or git clean -fd docs).

What was checked: git grep finds no reference to docs/, empty_docs, ghpages, .nojekyll or .buildinfo outside docs/ and the present page; the documentation builds without warning (-W --keep-going), and make html builds into sphinx/_build/html. make.bat was not run (no Windows on this machine).

Suggestion (applied, see below): section E11 of the Roadmap to v1.0 still mentions “possibly the deployment of the documentation to GitHub Pages” as a proposal, and the introduction lists what is done; both could state that this part is now done.

Follow-up: roadmap updated#

At the author’s request, the suggestion was applied to the Roadmap to v1.0:

  • introduction: the list of what is done now includes the deployment of the documentation by continuous integration (E11);

  • E11, Proposal: “possibly the deployment of the documentation” becomes “build and deployment of the documentation to GitHub Pages”;

  • E11, Recommendation: the part marked as done now describes the docs workflow (build at each push, failing on any warning; deployment at each push to master; HTML no longer versioned);

  • milestone 0.2 (Milestones), for consistency: a sentence states that the deployment of the documentation was added afterwards. It is not presented as part of the milestone, which was defined without it.

2026-09-26 • Make the roadmap consistent with the decisions of 2026-09-25#

Priority task. The decisions recorded in The continuum Green operator in the new architecture (below) were applied to sections E3, E4, E7 and Milestones of the Roadmap to v1.0 only. Update the other parts of the roadmap, which still assume that Cython is replaced by NumPy/JAX. The list established at the end of that section is the starting point:

  • Goals: new physics implementable without compilation, GPU not to be ruled out;

  • friction point 2, which presents the per-frequency design as a problem;

  • E2: its recommendation contradicts milestone 0.3 (it refers to the array namespace of E7, and does not state that the link to FFTW disappears with scipy.fft);

  • E5, E6 (new schemes “in a few lines of Python”), E8, E10, E11, E12;

  • E8 and milestones 0.4 and 0.5 must also reflect the decision on local operators (see Follow-up: local operators): functions of fields, reference implementation in pure NumPy (phase map, loop over the phases), Numba as an optional dependency, removal of BlockDiagonalOperator2D/3D at milestone 0.4;

  • the scope of the constitutive laws (see Follow-up: scope of the constitutive laws): linear laws, and hyperelasticity at finite strain, without internal variables. Remove or qualify the mentions of general nonlinear laws (Goals, E8: “extensible to nonlinear laws”, tangent operators by automatic differentiation; E10);

  • Decisions required from the author: Default backend and Acceptable slowdown are obsolete;

  • the introduction (see Status of the roadmap);

  • the mentions of JAX and of automatic differentiation (Goals, E1, E5, E8, E10, E12), to be aligned with E13 (see Automatic differentiation with JAX): JAX is no longer a backend, but a use case shown by an example.

Start with E2. Report the proposed changes before applying the ones that go beyond consistency (i.e. that would express a new decision).

Claude’s report#

E2 (2026-09-26). Changes applied, for consistency only:

  • a note states that the section was revised, and why;

  • Gains of scipy.fft: “no additional dependency (SciPy is needed anyway for iterative solvers)” was inaccurate: NumPy is currently the only runtime dependency of Janus (see environment.yml; SciPy is not even installed in the janus environment). The text now says that SciPy becomes a runtime dependency, distributed as wheels, and needed anyway by the users for the solvers;

  • Losses of scipy.fft: the loss of the fine tuning of FFTW is measured by the benchmark of milestone 0.3;

  • new paragraph Keeping the current wrapper: with Cython kept, this option had to be discussed; it records the reasons of Follow-up: milestones (negligible cost of a call from Python once per field, link to FFTW required by setup.cfg and awkward for wheels);

  • Recommendation: the reference to the array namespace of E7 was removed; the FFT is called from Python, the loop over frequencies remaining in Cython; scipy.fft from milestone 0.3 on, deletion of the wrapper, of the link to FFTW and of setup.cfg at milestone 0.4.

Point going beyond consistency, submitted to the author, approved and applied: scipy.fft has no out argument, so that each transform allocates its result, whereas the current discrete Green operators preallocate two Fourier buffers (dft_x, dft_y, i.e. two complex fields) and the in-place semantics of apply(x, y) is kept (E7). Claude proposed to add to the Implementation problems of E2 (now done): transform the whole field at once (rfftn over the grid axes), apply the Green operator in place on the Fourier coefficients (with a small temporary vector per frequency, which removes the second buffer), and write the inverse transform component by component into y, so that the temporaries are one complex field and one real component; the layout of the output of rfftn (contiguity, strides) seen by the Cython loop is to be checked.

Goals (2026-09-26). Changes applied, for consistency only; a note records the initial wording:

  • installation: “without compiler” now relies on precompiled wheels;

  • new discretizations and new physics are written in Cython, within the library, mainly by the author (decision 4); the local operators are written without compilation, in NumPy, or in Numba where NumPy is not suitable (Follow-up: local operators);

  • new item on the scope of the constitutive laws: linear laws and hyperelasticity at finite strain; laws with internal variables are out of scope (Follow-up: scope of the constitutive laws); “finite strain solid mechanics” became “finite strain hyperelasticity”;

  • GPU execution: the requirement that the architecture should not rule it out was dropped, GPU execution being “not a priority” (decision 4); automatic differentiation remains possible through E13.

Found along the way, not in the initial list: the Gains of E6 state that “new schemes can be added in a few lines of Python”, whereas, with E4 as revised, the modified wave-vectors are computed on the fly in the Cython loop, so that a new scheme is written in Cython. To be corrected at the same time as the other evolutions.

Friction point 2 (2026-09-26). Changes applied, for consistency only; a note records the initial wording. The title “Operators are scalar and stateful” became “Operators are stateful”: evaluating the physics one wave-vector at a time is the design retained by decision 3, and is no longer presented as a problem. The problem is the hidden state shared by set_frequency and apply (no sharing between threads, hence no parallel loop over frequencies; result depending on a previous call); this is also how E3 already refers to this friction point. The local operators, already mentioned by the initial wording (“cells”), are described as in Follow-up: local operators (one Cython object per cell, indirect call per cell, microstructure described cell by cell). The remaining consequence of the per-frequency design (a physics must be compiled to be fast) is kept, with a reference to E3.

E5 (2026-09-26). Changes applied; a note records that the section initially assumed a core written in NumPy or JAX:

  • Proposal: the dimension is a run-time value; E5 concerns the Cython part only (discrete Green operators and physics), the local operators written in NumPy (E8) being dimension-generic at no cost;

  • Losses: the argument on NumPy and JAX was replaced by its Cython counterpart (loops with run-time bounds, which the C compiler cannot unroll; slowdown to be measured);

  • Consequences: the apply method of the physics takes the dimension as a parameter from milestone 0.3 on (Follow-up: milestones);

  • Recommendation: “Adopt together with E4” contradicted the milestones; it became “milestone 0.5, after the switch”, with the reasons of Follow-up: milestones.

New paragraph Implementation problems, which develops the approach already stated in E3 (loop over a flattened frequency index) without deciding anything: the number of dimensions of a memoryview is fixed at compile time, hence a view of shape (N, n) of the Fourier coefficients (which depends on the layout of the output of rfftn, see E2), and the wave-vector recovered from the flattened index by integer divisions or by an incremented multi-index, whose costs are to be measured.

E6 (2026-09-26). Changes applied; a note records the initial wording:

  • Proposal: new paragraph stating that a scheme, like the physics, is written in Cython and is stateless (wave-vectors and weights computed on the fly for each discrete frequency, in buffers provided by the caller), the loop over frequencies, the calls to the physics and the weighted sum being generic; this transposes E4 to the schemes;

  • Gains: “a few lines of Python” became “a few lines of Cython”;

  • Losses: the initial argument (“instead of combining precomputed matrices; this is also the case in the current code”) did not describe the current code accurately: FilteredGreenOperator2D/3D forms the matrix of the symbol at the 4 or 8 wave-vectors, combines these matrices, then applies the result. With E4, the symbol is applied 4 or 8 times and the results are summed, which should cost about the same. Claude added that the calls from the generic loop to the scheme and to the physics are indirect (cdef methods), hence not inlined; both points are to be checked by the benchmark of milestone 0.3;

  • Implementation problems: complex wave-vectors are presented as one of the open points of the signature of the physics (E4), rather than as a requirement (“should” became “may have to”).

The Recommendation (milestone 0.3) was already consistent with the milestones.

E8, milestones 0.4, 0.5 and 0.6 (2026-09-26). Changes applied, for consistency; a note records the initial wording of E8:

  • E8 rewritten according to Follow-up: local operators: local operators are functions of fields, on arrays of shape (*grid_shape, n); pure NumPy for linear laws with few phases (phase map, one matrix per phase, loop over the phases); Numba where NumPy is not suitable (many phases, hyperelasticity); the interface with the Green operator only consists of fields. The mentions of general nonlinear laws, of vmap and of tangent operators obtained by automatic differentiation were removed; tangent operators are written by hand, and JAX is mentioned through E13 only;

  • following the author’s statement of 2026-09-26 (Automatic differentiation with JAX), local operators are written in complete examples, not in the library; Numba is therefore a dependency of some examples, not of the library. The Follow-up: local operators of 2026-09-25 spoke of a “reference implementation in pure NumPy”, without saying where it would live; E8 now follows the later statement;

  • Recommendation of E8: milestone 0.4 instead of 0.5, since the deletion of BlockDiagonalOperator2D/3D at the switch requires the tutorials to be ported to local operators written in NumPy;

  • milestone 0.4: BlockDiagonalOperator2D/3D and the fourth-rank tensor classes are listed among the deleted API; local operators become functions of fields, and the tutorials are ported accordingly;

  • milestone 0.5: “Local operators described as fields, e.g. phase maps (E8)” was removed (moved to 0.4), and “reference iterative schemes (E10)” became a sentence of its own;

  • milestone 0.6: the representation of hyperelastic laws is decided there, and their local operators are written with Numba.

Points going beyond consistency, not applied, submitted to the author:

  • an example with many phases (e.g. a polycrystal), whose local operator is written with Numba, in milestone 0.5. The decisions say why Numba is needed, not when such an example is written. (Claude had first applied it, then reverted it, since the task asks for such changes to be proposed first);

  • the fourth-rank tensor classes (FourthRankIsotropicTensor2D/3D, FourthRankCubicTensor2D) are deleted at 0.4 with the rest of the local operators written in Cython, as stated by the author on 2026-09-26 (this is applied). The initial E8 proposed to turn them into small functions returning Mandel–Voigt matrices, i.e. to keep helpers in the library; whether the library should provide such helpers (e.g. in janus/mandelvoigt.py), or leave them to the examples, is not decided.

The author validated these changes on 2026-09-26, and decided both points: the example with many phases, written with Numba, is planned in milestone 0.5; the library provides helper functions returning the Mandel–Voigt matrices of usual fourth-rank tensors. Both decisions were applied to E8 (Proposal, Consequences, Recommendation) and to milestones 0.4 (helper functions replacing the fourth-rank tensor classes) and 0.5 (example with Numba).

E10 (2026-09-26). Changes applied, for consistency; a note records the initial wording:

  • the adapters to the JAX solvers were removed: JAX is no longer a backend, and the example with JAX handles its own solver, differentiated implicitly (E13);

  • “a Newton–Krylov loop for nonlinear problems” became “for hyperelastic problems at finite strain, with tangent operators written by hand” (Follow-up: scope of the constitutive laws);

  • Recommendation: “reference schemes in 0.5” was split: basic scheme in 0.5, Newton–Krylov loop in 0.6, since the latter needs the finite strain prototype; milestones 0.4 (“adapter”), 0.5 (basic scheme) and 0.6 (reference to E10) were aligned.

Point not applied, submitted to the author: on 2026-09-26, the author stated that “the rest of the chain” (everything but the Green operator) will no longer be developed in the library, but in complete examples. Taken literally, this also applies to the reference schemes (basic scheme, Newton–Krylov loop), which E10 still places in the library, and possibly to the adapter to scipy.sparse.linalg.LinearOperator. Claude proposes: the adapter stays in the library, since it only wraps the discrete Green operator; the reference schemes are written in the examples.

The author validated these changes on 2026-09-26, and approved the proposal, which was applied to E10 (Proposal, Gains, Losses, Recommendation) and to milestone 0.5 (example with the basic scheme).

E11 (2026-09-26). Changes applied, for consistency; a note records the initial wording (“once Cython is gone”, pure Python package, universal wheel):

  • Proposal: Janus remains a compiled package, without link to FFTW after the switch; precompiled wheels for Linux, Windows and macOS and for each supported version of Python (cibuildwheel), and a source distribution, as decided in Follow-up: milestones;

  • Gains: pip install without compiler holds on the platforms for which wheels are provided;

  • new Losses: build matrix to be maintained; a C compiler (but no longer FFTW) is still needed to install from the source distribution;

  • Recommendation: continuous integration is marked as done at 0.2, as it actually runs (.github/workflows/tests.yml: tests and doctests on Linux and Windows, at each push and once a week); macOS, wheels and publication at 0.4, in line with the milestones.

Two facts found while checking the code, added to the Implementation problems: pyproject.toml does not declare any runtime dependency yet (NumPy, and SciPy after E2); the extensions use typed memoryviews and not the C API of NumPy, so that the wheels do not depend on the version of NumPy they are built against.

E12 (2026-09-26). Changes applied; a note records the initial wording:

  • “the results do not depend on the backend” was removed (there is no backend any more); it is replaced by the comparison of the new core with the current code on the same grids until the switch, as stated in milestone 0.3, the tagged release of 0.4 taking over afterwards;

  • factual correction: the initial text stated that the discrete Green operator is a projector (\(\Gamma_0 \mathbf C_0 \Gamma_0 = \Gamma_0\)). Claude checked it on the current code (isotropic elasticity, grids of even and odd sizes, 2D and 3D): it holds for willot2015 on all grids and for the truncated scheme on grids of odd sizes, but fails for the truncated scheme on grids of even sizes (relative error of order \(10^{-1}\), presumably because of the Nyquist frequencies) and for the filtered scheme on all grids. Symmetry and annihilation of uniform fields hold for all six operators. The list of properties is now a bulleted list, the projector property being restricted to the schemes for which it holds; each scheme must state which properties it satisfies.

Points not applied, submitted to the author:

  • the failure of the truncated scheme on grids of even sizes is directly related to the open point of E4 on the Nyquist frequencies; Claude proposes to add a reference to this observation in the Implementation problems of E4;

  • since local operators and reference schemes now live in the examples (E8, E10), the examples should be run by continuous integration, so that they do not silently break; Claude proposes to add this to E12 (and to the continuous integration of E11).

The author validated these changes on 2026-09-26, and approved both proposals, which were applied: E4 (Nyquist frequencies) refers to the observation of E12; E12 states that the examples are run by continuous integration, and E11 lists their execution among the jobs of continuous integration.

Decisions required from the author (2026-09-26). Changes applied, for consistency; a note records the removed items:

  • Default backend and Acceptable slowdown (of a pure Python implementation) were removed, as obsolete;

  • Precision: “relevant on GPU” became “which halves the memory footprint of large grids; Cython’s fused types allow it”, GPU execution being no longer a priority;

  • Minimum supported versions: SciPy was added, since it becomes a runtime dependency (E2, E11).

Point not applied, submitted to the author: the acceptance criterion of milestone 0.3 is the absence of regression with respect to the current code. However, the genericity introduced in 0.3 (E6: indirect calls to the scheme and to the physics, not inlined) and in 0.5 (E5: loops with run-time bounds) may cost some performance, which E5 and E6 leave “to be measured”. Claude proposes to add a decision: Tolerance of the benchmark: strict absence of regression, or an accepted margin (to be set by the author) in exchange for genericity?

The author validated these changes on 2026-09-26, and approved the proposal: the decision Tolerance of the benchmark was added to the list.

Introduction, E1 and E7 (2026-09-26). The last sentence of the introduction was replaced, as decided by the author (see Status of the roadmap, formerly TO DISCUSS). In E1, the last mentions of JAX were removed (“JAX on GPU” became “prange loops in Cython or Numba”; “JAX sharding” was dropped). In E7, the reasons why the evolution was not adopted no longer state that automatic differentiation is not a priority, but that it remains possible without E7 (E13).

Summary#

All the items of the task were processed, in this order: E2, Goals, friction point 2, E5, E6 (added to the list on the way), E8 with milestones 0.4, 0.5 and 0.6, E10, E11, E12, Decisions required from the author, and the introduction, together with the last mentions of JAX in E1 and E7. Each revised section carries a note that records its initial wording. A final search of the Roadmap to v1.0 for “JAX”, “backend”, “nonlinear”, “vmap”, “pure Python”, “array namespace” and “GPU” only finds the historical analysis of E3, the non-adopted E7, E13, and the notes.

Besides consistency, the author took the following decisions during the task, all applied:

  • E2: handling of the temporaries of scipy.fft (whole field transformed at once, Green operator applied in place, inverse transform component by component);

  • E8: an example with many phases, written with Numba, in milestone 0.5; helper functions returning the Mandel–Voigt matrices of usual fourth-rank tensors are provided by the library;

  • E10: only the adapter to scipy.sparse.linalg.LinearOperator is in the library; the reference schemes are written in the examples;

  • E4/E12: reference to the Nyquist observation; the examples are run by continuous integration (E11);

  • new decision to be taken: Tolerance of the benchmark.

Two checks were made on the current code, with results recorded in the Roadmap to v1.0: the six discrete Green operators are symmetric and annihilate uniform fields (E12, E13); the projector property holds for willot2015, and for the truncated scheme on grids of odd sizes only, never for the filtered scheme (E12). Two facts were found in the configuration: SciPy is not a dependency yet (E2), and pyproject.toml declares no runtime dependency (E11).

Open points left to later milestones (not part of this task): signature of the cdef methods and representation of the local tensors (E4, E9), behaviour at the Nyquist frequencies (E4), layout of the output of rfftn (E2, E5), representation of hyperelastic laws (E8, milestone 0.6), and whether the solvers of jax.scipy.sparse.linalg can be differentiated through the adapter (E13).

The documentation builds without warning; docs/ was not regenerated, and nothing was committed. The author validated this summary on 2026-09-26, and the task was marked as done.

2026-09-26 • Automatic differentiation with JAX#

Not a task: record of a discussion held in the console. The author asked whether, Cython being kept, automatic differentiation with JAX could be recovered by implementing the missing derivatives of the Green operators by hand, JAX then applying the chain rule.

Discussion#

Claude answered that it can: JAX cannot differentiate code it does not see, but jax.pure_callback makes the Cython code callable from JAX (also under jit), and jax.custom_vjp provides its derivative, which JAX combines with the rest of the computation by the chain rule. With respect to the polarization, the discrete Green operator is linear, so that its vector-Jacobian product is its transpose; Claude checked numerically that the six current discrete Green operators (truncated, filtered, willot2015, in 2D and 3D) are symmetric, to within about \(10^{-16}\) (relative), including on grids of odd sizes. The derivative to be provided is therefore the operator itself: no new Cython code is needed. Only the derivatives with respect to the reference medium (\(\mu_0\), \(\nu_0\)) would require new kernels, but they are rarely needed.

Claude listed the limits: reverse mode only (JAX cannot transpose a pure_callback), execution on the host CPU, no fusion by XLA across the call, sequential vmap, jax_enable_x64 required; the solver should be differentiated implicitly (a custom_vjp around the whole solve, the backward pass solving the adjoint problem), not through its iterations. Claude also objected that the rest of the chain, in particular the local operators, would have to be visible by JAX, whereas the decision of 2026-09-25 is to write them in NumPy.

The author answered that this is not a problem: the library will only provide the Green operator, the local operators written in Cython disappearing; the local operators will be written in complete examples, in NumPy or Numba, and nothing prevents an example based on JAX, precisely to show that it is possible. Claude agreed: in such an example, the local operators are written with jax.numpy, and the discrete Green operator is the only opaque function. The remaining points belong to the example, not to the architecture:

  • the adapter (a dozen lines) is written in the example, and may move to an optional module of the library later; JAX is not a dependency of the library;

  • the solver is differentiated implicitly, in the example; whether the solvers of jax.scipy.sparse.linalg can be differentiated directly when their operator contains the adapter is to be checked by a prototype;

  • the example relies on the symmetry of the discrete Green operator, which must therefore become a property of its interface, guaranteed by a test for each scheme and preserved by the new core.

JAX thus becomes a use case, shown by an example, and not a backend; this is consistent with the abandonment of E7.

Claude’s report#

At the author’s request, the discussion was integrated into the Roadmap to v1.0:

  • new evolution E13. Automatic differentiation through an adapter (added at the end, so that the numbering does not change): context, adapter code, limits, consequence on the library (symmetry of the discrete Green operator as a property of the interface, with the check made on the current code), implementation problems (implicit differentiation of the solver, derivatives with respect to the reference medium), and recommendation: an example with JAX in milestone 0.5, once local operators are described as fields (E8), and the symmetry test from milestone 0.3 on;

  • E3: the last paragraph no longer states that automatic differentiation is out of reach with Cython, and refers to E13;

  • E12: symmetry is marked as a property of the interface, on which E13 relies;

  • milestone 0.5: the JAX example is added. Its placement in 0.5 is a proposal of Claude;

  • the introduction of Analysis of the proposed evolutions mentions E13.

The other mentions of JAX and of automatic differentiation in the Roadmap to v1.0 (Goals, E1, E5, E8, E10) were not modified: they were added to the list of the task Make the roadmap consistent with the decisions of 2026-09-25 (above). Note that the Goals (“GPU execution and automatic differentiation are not required, but the architecture should not rule them out”) are now consistent with the decisions as far as automatic differentiation is concerned; only GPU execution is ruled out.

2026-09-25 • The continuum Green operator in the new architecture#

Not a task: record of a discussion held in the console, started by the author with the question “what are the inputs and outputs of the function symbol(k)?” (see E4 of the Roadmap to v1.0). The discussion led to the decisions below, in this order; the last one reverses the recommendation of E3.

Decisions#

  1. Zero frequency. \(\hat\Gamma_0(\mathbf 0) = \mathbf 0\) is part of the definition of the Green operator, which acts on fields with zero mean. It is not a convenience value, and it does not depend on the loading. The macroscopic loading (imposed mean strain, mean stress, or mixed conditions) is handled by adapting the equation, not the Green operator. Claude had first argued that, under an imposed mean stress, the zero mode of the operator should be \(\mathbf C_0^{-1}\); the author objected that the corresponding term, \(\mathbf C_0^{-1} : (\boldsymbol\Sigma - \langle\boldsymbol\tau\rangle)\), belongs to the equation, which Claude agreed with.

  2. Apply, do not form the matrix. The primitive of a continuum Green operator is the application \(\hat{\boldsymbol\eta} = \hat\Gamma(\mathbf k) \cdot \hat{\boldsymbol\tau}\), computed in closed form, not a function symbol(k) that returns a matrix: the matrix is not needed in general, and forming it costs time and memory. The matrix can be recovered by applying the operator to the vectors of the canonical basis, which is enough for the tests. A notation such as symbol(k) @ tau would require an intermediate object (a matrix, or a matrix-free linear operator), and was not retained.

  3. One frequency at a time. Within a vectorized (NumPy) design, apply(k, tau) must receive the wave-vectors of the whole grid. Storing them costs about a quarter of a field in 3D elasticity (1.6 GB for a 512³ grid, against 6.4 GB for the Fourier coefficients of the polarization), and half of a field in 2D conductivity, whereas the current Cython code computes each wave-vector on the fly and stores nothing. Claude proposed workarounds (wave-vectors passed as a tuple of broadcastable components, evaluation by blocks), which the author found unconvincing: they are symptoms of the ban on loops over frequencies that comes with abandoning compiled code. The physics is therefore written for one wave-vector at a time, as in the mathematics and in the current code.

  4. Cython is kept. The author will write new physics mainly by themselves, within the library, and GPU execution is not a priority. Under these conditions, compiling new physics is not an obstacle, and Cython remains a good choice: the existing code works and serves as a reference, it is fast and allocates nothing, and most friction points of the Roadmap to v1.0 (stateful operators, Python subclasses silently ignored, restricted data model, and, to a large extent, the fragile build) are design problems, which can be fixed without changing the tool. This departs from the context of the task The road to v1.0 below, which asked that new physics be implementable without compiling.

Open points#

  • Modified wave-vectors that vanish at a nonzero discrete frequency (e.g. at the Nyquist frequencies, for some schemes): with decision 1, the Green operator is zero there. Check that this is the intended behaviour for each scheme, and not a side effect.

  • Representation of the local tensors (flattened Mandel–Voigt vectors, or full tensors), which fixes the sizes seen by apply.

  • Signature of the cdef method: raw pointers or memoryviews (slicing a memoryview at each frequency has a non-negligible cost in an inner loop); real or complex wave-vectors.

  • Dimension-generic code in Cython (E5): this is where Cython helps least.

  • A Numba prototype (generic kernel, truncated scheme, 2D conductivity, timed against the Cython code) was considered, then postponed: it may be done later, if the choice of Cython is to be confirmed by measurements.

Claude’s report#

At the author’s request, sections E3, E4 and E7 of the Roadmap to v1.0 were rewritten according to the above decisions.

  • E3: the analysis of the three options (NumPy, Numba, JAX) is kept, shortened, and completed with the reasons why the vectorized design was rejected; the recommendation is reversed: Cython is kept, and its friction points are fixed by design.

  • E4, renamed Stateless operators: the continuum Green operator exposes a stateless cdef method that applies its symbol at one wave-vector, without forming the matrix; \(\hat\Gamma(\mathbf 0) = \mathbf 0\) by definition; the discrete operators compute the wave-vectors on the fly. The NumPy example was replaced by a Cython sketch for conductivity, whose signature is explicitly left open.

  • E7 is marked as not adopted: the array API and the functional interface lose their purpose once Cython is kept and JAX is no longer a goal; the in-place semantics of apply(x, y) is kept. The section is kept, so that the numbering of the evolutions does not change.

The other parts of the roadmap were not modified, and are now inconsistent with these decisions:

  • Goals: “new physics … implementable in pure Python, without compilation” and “the architecture should not rule [GPU] out”;

  • friction point 2, which presents the per-frequency design as a problem;

  • E2: the recommendation of scipy.fft goes “through the array namespace, see E7”; with Cython kept, the choice between the current FFTW wrapper, pyFFTW and scipy.fft must be reconsidered;

  • E5 (NumPy/JAX arguments), E8 (vectorized constitutive functions, vmap), E10 (JAX solvers), E11 (“once Cython is gone”, pure Python package) and E12 (independence from the backend);

  • the milestones 0.3 (pure NumPy/SciPy core), 0.4 (removal of Cython and FFTW) and 0.6 (JAX backend), and two of the Decisions required from the author (default backend, acceptable slowdown of the pure Python implementation);

  • the introduction, already discussed in TO DISCUSS • Status of the roadmap.

The documentation builds without warning; docs/ was not modified.

Follow-up: milestones#

The milestones of the Roadmap to v1.0 were then discussed. The author approved Claude’s three recommendations:

  • the new core is developed alongside the current code (e.g. in a new subpackage), rather than by refactoring it in place, so that the current code remains an executable reference until the switch;

  • the FFT moves to scipy.fft as early as milestone 0.3: it is called from Python once per field, the loop over frequencies remaining in Cython, which removes the link to FFTW (hence setup.cfg) and eases the production of wheels; the loss of the fine tuning of FFTW (FFTW_MEASURE, wisdom) is to be measured by the benchmark;

  • the dimension-generic code (E5) is postponed after the switch; the apply method of the physics takes the dimension as a parameter from the start, so that E5 does not change it.

The Milestones section was rewritten accordingly: 0.2 is marked as done; 0.3 is the new core in Cython (E4, E6, scipy.fft, elasticity with the three existing schemes, benchmark with no regression as acceptance criterion); 0.4 is the switch (deletion of the current API and of the link to FFTW, wheels built with cibuildwheel, publication on PyPI); 0.5 is the second physics, in Cython, together with E5, E8 and the reference schemes; 0.6 becomes a finite strain prototype, with hand-written tangent operators, the JAX backend being dropped; 1.0 is unchanged. The closing paragraph now explains the three ordering choices above.

Follow-up: local operators#

The author then raised the question of the local part of the linear operator, e.g. \((\mathbf C - \mathbf C_0)^{-1} \cdot \boldsymbol\tau\). In the current code, it is what makes Janus particularly heavy: BlockDiagonalOperator2D/3D takes an array of local operators (AbstractOperator[:, :]), i.e. one Cython object per cell, with one indirect call per cell, and a microstructure described cell by cell rather than by its phases.

The situation differs from that of the Green operator. For the latter, vectorization required data to be created (the grid of wave-vectors, temporaries), which led to keeping Cython. For the local operator, the data already exist as fields (phase map, polarization), so that this objection does not apply. Moreover, the interface between both parts only consists of fields: the operator passed to the Krylov solver combines them in Python, with one call per field for each part, so that both parts need not be written with the same tool.

The author approved the following proposal:

  • a local operator is a function of fields, tau ↦ eta, acting on arrays of shape (*grid_shape, n) (E8);

  • the reference implementation is written in pure NumPy, for linear laws with few phases: a phase map and one (precomputed) matrix per phase, with a Python loop over the phases, not over the cells. No Cython, no object per cell, and temporaries limited to the size of each phase;

  • Numba is an optional dependency, not a foundation, for the cases where NumPy is not suitable: many phases (e.g. polycrystals with thousands of grains, where storing one matrix per cell costs \(n^2\) reals per cell, i.e. six times a field in 3D), and hyperelastic laws at finite strain (milestone 0.6), whose stress and tangent operator are naturally evaluated cell by cell. A @njit loop over the cells, reading the matrix of each cell from a table indexed by the phase, creates no temporary;

  • Cython is thus kept for the Green operator only, where it is required; for local operators, the goal of the task The road to v1.0 (prototyping without compiling) is recovered;

  • BlockDiagonalOperator2D/3D would disappear at milestone 0.4; the representation of hyperelastic laws is to be decided in milestone 0.6.

The Roadmap to v1.0 was not modified: E8 and milestones 0.4 and 0.5 are to be updated as part of the task Make the roadmap consistent with the decisions of 2026-09-25 (above).

Follow-up: scope of the constitutive laws#

Claude had mentioned nonlinear constitutive laws several times during the discussion, including laws with internal variables. The author stated that such laws are not among the goals of Janus. Finite strain is of interest, but only for hyperelasticity: the stress and the tangent operator derive from a strain energy density, and depend on the current deformation gradient only. There are no internal variables, hence no history to store and no local integration of evolution laws (plasticity, damage, viscosity… are out of scope).

The problem remains nonlinear (material and geometric nonlinearities), and still calls for a Newton–Krylov loop, with hand-written tangent operators.

Milestone 0.6, which had been rewritten earlier in the day, was corrected accordingly: “nonlinear constitutive laws” became “hyperelastic constitutive laws (no internal variables)”. The other mentions of nonlinear laws in the Roadmap to v1.0 (Goals, E8, E10) are left to the task Make the roadmap consistent with the decisions of 2026-09-25 (above).

Still inconsistent with the decisions: the Goals, friction point 2, the recommendation of E2 (which now contradicts the milestones: it refers to the array namespace of E7, and does not mention that the link to FFTW disappears), E5, E8, E10, E11, E12, the two decisions Default backend and Acceptable slowdown of Decisions required from the author, and the introduction. The documentation builds without warning; docs/ was not modified.

2026-09-26 • Status of the roadmap#

The introduction of Roadmap to v1.0 (sphinx/roadmap.rst, line 9) stated that “none of the evolutions described below has been implemented yet”, which was no longer true: E1 is done, and so is the continuous integration part of E11. The author sees no point in rewriting the roadmap in the past tense, since the history is kept in the present page, in README.rst and in git. Claude suggested correcting only this sentence.

Decision (2026-09-26, as part of the task Make the roadmap consistent with the decisions of 2026-09-25). Only the last sentence of the introduction is replaced: it now states that the roadmap was revised on 2026-09-25 and 2026-09-26 after the decision to keep Cython, that the revised sections carry a note, and that milestone 0.2 (E1, and the continuous integration part of E11) is done, the other evolutions having not been implemented yet. docs/ was not regenerated.

2026-09-23 • Continuous integration#

Set up continuous integration on GitHub Actions, with the current Cython code, as announced in section E11 and in milestone 0.2 of the Roadmap to v1.0. Its purpose is to build Janus from a clean clone, on Linux and Windows, at each push and once a week, so that the Cython implementation remains a reliable reference during the rewrite of milestone 0.3.

Proceed in the order below, one step at a time. Each step is a separate commit, made by the author: Claude does not commit, nor push. Report on each step in its own sub-paragraph of Claude’s report, and wait for validation before starting the next one.

Out of scope: building and deploying the documentation to GitHub Pages, packaging and publication on PyPI (milestone 0.4), macOS.

2026-09-23 • Step 1 — Make setup.cfg optional#

setup.py, environment.yml, sphinx/installation.rst, CLAUDE.md.

When setup.cfg has no [fftw] section, setup.py falls back to defaults: libraries = fftw3 on all platforms and, on Windows within a conda environment, include_dirs/library_dirs set to sys.prefix\Library\include/sys.prefix\Library\lib. An existing [fftw] section keeps precedence over these defaults, so that the precompiled DLLs from fftw.org remain usable. The workflow of step 2 then reduces to pip install, with no configuration file to generate.

Update the instructions accordingly: the header comment of environment.yml, sphinx/installation.rst and the Build section of CLAUDE.md state that setup.cfg is only needed outside conda, or to override the defaults.

Check on Linux: move setup.cfg aside, remove the compiled artifacts (git clean -Xfd janus/), then pip install --no-build-isolation -e . and run the tests. Windows cannot be checked by Claude on this machine: the author checks it, or step 2 does.

2026-09-23 • Step 2 — GitHub Actions workflow#

.github/workflows/tests.yml (new file).

  • Triggers: push, pull_request, a weekly schedule (to catch breakage caused by new versions of the dependencies, which environment.yml does not pin), and workflow_dispatch.

  • Matrix: ubuntu-latest and windows-latest.

  • Steps: actions/checkout; conda-incubator/setup-miniconda with environment.yml and the janus environment activated (shell: bash -el {0}); pip install --no-build-isolation -e .; python -m pytest tests; python -m sphinx -b doctest sphinx sphinx/_build/doctest.

The workflow only runs once pushed to GitHub, which the author does. Two difficulties are expected, to be reported rather than worked around silently:

  • the defaults channel of Anaconda may require the acceptance of its terms of service, which blocks non-interactive runs. If so, propose switching environment.yml to conda-forge (after checking that Python 3.14 and fftw are available there for both platforms), as a separate commit;

  • on Windows, setuptools must find the MSVC compiler of the runner.

Acceptance criterion: both jobs are green, with the same test count as locally (3043 passed, 111 skipped on Linux), and no failing doctest.

2026-09-23 • Step 3 — Badge#

README.rst.

Add the status badge of the workflow at the top of README.rst, next to the documentation badge.

Claude’s report#

Step 1 — Make setup.cfg optional#

  • setup.py: new function fftw_config(), which replaces the direct call to update_from_config({}, "fftw") in extensions_and_packages(). If setup.cfg provides at least one entry in its [fftw] section, these entries are used as before, and the defaults are ignored altogether (they are not merged, so that a hand-written configuration behaves exactly as it did). Otherwise, libraries = fftw3 and, on Windows within a conda environment (detected by the conda-meta directory of sys.prefix), include_dirs/library_dirs are set to sys.prefix\Library\include/lib. The message printed by python setup.py clean no longer says that setup.cfg is required.

  • Why nothing more is needed on Linux: the Python interpreter of the janus environment compiles with -isystem $PREFIX/include and links with -L$PREFIX/lib and -rpath $PREFIX/lib (checked with sysconfig), and the compiled _serial_fft module does load the libfftw3.so.3 of the environment, not the one of the system (checked with ldd). The same holds for macOS in principle, but was not checked.

  • environment.yml (header comment), sphinx/installation.rst (sections Configuration and Compilation with Miniconda and Visual Studio, step 3) and CLAUDE.md (Build) now state that setup.cfg is not needed within the janus environment, and when it must still be written.

Check on Linux: with setup.cfg moved aside and the compiled artifacts removed (git clean -Xfd janus/), pip install --no-build-isolation -e . succeeds, and the tests give 3043 passed, 111 skipped; the doctests (python -m sphinx -b doctest sphinx sphinx/_build/doctest) give 0 failures. setup.cfg was then put back. The Windows branch of fftw_config() was not run: it will be checked by the author, or by the Windows job of step 2.

Step 2 — GitHub Actions workflow#

New file .github/workflows/tests.yml, as specified. A few choices beyond the specification:

  • fail-fast: false: a failure on one platform does not cancel the job on the other, so that each run tells whether the problem is specific to one platform;

  • concurrency with cancel-in-progress: a new push to a branch cancels the run still in progress on that branch;

  • permissions: contents: read: the workflow only needs to read the repository;

  • a Show environment step (conda list), so that the versions of the dependencies are recorded in the log of each run. This is what makes a failure of the weekly run diagnosable: comparing with the log of the last successful run shows which package changed;

  • no setup.cfg is written: the build relies on the defaults of step 1.

The weekly run (Mondays, 04:00 UTC) only starts once the workflow is on master: GitHub runs scheduled workflows on the default branch only.

What was checked: the file is valid YAML, and the commands of the workflow were run by hand on a fresh clone of the branch (git clone, no setup.cfg, no compiled artifacts), in the janus environment: build OK, 3043 passed, 111 skipped, 0 failing doctest. The workflow itself could not be run: it will run when the author pushes the branch. The two expected difficulties (terms of service of the defaults channel, MSVC on Windows) can only be observed there.

Step 2 (continued) — Switch to conda-forge#

At the author’s request, the first of the two difficulties was removed before the first run, rather than waited for.

  • environment.yml: the only channel is now conda-forge. fftw is pinned to its nompi_* builds: conda-forge also publishes builds of FFTW linked against MPI (OpenMPI, MPICH), which Janus no longer needs.

  • .github/workflows/tests.yml: setup-miniconda installs Miniforge (miniforge-version: latest), whose only channel is conda-forge, and conda-remove-defaults: true makes sure that the defaults channel is never queried. There are no terms of service to accept.

  • sphinx/installation.rst: a note states that the packages come from conda-forge (which works with Miniconda as well as Miniforge), and that an environment created from the former environment.yml should be recreated rather than updated, so as not to mix channels.

What was checked:

  • both platforms resolve on conda-forge (conda create --dry-run with CONDA_SUBDIR set to linux-64 and win-64): Python 3.14.7 (the regular build, not the free-threaded one), Cython 3.3.0, NumPy 2.5.3, FFTW 3.3.11 nompi;

  • the Windows package of FFTW on conda-forge provides Library/include/fftw3.h and Library/lib/fftw3.lib (checked by downloading the package): the defaults of fftw_config() (step 1) apply unchanged;

  • on Linux, end to end: a fresh environment created from the new environment.yml (in a temporary prefix), a fresh clone without setup.cfg, python setup.py build_ext --inplace, then 3043 passed, 111 skipped, and 0 failing doctest. The compiled module loads the FFTW of the new environment (ldd). The temporary environment and clone were deleted.

The author’s own janus environment was not modified: it still comes from the defaults channel, and should be recreated as explained above.

After the push by the author, both jobs of the workflow are green on GitHub. This also validates the two points that could not be checked on this machine: the Windows branch of fftw_config() (step 1), and the detection of the MSVC compiler of the runner by setuptools.

Step 3 — Badge#

README.rst: the status badge of the workflow is placed before the documentation badge, on the same line. Both are now written as substitutions (|tests| |docs|), since two consecutive image directives would be rendered one below the other. The rendering was checked with docutils (no warning, both images in a single paragraph).

The badge reports the status of master (?branch=master), which is the reference for a visitor, not the status of the working branches. It will show no status until continuous_integration is merged into master; the weekly run will also start then.

2026-09-23 • Removal of the vestiges of distributed memory#

Now that the parallel code has been removed (see the branch MPI-ectomy), the classes of janus/fft/serial/ and janus/green.pyx still carry the attributes that used to locate a local slab within a domain-decomposed grid. They are now redundant: offset0 is always 0, idispl and odispl are always 0, global_shape0 == shape0, and global_ishape/global_oshape are equal to ishape/oshape. Remove them, as announced in section E1 of the Roadmap to v1.0.

Proceed one attribute at a time, in the order below, so that each step is a separate commit. Each step leaves the library in a working state: rebuild the extension modules (python setup.py build_ext --inplace) and run the tests before moving on. The order is not arbitrary — steps 2 and 4 remove the readers of the attributes that steps 3 and 5 delete.

Report on each step in its own sub-paragraph of Claude’s report, and wait for validation before starting the next one.

2026-09-23 • Step 1 — idispl and odispl#

janus/fft/serial/_serial_fft.pxd, _serial_fft.pyx.

Dead code: both are computed in __cinit__ from offset0, and read nowhere else in the code base. Pure deletion, no other file affected.

2026-09-23 • Step 2 — offset0 of the discrete Green operators#

janus/green.pyx.

Remove the offset0 attribute of DiscreteGreenOperator2D and 3D, which is read from transform.offset0 (or set to 0 when there is no transform). Three consequences:

  • in set_frequency, the bounds check on b0 becomes 0 <= b0 < shape0, like the checks on b1 and b2; the error message becomes the same as theirs, which leaves the text produced unchanged, since offset0 was interpolated as the lower bound and was 0;

  • in the c_apply of DiscreteGreenOperator2D/3D, b[0] = i0 + self.offset0 becomes b[0] = i0;

  • in the c_apply of TruncatedGreenOperator2D/3D, b0 = i0 + self.offset0 becomes b0 = i0.

This step must come before step 3, which removes the attribute that is read here.

2026-09-23 • Step 3 — offset0 of the FFT objects#

janus/fft/serial/_serial_fft.pxd, _serial_fft.pyx, examples/square_inclusion.py.

Once step 2 is done, the attribute is read nowhere in the library. Remove it, together with the offset0 parameter of the constructors of _RealFFT2D and _RealFFT3D. These constructors are called only by create_real_2D/create_real_3D, which are cdef functions: the public entry point janus.fft.serial.create_real(shape, flags) is unaffected.

examples/square_inclusion.py reads transform.offset0. The example is already broken (it depends on mpi4py and petsc4py) and carries a TODO header describing its repair: state there that the attribute no longer exists, but do not attempt the repair, which is a separate task.

2026-09-23 • Step 4 — global_shape0#

janus/green.pyx, CLAUDE.md.

global_shape0 is equal to shape0, which init_shapes sets just above its last use. Replace it with self.shape0 in the computation of s0 (DiscreteGreenOperator2D/3D) and in the wave-vectors of TruncatedGreenOperator2D/3D and FilteredGreenOperator2D/3D, then remove the attribute. FiniteDifferences2D/3D does not use it.

The constructors also read transform.global_ishape, to check the shape of the transform: switch that check to transform.ishape. Step 5 removes the attribute, so this step must come first.

In CLAUDE.md, delete the paragraph that presents offset0/global_shape0 as a pending simplification.

2026-09-23 • Step 5 — global_ishape, global_oshape and n0_loc#

janus/fft/serial/_serial_fft.pxd, _serial_fft.pyx, sphinx/fft_tutorial.rst, CLAUDE.md.

Once step 4 is done, these are read only by the documentation. Remove the two attributes and the n0_loc parameter of the constructors (which then take the shape alone), and drop the word global from the docstring of create_real.

In sphinx/fft_tutorial.rst, the four attributes documented for a serial transform are reduced to ishape and oshape: remove the two doctests on global_ishape/global_oshape, and the two sentences explaining that local and global shapes coincide in the serial case. In CLAUDE.md, the description of the FFT layer no longer mentions the vestigial attributes.

Whatever the step, the behaviour of the library must not change: the tests (3043 passed, 111 skipped) are the acceptance criterion, and no reference data in tests/data is to be regenerated.

Claude’s report#

Step 1 — idispl and odispl#

Both attributes were removed, as a pure deletion. Two files were modified.

  • janus/fft/serial/_serial_fft.pxd: in the declarations of _RealFFT2D and _RealFFT3D, the readonly ptrdiff_t line becomes isize, osize, offset0.

  • janus/fft/serial/_serial_fft.pyx: the two assignments of __cinit__ were deleted in each class (self.idispl/self.odispl, computed from self.offset0).

Before deleting, a search for idispl and odispl over the whole repository (excluding docs/ and the build artifacts) confirmed that the only remaining occurrences were these four lines and the description of the task in the present file: the attributes were written in __cinit__ and read nowhere — neither in janus/, nor in tests/, examples/ or sphinx/. No other file was affected.

The extension modules were rebuilt (python setup.py build_ext --inplace; all five .pyx files were re-cythonized, not only the modified one — the .c files present in the checkout were stale) and the tests were run: 3043 passed, 111 skipped, i.e. the expected baseline. No reference data was touched.

The changes are not committed, as usual.

Step 2 — offset0 of the discrete Green operators#

The attribute was removed from DiscreteGreenOperator2D and DiscreteGreenOperator3D; only janus/green.pyx was modified. The three announced consequences were applied, in both classes:

  • the declaration cdef int offset0 and its two assignments in __cinit__ (transform.offset0 when a transform is given, 0 otherwise) are gone. The attribute was declared cdef, not cdef readonly: it was never visible from Python, so this is not a breaking change for the public API;

  • in set_frequency, the bounds check on b0 is now if (b0 < 0) or (b0 >= self.shape0), and raises the same message as the checks on b1 and b2;

  • in c_apply, b[0] = i0 + self.offset0 becomes b[0] = i0 (DiscreteGreenOperator2D/3D), and b0 = i0 + self.offset0 becomes b0 = i0 (TruncatedGreenOperator2D/3D).

global_shape0 was left untouched, as it belongs to step 4; so was the check on transform.global_ishape.

After rebuilding, the tests give the expected baseline: 3043 passed, 111 skipped, with the reference data unchanged.

The out-of-bounds branch of set_frequency turned out not to be covered by the test suite (tests/test_greenop.py only exercises the continuum operators), so the invariance of the error message was checked by hand, on a TruncatedGreenOperator2D of shape (8, 8), built both with and without a transform. In both cases, set_frequency raises index must be >= 0 and < 8 (was -1) (resp. (was 8)) for an out-of-range b0, which is the text produced before the change, and the message is now identical to the one raised for an out-of-range b1. A valid index is still accepted.

The changes are not committed.

Step 3 — offset0 of the FFT objects#

Three files were modified.

  • janus/fft/serial/_serial_fft.pxd: in _RealFFT2D and _RealFFT3D, the readonly ptrdiff_t line is reduced to isize, osize. Unlike the offset0 of the Green operators (step 2), this one was readonly, hence visible from Python: its removal is a breaking change for any code that read transform.offset0. This is the intended outcome, announced in section E1 of the Roadmap to v1.0.

  • janus/fft/serial/_serial_fft.pyx: the offset0 parameter was dropped from the __cinit__ of both classes, together with the assignment self.offset0 = offset0. The two call sites were updated accordingly: _RealFFT2D(n0, n1, n0, 0) becomes _RealFFT2D(n0, n1, n0), and _RealFFT3D(n0, n1, n2, n0, 0) becomes _RealFFT3D(n0, n1, n2, n0). A search confirmed that these two lines, in the cdef functions create_real_2D/create_real_3D, are the only places where the constructors are called; the public entry point janus.fft.serial.create_real(shape, flags) is unchanged, and so is the n0_loc parameter, which belongs to step 5.

  • examples/square_inclusion.py: the TODO header now states that transform.offset0 no longer exists at all, and that the two references to it in the body of the example (self.offset0 = transform.offset0 and the slice ops[:imax - self.offset0, :imax]) are therefore dead. The repair itself was not attempted, as agreed: the example still imports mpi4py, petsc4py and janus.fft.parallel, and does not run.

After offset0 was removed, no occurrence of it remains anywhere under janus/.

The extension modules were rebuilt and the tests run: 3043 passed, 111 skipped, the expected baseline, with the reference data unchanged. tests/test_fft.py builds its transforms through the public create_real and exercises r2c/c2r round trips, so the constructors are covered; the attribute itself was read by no test.

Step 4 — global_shape0#

global_shape0 disappears from DiscreteGreenOperator2D and 3D. In janus/green.pyx:

  • the declaration cdef int global_shape0 and its two assignments in __cinit__ (transform.global_ishape[0], or shape[0] without a transform) were deleted;

  • the twelve readers now use self.shape0: the computation of s0, the wave-vector of TruncatedGreenOperator2D/3D (if 2 * b0 > self.shape0 and the corresponding self.k[0], in both c_set_frequency and c_apply), and the first component of the wave-vectors of FilteredGreenOperator2D/3D. FiniteDifferences2D/3D was indeed not concerned;

  • the check on the shape of the transform now reads transform.ishape, in the condition and in the error message, which frees step 5;

  • the comment above s0 in DiscreteGreenOperator2D described n[i] as the size of the global grid; it now reads like its 3D counterpart, which never mentioned the global grid.

The substitution is legitimate because init_shapes, called just above the computation of s0, sets shape0 to exactly the value that global_shape0 received: transform.ishape0 (equal to transform.global_ishape[0] in the serial case) or shape[0].

Both replacements are covered by the test suite. The mismatched-transform branch is exercised by tests/test_discrete_green_operator.py, whose parameters for test_init_invalid_params include a grid of shape (9, 9) with a transform of shape (8, 9) and (9, 8); and the wave-vectors are precisely what the reference data of tests/data check. Tests: 3043 passed, 111 skipped, reference data unchanged.

In CLAUDE.md, the paragraph presenting the offset0/global_shape0 pair as a pending simplification was deleted.

One residue is left on purpose: in the FFT layer paragraph of CLAUDE.md, the serial transforms are still described as exposing ishape/oshape “alongside the vestigial global_ishape/global_oshape and offset0”. Since step 3, offset0 no longer exists; that sentence is rewritten by step 5, which removes the last two attributes as well.

Step 5 — global_ishape, global_oshape and n0_loc#

The last vestiges are gone. Four files were modified.

  • janus/fft/serial/_serial_fft.pxd: in both classes, the readonly tuple line is reduced to ishape, oshape.

  • janus/fft/serial/_serial_fft.pyx: the four assignments of global_ishape/global_oshape were deleted, and the constructors now take the shape alone — __cinit__(self, n0, n1) and __cinit__(self, n0, n1, n2). Wherever n0_loc was used (ishape0 and oshape0), n0 is used instead; the call sites in create_real_2D/create_real_3D lose their repeated argument (_RealFFT2D(n0, n1, n0) becomes _RealFFT2D(n0, n1)). In the docstring of create_real, shape is now “the shape of the input data”.

  • sphinx/fft_tutorial.rst: the list of attributes is reduced to ishape and oshape, described without the local/global emphasis, which no longer opposes anything; the two doctests on global_ishape/global_oshape and the two sentences on the coincidence of local and global shapes were removed.

  • CLAUDE.md: the FFT layer paragraph now says that the transforms expose ishape/oshape (and isize/osize), with no mention of the vestigial attributes. This also settles the residue reported in step 4.

After rebuilding, the tests give 3043 passed, 111 skipped, with the reference data unchanged. The doctests of the documentation were run as well (python -m sphinx -b doctest, into a temporary directory): fft_tutorial passes its 30 tests, which covers the rewritten section.

Two mentions were deliberately left alone.

  • README.rst documents the renaming of the FFT attributes in its History of major changes, under the date 2015-02-23 (shape → global_ishape, and the addition of global_oshape). This is a historical record of what happened in 2015, not a description of the current API: rewriting it would falsify the history. The removal is already recorded in the same file, in the entry of 2026-09-15 on the MPI-ectomy.

  • sphinx/roadmap.rst lists these attributes twice, as friction point 6 and in the description of milestone 0.2, i.e. as the work to be done. They now are done; the roadmap will have to be updated when the milestone is closed, which is beyond the scope of this task.

Unrelated observation, found while running the doctests: sphinx/operators.rst (line 81) has one failing doctest, np.sqrt(np.sum((yy - y)**2)), which expects 0.0 but gets np.float64(0.0). This is the NumPy 2 scalar representation, has nothing to do with the present task, and does not affect the HTML build (the doctest builder is not run by make ghpages).

Suggestions#

On the interactions:

  • the form of this task is worth reusing for the rest of the roadmap. Splitting it into numbered steps, each with the list of files it touches, the consequences to expect, the reason for its rank in the order, and a global acceptance criterion (the test count), left no room for interpretation: each step was a mechanical edit followed by a check. The validation between steps also kept the reviewing effort proportionate to what had just changed;

  • one thing the steps could state explicitly: whether Claude should commit. The introduction says “so that each step is a separate commit”, while the standing rule of How to update this page is never to commit. The commits were made by the author, which is consistent, but a word in the task would remove the ambiguity.

Follow-ups for the code base, in decreasing order of usefulness:

  • sphinx/roadmap.rst still lists offset0, global_shape0, global_ishape, global_oshape and n0_loc as work to be done, in friction point 6 and in milestone 0.2. Both passages could now be written in the past tense, when the milestone is closed;

  • examples/square_inclusion.py is the only example of the symmetric formulation, and it no longer runs. Its TODO header now describes its repair completely, including the two dead references to offset0: the rewrite in serial form would make a well-defined task;

  • the failing doctest of sphinx/operators.rst (see above) could be fixed, either by expecting np.float64(0.0), or by wrapping the result in float(...), which keeps the output stable across NumPy versions;

  • the out-of-bounds branch of set_frequency in the discrete Green operators is not covered by any test (this was found in step 2, and checked by hand). A short test on the three indices would protect the bounds checks, which are the only remaining place where the shape of the grid is interpreted.

2026-09-15 • Planning the MPI-ectomy#

I am ready to start working on the removal of the MPI dependency.

I will work in a dedicated branch: show me how to proceed.

Then, draft a plan for this task.

Claude’s report#

Should a branch be created?#

Yes, for three reasons.

  • The task spans several commits and introduces breaking changes to the public API (offset0, global_ishape… disappear). master should remain usable in the meantime.

  • master is the published branch: GitHub Pages serves master:/docs. On a branch, sphinx/ can be modified freely.

  • The repository has no tags at all. Before deleting anything, the last commit that includes MPI should be tagged, so that it remains available as a reference (this is also part of milestone 0.2 of Roadmap to v1.0).

Procedure#

At the time of writing, master has no local changes and is up to date with origin/master. From the root of the project:

  1. Tag the last commit with MPI (annotated tag), and push the tag:

    git tag -a last-mpi -m "Last version with the MPI-enabled parallel FFT"
    git push origin last-mpi
    

    The name last-mpi is only a suggestion; a version number (e.g. v0.1) would also do.

  2. Create the branch, switch to it, and (optionally) push it to GitHub, as a backup and to allow a pull request later:

    git switch -c remove-mpi
    git push -u origin remove-mpi
    
  3. Commit on the branch as the work progresses.

  4. Once the work is done, merge the branch into master, either through a pull request on GitHub, or locally:

    git switch master
    git merge --no-ff remove-mpi
    

    Regenerate docs/ only after the merge.

Draft plan#

The work proceeds from the outside in, so that the serial tests pass after each step. Before starting, record a baseline with python -m pytest tests (last recorded result: 3043 passed, 111 skipped). Each step could be one commit.

  1. Delete the MPI code (no change for the serial code).

    • Delete janus/fft/parallel/, tests/parallel/, sphinx/parallel_fft_tutorial.py and examples/fftw_python_benchmark_mpi.py.

    • examples/square_inclusion.py uses MPI and PETSc: rewrite it for serial use, or delete it.

    • setup.py: remove mpicc_show() and extensions_and_packages_with_mpi() (lines 75–128), and the [fftw_mpi] configuration.

    • pytest.ini: remove parallel from norecursedirs.

    • sphinx/api.rst: remove the janus.fft.parallel section (this also removes the two warnings of the documentation build).

  2. Simplify the serial FFT (breaking change). In janus/fft/serial/_serial_fft.pyx and _serial_fft.pxd, remove n0_loc, offset0, idispl, odispl, global_ishape and global_oshape from _RealFFT2D and _RealFFT3D.

  3. Simplify janus/green.pyx. Remove global_shape0 and offset0 from the discrete Green operators, and use shape0 instead (around lines 92–155, 199, 253–321, 371, 436–550, 616 and 738), together with the checks of transform.global_ishape. tests/test_operators.py also contains a few matching names, to be checked (some may be unrelated uses of the word “parallel”). Recompile with python setup.py build_ext --inplace. The reference data (tests/data/*.npz) must not be modified: they are precisely what detects a mistake in this step.

  4. Update the documentation: README.rst and sphinx/introduction.rst (“fully parallelized”), sphinx/installation.rst and sphinx/fft_tutorial.rst (both mention MPI extensively), CLAUDE.md, and the comment on mpi4py in environment.yml.

What was checked#

The plan is based on a search for mpi, parallel, offset0, global_ and n0_loc in the sources (304 occurrences in 26 files, excluding docs/ and the build artifacts), and on the current state of the repository (git branch -a, git tag, git status). No command of the procedure was run: no tag and no branch were created, and no code was modified.

Follow-up: tag and branch created by the author#

The author then created the tag Farewell_MPI (on commit 161dc75) and the branch MPI-ectomy, both pushed to GitHub, and added a corresponding entry to the History of major changes of README.rst. At the author’s request, Claude suggested language improvements to this entry (in the console only; README.rst was not modified by Claude).

The author validated this report on 2026-09-15, and the task was marked as done.

2026-09-11 • The road to v1.0#

The goal of this task is to write a roadmap to v1.0 of Janus

Context#

Janus was initially built to target both prototyping and large simulations.

Large simulations has now become obsolete, because new developments in the community will soon offer excellent alternatives. So Janus should really evolve into a more flexible library, easily maintanable and extensible.

The architecture should reduce as much friction as possible at installation and allow for rapid prototyping of new ideas. More precisely

  • implementation of new discretizations

  • implementation of new physics (e.g. Darcy, finite strain solid mechanics, etc.)

should be possible without having to compile with Cython, which is not possible at the time being I think, even for experimental (sub-optimal) code.

I have listed below a few evolutions I have in mind. Analyse each of them in terms of gains, losses, consequences on the code, implementations problems, …

With the above context in mind, try to come up with supplementary evolutions that you think might improve the code’s flexibility, and go through the same analysis for each of your suggestions. At this stage, breaking changes in the code would be allowed.

Report briefly in this file, and write the detailed analysis in a new chapter of these docs (file called roadmap.rst); add the corresponding entry in the index.rst file.

Possible evolutions#

Removal of the MPI dependency#

MPI is no longer useful if we do not target large simulations.

The gain would be considerable

  • installation

  • the structure of some objects: no need to encode the global shape and the local shape of an operator

Interfacing with FFTW#

At the time of creation of Janus, interfacing with FFTW was done “manually” through a hand-crafted Cython file. Nowedays, pyFFTW seems to be the de facto module (with presumably a robust installation procedure).

Replacing Cython with other (dynamic) tools#

The compilation required by Cython adds some friction. I am under the impression that tools such as Numba, JaX are mature tools that could (partly) replace Cython. I am ready to pay a little price in terms of speed if it is justified by a significant gain in flexibility.

Claude’s report#

Before starting, Claude asked four questions; the author answered that GPU execution and automatic differentiation are nice to have, that any dependency distributed as binary wheels is acceptable, that the analysis should not be backed by benchmarks, and that the roadmap should include ordered milestones.

The detailed analysis is in the new chapter Roadmap to v1.0 (file sphinx/roadmap.rst, added to sphinx/index.rst after the API reference). It is based on a complete reading of the code base, and on the current state of the candidate dependencies on PyPI. In brief:

  • Friction points. Seven were identified. The most important one: all the methods that do the actual work are cdef methods, so that Python subclasses are silently ignored inside the library. For instance, a Python local operator used in a BlockDiagonalOperator2D leaves the output untouched; this was checked with the current build. The other ones: operators are scalar and stateful (one call per frequency, impossible to transpose to Python); everything is duplicated for 2D and 3D; the filtered discretization is hard-coded for elasticity; the data model is restricted (Mandel–Voigt vectors, float64, real symbols); local and global shapes leak from MPI into the serial code; the build chain is fragile.

  • Evolutions proposed by the author. Remove MPI: yes, first (cheap, and it reduces the code to be ported). FFTW: rather than making pyFFTW a hard dependency, use scipy.fft by default, with pyFFTW as an optional accelerator through the scipy.fft backend mechanism. Cython: replace it entirely, first by a pure NumPy/SciPy implementation written in functional style, then by an optional JAX backend (fusion, GPU, automatic differentiation); Numba is not recommended as a foundation, because it does not solve the extensibility problem.

  • Additional evolutions (E4 to E12). Vectorized, stateless operators (the Green operator as a function of an array of wave-vectors); dimension-generic code; separation of discretizations (weighted modified wave-vectors) and physics; array API and functional interface; local operators as fields (phase maps, constitutive functions, autodiff tangents); generic tensor representations (vectors, full tensors for finite strain); thin solver adapters; pure Python packaging and continuous integration; testing strategy based on the reference data and on mathematical properties.

  • Milestones. 0.2 clean-up (MPI removal, continuous integration); 0.3 new core alongside the Cython code, validated against the reference data and benchmarked; 0.4 switch (Cython and FFTW removed, pure Python packaging); 0.5 extensibility (second physics in pure Python); 0.6 backends (JAX, autodiff, finite strain prototype); 1.0 stabilization.

  • Decisions required from the author are listed at the end of the chapter. In particular, the name janus is already taken on PyPI (by an unrelated package), so a distribution name must be chosen before publication.

The speed estimates of the chapter are not backed by benchmarks, as agreed; a benchmark is part of milestone 0.3. No code was modified. The documentation builds without new warnings.

2026-09-11 • Updating the online docs#

Report on the procedure for compiling the sphinx docs locally and updating the Github pages accordingly (the project lives in the following repo: sbrisard/janus while the github pages are: https://sbrisard.github.io/janus/).

Claude’s report#

Current setup#

  • The HTML docs are versioned in the docs/ directory of the master branch (since 2018), with a docs/.nojekyll file, so that GitHub does not process the files with Jekyll (which would ignore the _static, _sources… directories). There is no gh-pages branch, and no GitHub Actions workflow. GitHub Pages is therefore most likely configured as Deploy from a branch, master, /docs. This could not be checked directly (the corresponding GitHub API requires authentication); it can be checked in Settings → Pages of the repository.

  • The online docs are exactly the content of docs/: they were last updated on 2019-08-20 (commit 811359f), with Sphinx 2.1.2. In particular, they do not contain the present page, nor the new installation procedure.

  • sphinx/make.bat html builds the docs directly into ../docs (the doctrees go to sphinx/_build/doctrees; both sphinx/_build and docs/.buildinfo are git-ignored). By contrast, sphinx/Makefile (Linux, macOS) builds into sphinx/_build/html, and the files must then be copied to docs/.

Procedure#

  1. Activate the janus environment, where Janus must be compiled and installed (see Installation on a windows machine): autodoc imports the compiled modules.

  2. Empty the docs/ directory (from the root of the project, in PowerShell). make.bat html does not remove files that Sphinx no longer produces; without this step, obsolete files would accumulate in docs/. Since the sphinx.ext.githubpages extension was added (see follow-up below), docs/.nojekyll is recreated by the build, and the whole directory can be emptied:

    Get-ChildItem -Force docs | Remove-Item -Recurse -Force
    
  3. Build the docs, from the sphinx/ directory. make.bat clean deletes the cached doctrees, which forces a complete rebuild:

    cd sphinx
    .\make.bat clean
    .\make.bat html
    

    Equivalently, from the root of the project: python -m sphinx -b html -E -d sphinx/_build/doctrees sphinx docs.

  4. Check the result: open docs/index.html in a browser, and review the changes with git status docs.

  5. Commit the docs/ directory, and push to master:

    git add -A docs
    git commit -m "Update HTML docs"
    git push
    

    GitHub Pages then redeploys the site automatically (usually within a few minutes). The deployment can be followed in the Actions tab of the repository (pages build and deployment).

What was checked#

Steps 2 and 3 were not run as such on docs/, and step 5 was not run at all (no commit, no push). The following equivalent operations were performed instead.

  • A complete build (python -m sphinx -b html -E) in an empty temporary directory succeeds (2 warnings, both related to janus.fft.parallel). Compared to the current docs/, it adds 8 files (claude.html, _sources/claude.rst.txt, 2 files in _downloads/, 4 JavaScript/SVG files in _static/) and makes 4 files obsolete (jquery*.js and underscore*.js in _static/), which step 2 removes.

  • Mirroring this build into a copy of docs/ with robocopy <build> docs /MIR /XF .buildinfo .nojekyll (an alternative to steps 2 and 3) gives the same result, and keeps .nojekyll. Note that robocopy returns non-zero exit codes on success (codes 1 to 7), which may confuse scripts.

  • make.bat html was also run as is, and wrote into docs/: this is how Claude found out that it targets ../docs. Since this task only asked for a report, the docs/ directory was then restored to its committed state (git restore docs, removal of the new files, of docs/.buildinfo and of sphinx/_build). docs/ is currently unchanged.

Points to be aware of#

  • The API of janus.fft.parallel is absent from the docs built under Windows (the parallel extension is not compiled). This was already the case for the current online docs.

  • The present page (claude.rst) will be published. It contained an absolute local path, in the report of Installation on a windows machine (replaced since, see follow-up below).

  • The generated HTML files are versioned: each update of the docs adds all modified HTML files to the history of the repository.

Follow-up: suggestions 2 and 4 applied#

At the author’s request, suggestions 2 and 4 below were applied.

  • sphinx.ext.githubpages was added to the extensions of sphinx/conf.py. A complete build in a temporary directory succeeds (still 2 warnings, both related to janus.fft.parallel), and now produces a .nojekyll file in the output directory. Step 2 of the above procedure was updated accordingly: the whole docs/ directory can now be emptied before the build. The extension would also create a CNAME file if html_baseurl pointed to a custom domain, which is not the case here.

  • In the report of Installation on a windows machine, the absolute local paths of the setup.cfg example were replaced by C:\path\to\miniconda3\envs\janus\Library\…. No other absolute local path remains in sphinx/.

Follow-up: inconsistency between Makefile and make.bat#

Both files were generated by sphinx-quickstart on 2013-09-17 (commit e2b3e81), for Linux/macOS (Makefile) and Windows (make.bat) respectively. Originally, the html target of both files built the docs into _build/html (i.e. sphinx/_build/html today). When the HTML docs were moved to docs/ to be served by GitHub Pages (commit f0f32ee, 2018-07-13, which also renamed the source directory docs/ → sphinx/), the html target of make.bat was changed to build into ../docs, but Makefile was not modified. As a consequence:

  • under Windows, make.bat html updates docs/ directly (and the changes show up in git status);

  • under Linux/macOS, make html builds into sphinx/_build/html, which is git-ignored: docs/ is left untouched, and nothing shows up in git status. The files must then be copied to docs/ by hand (without .buildinfo), which is easily forgotten.

In both files, all other targets (dirhtml, latex, epub…) still build into _build/, and clean only empties _build/ (the doctrees), never docs/. Both files also contain leftovers from another project: the qthelp and devhelp targets refer to HashTri (e.g. HashTri.qhcp) instead of Janus. Finally, both use the old sphinx-quickstart template, which lists every builder explicitly; current versions of sphinx-quickstart generate much shorter files, based on sphinx-build -M (“make mode”).

Possible fixes, from the smallest to the largest change:

  1. Change the html target of Makefile to build into ../docs, as make.bat does (two lines). The HashTri leftovers can be fixed at the same time.

  2. Replace both files with those generated by the current sphinx-quickstart (make mode), and add a dedicated target (e.g. ghpages) that empties docs/ and builds into it. This must be done twice (make and batch syntax).

  3. Remove both files, and document a single command, identical on all platforms, run from the root of the project:

    python -m sphinx -b html -E -d sphinx/_build/doctrees sphinx docs
    

    Emptying docs/ beforehand is still platform-dependent (rm -rf docs/* vs. PowerShell); a small Python script (e.g. scripts/build_docs.py) could perform both steps on all platforms.

Claude would recommend c: the docs are only built as HTML, for GitHub Pages, so that the many other targets of the make files are not needed, and a single command (or script) avoids maintaining two files in two syntaxes. None of these fixes was applied.

Follow-up: options b and c applied#

The author chose to combine b and c: the make files are updated according to b (the author wants to build the PDF version of the docs from time to time), but the procedure that is documented is c. This follow-up supersedes steps 2 and 3 of the above procedure.

Changes:

  • scripts/empty_docs.py (new): empties docs/, except docs/.nojekyll. The docs/ directory is located relative to the script (at the root of the project), not relative to the current directory, so that the script cannot empty another directory by mistake.

  • sphinx/Makefile and sphinx/make.bat were replaced by the files generated by the current sphinx-quickstart (Sphinx 9.1, “make mode”: all targets are forwarded to sphinx-build -M), with one additional target, ghpages, which runs scripts/empty_docs.py, then builds the HTML docs from scratch into ../docs. This fixes the inconsistency between both files, as well as the HashTri leftovers. Note the change of behavior: make.bat html now builds into sphinx/_build/html, like make html; it no longer writes into docs/. make.bat was saved with CRLF line endings (git stores it with LF, as before).

  • sphinx/installation.rst: new section Build the documentation, which documents the two commands of option c (run from the root of the project):

    python scripts/empty_docs.py
    python -m sphinx -b html -E -d sphinx/_build/doctrees sphinx docs
    

    followed by the commit and push of docs/. The make files are not mentioned.

  • CLAUDE.md: the note on docs/ in Repository layout notes now gives the same commands (and mentions the ghpages target), and says that docs/ should only be regenerated on request, since it is the published site.

Tests (all performed on a copy of sphinx/, scripts/ and docs/ in a temporary directory; the actual docs/ directory was not modified):

  • The documented commands (option c): docs/ is emptied, .nojekyll is kept, the obsolete files (jquery*.js, underscore*.js) are removed, and the build succeeds (2 warnings, related to janus.fft.parallel).

  • make.bat (help, including the description of the ghpages target), make.bat ghpages (same result as the documented commands) and make.bat html (builds into _build/html) work as expected.

  • sphinx/Makefile was not tested: make is not available on this machine.

  • make.bat latexpdf (TeX Live 2026 is installed on this machine) fails, for a reason unrelated to the make files: with the default LaTeX engine (pdflatex), and the latex_elements of sphinx/conf.py (which empty inputenc and fontenc), LaTeX stops on a Unicode character (δ, U+03B4). With -D latex_engine=xelatex, the PDF is produced, but latexmk then fails on the index, because Sphinx uses xindy with xelatex, and xindy fails on this machine. With -D latex_engine=xelatex -D latex_use_xindy=0 (makeindex is then used), the build succeeds: sphinx/_build/latex/janus.pdf, 66 pages, no missing character. sphinx/conf.py was not modified (see suggestions).

  • Note that make.bat returns exit code 0 even when the build fails (this is also the case of the template generated by sphinx-quickstart): the output must be read.

Follow-up: PDF settings added to conf.py#

At the author’s request, latex_engine = 'xelatex' and latex_use_xindy = False (with a comment explaining the latter) were added to sphinx/conf.py, just before latex_elements, which was left unchanged. On a copy of sphinx/ in a temporary directory, make.bat latexpdf (without any -D option) now succeeds: _build/latex/janus.pdf, 66 pages, no missing character. The HTML build is unaffected (2 warnings, related to janus.fft.parallel).

Follow-up: latex_elements removed from conf.py#

At the author’s request, the latex_elements overrides were reviewed. The dictionary set preamble, inputenc, fontenc and utf8extra to empty strings. The last one was added in 2016 (commit 18071f2, Remove \DeclareUnicodeCharacter), before Sphinx offered the latex_engine option (Sphinx 1.5): these overrides most likely allowed the generated .tex file to be compiled with xelatex by hand, by removing the pdflatex-specific parts of the preamble.

Now that latex_engine = 'xelatex' is set, Sphinx adapts these entries itself, and the overrides are either redundant or counterproductive:

  • preamble and inputenc: the defaults are already empty strings (with xelatex, for the latter);

  • fontenc: with xelatex, the default loads fontspec explicitly (\usepackage{fontspec} and \defaultfontfeatures…); the override removed these lines (fontspec was still loaded indirectly, by polyglossia);

  • utf8extra: with xelatex, the default makes the non-breaking space (U+00A0) behave as ~; the override removed this.

The whole latex_elements dictionary was therefore removed from sphinx/conf.py. On a copy of sphinx/ in a temporary directory, make.bat latexpdf succeeds: 66 pages, no missing character. The only differences in the preamble of the generated janus.tex are the three lines listed above (fontspec, \defaultfontfeatures and non-breaking space), which are now present.

Suggestions#

  • Applied (options b and c), see above. Make sphinx/Makefile consistent with sphinx/make.bat (build into ../docs), or replace both by a single documented command.

  • Applied, see above. Add the sphinx.ext.githubpages extension to sphinx/conf.py: it creates .nojekyll in the output directory automatically, so that docs/ can be emptied without special care.

  • In the longer term, a GitHub Actions workflow could build the docs on each push and deploy them to GitHub Pages. The generated HTML files would then no longer be versioned, and building under Linux (with MPI) would include the API of janus.fft.parallel. This requires compiling Janus in the workflow.

  • Applied, see above. Replace the absolute local path in the report of Installation on a windows machine by a generic one (C:\path\to\miniconda3\…) before publishing.

  • Applied, see above. To build the PDF version of the docs, add latex_engine = 'xelatex' and latex_use_xindy = False to sphinx/conf.py (tested with TeX Live 2026, see above). The latex_elements overrides (empty inputenc, fontenc and utf8extra) could then be reviewed: they seem to date from an earlier attempt at supporting Unicode characters.

2026-09-11 • Automatic creation of environments#

Following your suggestion, add an environment.yml file, to create the conda environment in one command.

This environment should also include the packages that are required to compile the Sphinx docs.

Claude’s report#

Claude created the file environment.yml at the root of the project. It defines the janus environment (channel defaults, as the existing environment), with the following packages: python=3.14, pip, setuptools, cython, fftw (build), numpy (run), pytest (tests) and sphinx (documentation). The environment is created with:

conda env create -f environment.yml
conda activate janus

and an existing environment is synchronized with the file with:

conda env update -n janus -f environment.yml

Only the Python version is pinned; the other packages take the latest version available in the channel.

The documentation only requires sphinx: all extensions listed in sphinx/conf.py are bundled with Sphinx (including sphinx.ext.napoleon), the default theme (alabaster) is installed as a dependency of Sphinx, and the tutorials only include static figures and source files (literalinclude), which are not executed. Note however that autodoc imports Janus, which must therefore be compiled and installed first.

Janus itself is not installed by environment.yml: the build requires setup.cfg and the --no-build-isolation flag, neither of which can be expressed in the pip section of an environment file. The comments at the top of the file recall the remaining steps, and warn against adding mpi4py on Windows.

The file was checked as follows.

  • conda env create -f environment.yml -n janus-envcheck --dry-run: the environment resolves (Sphinx 9.1.0).

  • conda env update -n janus -f environment.yml: this added Sphinx to the existing janus environment, and upgraded cython (3.2.5 → 3.2.9) and fftw (3.3.10 → 3.3.11). The serial tests still pass (3043 passed, 111 skipped).

  • python -m sphinx -b html -E sphinx <temporary directory>: the build succeeds, with 3 warnings. The _static directory listed in html_static_path does not exist (1 warning), and janus.fft.parallel cannot be imported by autodoc, since the parallel extension is not built (2 warnings). The documentation of this module is therefore missing from the API page. The docs/ directory was not modified.

Follow-up: first two suggestions applied#

At the author’s request, the first two suggestions below were applied.

  • sphinx/requirements.txt was deleted. In sphinx/conf.py, the test on sphinx.__version__ was removed, and sphinx.ext.napoleon was added directly to the list of extensions.

  • html_static_path was removed from sphinx/conf.py, rather than creating an empty sphinx/_static directory (an empty directory cannot be tracked by git; besides, _static is listed in sphinx/.gitignore).

The documentation was built again: the build succeeds, with 2 warnings (both related to janus.fft.parallel, see above). The docstrings are still processed by napoleon (the Parameters and Returns sections are rendered in the API page).

Follow-up: proposed text for sphinx/installation.rst#

The following sub-section is proposed as a replacement for the current Compilation with Anaconda and Visual Studio sub-section of sphinx/installation.rst. It has not been applied. It summarizes the procedure of the task Installation on a windows machine, which was only tested under Windows (hence its location in the Windows section):

Compilation with Miniconda and Visual Studio (recommended)
----------------------------------------------------------

This procedure was tested with Miniconda, Python 3.14 and Visual Studio Build Tools 2026.

1. Install the `Visual Studio Build Tools`_, with the *Desktop development with C++* workload. The compiler is located automatically by ``setuptools``: there is no need to use a *Developer Command Prompt*.

2. From the root of the project, create and activate the ``janus`` environment. It provides all the dependencies of Janus (including FFTW), as well as the packages that are required to run the tests and build the documentation::

     conda env create -f environment.yml
     conda activate janus

   To synchronize an existing environment with ``environment.yml``, use ``conda env update -n janus -f environment.yml`` instead.

3. Create the ``setup.cfg`` file. FFTW is installed in the ``Library`` subdirectory of the environment, whose path is printed by ``echo %CONDA_PREFIX%``. Environment variables are not expanded in ``setup.cfg``: this path must be written in full::

     [fftw]
     include_dirs = C:\path\to\miniconda3\envs\janus\Library\include
     library_dirs = C:\path\to\miniconda3\envs\janus\Library\lib
     libraries = fftw3

   Note that, unlike the precompiled binaries downloaded from fftw.org, the library provided by conda is called ``fftw3`` (without the ``lib`` prefix).

4. Install Janus in development (editable) mode::

     pip install --no-build-isolation -e .

   The ``--no-build-isolation`` flag ensures that the versions of Cython and setuptools installed in the environment are used for the build (otherwise, pip downloads the latest versions from PyPI).

   After modifying a ``*.pyx`` or ``*.pxd`` file, recompile the extension modules in place with ``python setup.py build_ext --inplace``.

.. warning:: Do not install ``mpi4py`` in this environment: ``setup.py`` would then try to build the parallel version of Janus, which is not tested under Windows, and requires ``mpicc``.

.. _Visual Studio Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/

If this text is adopted, the note on the lib prefix in CLAUDE.md should be updated accordingly.

Follow-up: proposed text applied, CLAUDE.md corrected#

The author approved the above text, which now replaces the Compilation with Anaconda and Visual Studio sub-section of sphinx/installation.rst.

The Build section of CLAUDE.md was corrected as follows.

  • The FFTW library name on Windows depends on where FFTW comes from: fftw3 with conda’s fftw package (recommended), libfftw3-3 with the precompiled DLLs from fftw.org. CLAUDE.md previously stated that the lib prefix must always be kept.

  • environment.yml and the editable install (pip install --no-build-isolation -e .) are mentioned, instead of python setup.py install --user.

  • python setup.py clean does not remove the compiled files any more (commit 40eee5e): git clean -Xfd janus/ is mentioned instead.

  • If mpi4py is installed but mpicc cannot be found, the build most likely fails (CLAUDE.md stated that the parallel extension was then silently skipped).

The documentation was built again, without new warnings.

Note that the introduction of the Windows section of sphinx/installation.rst still reads “You must first download and install the precompiled binaries of FFTW for Windows”. This is not required by the new (recommended) procedure, where FFTW is provided by conda. At the author’s request, this sentence was removed, together with the setup.cfg example and the note on the lib prefix that it introduced (and the now unused link to the precompiled binaries). The Windows section now only covers the conda procedure (and the unfinished MinGW/MSYS procedure).

Suggestions#

  • Applied, see above. sphinx/requirements.txt only lists sphinxcontrib-napoleon, which has been bundled with Sphinx (as sphinx.ext.napoleon) since version 1.3. This file, as well as the corresponding test on sphinx.__version__ in sphinx/conf.py, could be removed.

  • Applied, see above. Remove html_static_path from sphinx/conf.py (or create the sphinx/_static directory) to get rid of the corresponding warning.

  • Applied, see above. Once the installation procedure is stabilized, mention environment.yml in sphinx/installation.rst.

2026-09-11 • Installation on a windows machine (Miniconda environment)#

Following the update of the installation procedure, I am not sure how to install Janus on a windows machine. Use the conda environment janus to install the local version of janus in development mode. Add all required packages. Write down the procedure in your report. In particular, identify the fragile steps of the procedure (if any).

Claude’s report#

What was done#

Janus was already installed in the janus environment, in editable mode. To check the procedure from scratch, Claude uninstalled it (pip uninstall janus), removed all build artifacts (git clean -Xfd janus/, plus the build/ and Janus.egg-info/ directories at the root), then reinstalled it with the procedure below. The build succeeded, and the serial tests pass (3043 passed, 111 skipped; all skipped tests are 3D, fourth-rank cubic tensors, which are not implemented yet).

No package had to be added: the environment already contained everything required (python 3.14, cython, setuptools, pip, numpy, fftw, pytest, all from the pkgs/main channel). The parallel version was not installed (mpi4py is absent, see below).

Procedure#

  1. Install the Microsoft C/C++ compiler: Visual Studio Build Tools, with the Desktop development with C++ workload. It is not provided by conda, but setuptools locates it automatically (no need for a Developer Command Prompt). Visual Studio Build Tools 2026 was used here.

  2. Create and activate the environment (the creation command was checked with conda create --dry-run):

    conda create -n janus python=3.14 cython fftw numpy pytest setuptools pip
    conda activate janus
    
  3. Create the setup.cfg file at the root of the project. FFTW is provided by conda, in %CONDA_PREFIX%\Library. Environment variables are not expanded in setup.cfg, so the absolute path must be written in full (echo %CONDA_PREFIX% prints it). Note that the library name is fftw3 (the conda package provides fftw3.lib and fftw3.dll):

    [fftw]
    include_dirs = C:\path\to\miniconda3\envs\janus\Library\include
    library_dirs = C:\path\to\miniconda3\envs\janus\Library\lib
    libraries = fftw3
    
  4. Install Janus in development (editable) mode, from the root of the project:

    pip install --no-build-isolation -e .
    

    The extension modules (*.pyd) are compiled in place, next to the *.pyx sources. Changes to the *.py files are picked up immediately.

  5. Run the tests:

    python -m pytest tests
    
  6. After editing a *.pyx or *.pxd file, recompile the modified extensions in place (only the modified modules are recompiled):

    python setup.py build_ext --inplace
    

    Re-running pip install --no-build-isolation -e . also works.

Fragile steps#

  • The setup.cfg file. It is git-ignored, written by hand, and contains absolute paths that depend on the machine and on the name of the environment. It must be rewritten on each new machine, or if the environment is renamed.

  • The FFTW library name. With the conda package, the library name is fftw3. The Windows section of sphinx/installation.rst (and CLAUDE.md) state that the lib prefix must be kept (libfftw3-3): this is true only for the precompiled DLLs downloaded from fftw.org.

  • Build isolation. Plain pip install -e . also works, but pip then downloads the latest setuptools and Cython from PyPI (84.0.0 and 3.3.0 at the time of writing), instead of using the versions installed by conda (83.0.0 and 3.2.5). This requires network access, and the versions used for the build are not pinned. Hence the --no-build-isolation flag.

  • mpi4py. It must not be installed in the environment. setup.py tries to build the parallel extension as soon as mpi4py can be imported, and only catches ImportError. On Windows, there is usually no mpicc, and the build would most likely fail. This was inferred from reading setup.py, not tested.

  • distutils. setup.py imports distutils, which was removed from the standard library in Python 3.12. It currently works only because setuptools provides a replacement distutils module; a future version of setuptools might drop it. setup.py also raises a SyntaxWarning (invalid escape sequence "\S", line 86).

  • The packages list in setup.py. It omits janus.material, janus.material.elastic and janus.material.elastic.linear, and setuptools issues several “Package would be ignored” warnings. This is harmless for an editable install (the whole janus/ directory is mapped), but a regular (non-editable) install would probably lack these subpackages. Not tested.

  • Stale compiled files. The *.c and *.pyd files live in the source tree. They must be rebuilt after editing *.pyx/*.pxd files, or after upgrading Python. python setup.py clean does not remove them; use git clean -Xfd janus/.

Some points turned out not to be fragile. The FFTW DLL (fftw3.dll) is found at import time even when the environment is not activated (checked with conda directories removed from PATH): conda’s Python adds Library\bin to the DLL search path. The compiler emits many C4244 warnings (conversions from Py_ssize_t/ptrdiff_t to int), which do not prevent the build.

Suggestions#

  • Update the Windows section of sphinx/installation.rst with the above procedure, and fix the note on the lib prefix in CLAUDE.md.

  • Add an environment.yml file, to create the environment in one command.

  • In setup.py, replace the distutils imports with their setuptools counterparts, fix the "\S" escape sequence (raw string), complete the packages list, and make the build of the parallel extension skip gracefully when mpicc cannot be found.

  • In setup.py, default the FFTW paths to sys.prefix\Library when running in a conda environment on Windows, so that setup.cfg becomes optional.

2026-09-11 • How to update this page#

@Claude: this paragraph describe how we are to interact for the development of Janus. Take note of these instructions so that I don’t have to repeat myself at each new session.

Each time you are invoked in a console, you will read the present file and find the paragraphs that are marked TODO.

These are your instructions for the current session: each paragraph is an elementary task. As far as possible, each task will be given its own section with a short, unique title.

After completion of a task, report on what you did in a sub-paragraph called Claude’s report of the claude.rst file.

Once I have validated your changes, I will ask you to mark the task as done. This means you will replace the TODO flag with the date in yyyy-mm-dd format. You will then move to the next task. For tasks that cannot be completed in one session, use an IN PROGRESS flag, so that the state of the task is visible in the present file.

Questions that are still open, on which I have not made a decision yet, are recorded in sections marked TO DISCUSS. These are not tasks: you will not act on them, but raise them with me when they become relevant. Once a decision is made, the section is either turned into a TODO task, or marked with the date of the decision, together with a short statement of that decision.

Unless otherwise stated, you will never commit your changes.

Before you mark the present task as done, you can collect in a sub-paragraph any suggestions that might improve our interactions.

For these instructions to apply on any machine, add the following pointer in CLAUDE.md

at session start, read sphinx/claude.rst and process the TODO sections according to the How to update this page section

Claude’s report#

The pointer above was added to CLAUDE.md, in a new Session workflow section at the top of the file. Since CLAUDE.md is loaded at the start of every session, the present file is now the single source of truth for our workflow, on any machine.

The copy of these instructions that had been saved in Claude Code’s local memory (under ~/.claude/projects/, on the author’s machine only) was deleted: it duplicated the present file and was already out of date (it did not require the author’s validation before marking a task as done).

The author validated these changes on 2026-09-11, and the task was marked as done.