Skip to content

Overhaul tutorials & Sphinx docs, fix periodic homogenisation FV stencil, and add CITATION.cff - #305

Open
jameslehoux wants to merge 5 commits into
masterfrom
feat/tutorials-and-docs-overhaul
Open

jameslehoux wants to merge 5 commits into
masterfrom
feat/tutorials-and-docs-overhaul

Conversation

@jameslehoux

Copy link
Copy Markdown

Summary

Overhauls OpenImpala's tutorial curriculum and Sphinx documentation to a scientific Python standard (pydata-sphinx-theme + myst-nb), fixes a conservative finite-volume discretisation & CUDA bug in periodic homogenisation, and adds pre-JOSS repository polish (CITATION.cff and multi-version pure-Python CI).

1. Conservative Finite-Volume Periodic Homogenisation & CUDA Fix (src/props/, python/openimpala/_solver.py)

  • Discretises $-\nabla \cdot (D(\mathbf{e}k + \nabla \chi_k)) = 0$ with harmonic face conductances $D{i+1/2}^{(d)}$ (0 at solid walls), divergence RHS $(D_{i+1/2}^{(k)} - D_{i-1/2}^{(k)})/h_k$, and conservative $+r$ face-flux tensor assembly across EffDiffFillMtx.H, DeffTensor.H/.cpp, EffectiveDiffusivityHypre.cpp, tEffectiveDiffusivity.cpp, and _solver.py.
  • Guarantees exact Onsager reciprocity ($D_{rc} = D_{cr}$), positive semi-definiteness, zero normal transport across blocked solid barriers, and exact Voigt/Reuss bounds at every grid resolution.
  • Fixes a host-pointer-on-device bug in EffectiveDiffusivityHypre.cpp when pinning the periodic nullspace cell under OPENIMPALA_USE_GPU (HYPRE_MEMORY_DEVICE), and scale-matches the diagonal pin entry.

2. Executed 5-Notebook Tutorial Curriculum & Python Ergonomics (tutorials/, python/openimpala/)

  • Replaces the 9 unexecuted legacy notebooks in tutorials/ and notebooks/ with 5 genuinely executed tutorials (tutorials/01..05_*.ipynb):
    1. 01_getting_started.ipynb — Exact analytical slab benchmark ($\tau = 1$), 3D TIFF loading, percolation, potential $\phi$ & $|\nabla \phi|$ bottleneck maps
    2. 02_microstructure_and_anisotropy.ipynb — $2/3$ Cauchy–Crofton specific surface area verification on analytical spheres, connected components, PSD, through-thickness porosity profile, and non-cubic FIB-SEM voxel_size=(dz, dy, dx)
    3. 03_homogenisation_tensor.ipynb — Periodic corrector cell problems on a tilted laminate, principal-axis eigendecomposition, and periodic vs. Dirichlet flow-through comparison
    4. 04_multiphase_transport.ipynb — Exact Voigt/Reuss multi-phase verification and nanoporous binder bridging across disconnected macropores
    5. 05_rev_and_uncertainty.ipynb — Subvolume REV scale convergence ($L \in [16, 64]$), 95% bootstrap confidence intervals, and 5% CV criterion
  • Adds openimpala.datasets (two_phase_stack, two_phase_cubic, sphere_pack, fetch_path), stdlib TIFF support in read_image(), tortuosity_all(), _repr_html_() tables on all 9 result dataclasses, and atexit-managed Session.ensure_active() for multi-cell notebooks.

3. Sphinx Documentation, CITATION.cff & CI (docs/, .github/workflows/)

  • Migrates Sphinx to pydata-sphinx-theme, myst-nb (nb_execution_mode = "cache"), sphinx-design, and sphinx-copybutton, rendering all 5 tutorials directly into the online docs alongside updated Diátaxis User Guide and complete v4.6+ Python/C++ API references.
  • Adds CFF 1.2.0 CITATION.cff and updates README.md, CONTRIBUTING.md, docs/changelog.md, and paper.md.
  • Adds a fast pure-Python pytest matrix job (3.9, 3.11, 3.13) to build-test.yml and PR verification (sphinx-build -W + Doxygen + Breathe + MyST-NB) to docs.yml.

Verification

  • PYTHONPATH=python pytest python/tests/ -v (71 passed, 14 skipped)
  • sphinx-build -W --keep-going -b html docs/ docs/_build/html (0 warnings, 0 errors across all 20 pages and 5 executed notebooks)
  • clang-format --dry-run --Werror across src/, tests/, and python/bindings/ (0 violations)
  • cffconvert --validate (valid CFF 1.2.0)

@github-actions github-actions Bot added devops documentation Improvements or additions to documentation physics python tests labels Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Performance Benchmark Results

Uniform Block (Analytical τ = 1.0)

Size Solver Wall Time (s) Tortuosity Expected Rel. Error Iters Status
64³ mlmg 0.0408 1.000000 1.000000 0.00e+00 0 PASS
64³ pcg 0.3443 1.000000 1.000000 0.00e+00 1 PASS
64³ flexgmres 0.2280 1.000000 1.000000 0.00e+00 1 PASS
64³ bicgstab 0.3055 1.000000 1.000000 0.00e+00 1 PASS
64³ gmres 0.3045 1.000000 1.000000 0.00e+00 1 PASS
128³ mlmg 0.1832 1.000000 1.000000 0.00e+00 0 PASS
128³ pcg 2.9312 1.000000 1.000000 0.00e+00 1 PASS
128³ flexgmres 2.2528 1.000000 1.000000 0.00e+00 1 PASS
128³ bicgstab 2.5829 1.000000 1.000000 0.00e+00 1 PASS
128³ gmres 2.6599 1.000000 1.000000 0.00e+00 1 PASS

Porous Media (MLMG vs HYPRE PCG+SMG, ~55% Porosity)

Size Solver Wall Time (s) Tortuosity Reference Rel. Diff Iters Status
32³ pcg+smg 0.2666 1.923669 1.923669 0.00e+00 19 PASS
32³ mlmg 0.0296 1.923669 1.923669 0.00e+00 10 PASS
64³ pcg+smg 2.8430 1.946440 1.946440 0.00e+00 31 PASS
64³ mlmg 0.1866 1.946440 1.946440 0.00e+00 11 PASS
128³ pcg+smg 39.7242 1.948784 1.948784 0.00e+00 50 PASS
128³ mlmg 1.7804 1.948784 1.948784 0.00e+00 13 PASS

Fastest uniform solver: mlmg at 64³ (0.0408s)

Benchmark: uniform block (analytical τ = 1.0) + smoothed Gaussian porous media

@github-actions

Copy link
Copy Markdown

Code Coverage Report

------------------------------------------------------------------------------
                           GCC Code Coverage Report
Directory: .
------------------------------------------------------------------------------
File                                         Lines     Exec  Cover   Missing
------------------------------------------------------------------------------
src/io/CathodeWrite.cpp                         95       83    87%   40-41,97-100,115-116,182-185
src/io/CathodeWrite.H                            1        1   100%
src/io/DatReader.cpp                           136      106    77%   28-29,32,37,94-95,101-102,109-111,137-139,143,146-150,154-157,164,166,210-211,256,259
src/io/DatReader.H                               1        1   100%
src/io/HDF5Reader.cpp                          344       84    24%   40-41,43-44,46-49,52,54-56,58-59,62,64-66,68-74,92-93,126-128,144-145,154-157,174-180,182-187,204,213-215,217,219-228,230-233,236-238,240-251,253-258,266,266,266,266,266,266,266,270,270,270,270,270,270,270,274,276,278,280,282,288,290,297,297,297,297,297,297,297,301,301,301,301,301,301,301,305,305,305,305,305,305,305-306,306,306,306,306,306,306,309,309,309,309,309,309,309-310,310,310,310,310,310,310-311,311,311,311,311,311,311,313,313,313,313,313,313,313-314,314,314,314,314,314,314-315,315,315,315,315,315,315,319,319,319,319,319,319,319,324,324,324,324,324,324,324-325,325,325,325,325,325,325-326,326,326,326,326,326,326-327,327,327,327,327,327,327,332,332,332,332,332,332,332,337,337,337,337,337,337,337-338,338,338,338,338,338,338,343,343,343,343,343,343,343,350,350,350,350,350,350,350,357-358,432-435,437-440
src/io/HDF5Reader.H                              3        3   100%
src/io/ImageLoader.cpp                          61       42    68%   25,38,48,60-62,64-70,72,77,89-90,92,94
src/io/RawReader.cpp                           267      136    50%   51-52,91-92,113-114,117-119,122-123,142-144,157-159,168-170,176-179,187-188,194-198,202-206,211-214,221-226,233-239,273,275-276,278,285-286,303,314,316,320,327,329,333-336,340,348-349,355-357,363-365,367-368,371,374,376,379-382,384-386,388,390-391,393,395-396,398,400-401,403,405-406,408,412-413,415,419-420,422,427,467,473-474,535-538,552,554-556,558,560-562,572,576-578,580,602
src/io/RawReader.H                               1        1   100%
src/io/TiffReader.cpp                          385      131    34%   60-66,68-70,72-74,76-78,80-81,83-85,87-89,91-93,95-97,99-100,102-104,107-109,112-113,115-118,120,123,125-128,144-145,149-151,153-159,161,187,211,218,227,229-232,241,243-246,249,256,289-294,307,310-318,320-321,324-328,332-336,339-343,345-349,352-358,360-364,368,370,376-378,380-394,397,399-403,405-410,414-419,421-426,429-430,433-435,569-589,591-592,595-602,604,607-623,626-628,684,687-688,691-697,699,703-714,716-717
src/io/TiffReader.H                              5        5   100%
src/props/BoundaryCondition.H                  113       56    49%   63,68,70,192,200-205,209-212,214-220,223-225,228-229,231,234-237,240-241,247-248,250-255,261-263,266-272,275,279,341-342,347,349
src/props/ConnectedComponents.cpp               71       69    97%   115-116
src/props/ConnectedComponents.H                  4        4   100%
src/props/DeffTensor.cpp                       101       99    98%   96,179
src/props/Diffusion.cpp                        510      327    64%   93-94,97-98,103-104,106-116,118,123-132,134-141,144-150,153-157,159-163,165,168-173,175-177,179,182-184,186-187,190-191,193,195-198,200,202-203,288-289,297-298,300,341,349,362-371,373-375,380-389,392-399,401,403-413,415,420-424,426-427,430-432,436-447,449,451,453,457-459,461,463-464,526-527,533,535,539,547,581,610,638,646,735-736,739-740,757-760,771-772,774,824
src/props/EffDiffFillMtx.H                     102       96    94%   58,192-196
src/props/EffectiveDiffusivityHypre.cpp        422      361    85%   146-147,149,151,199-201,203-207,362-365,468,642-645,647-649,651-654,672-676,678-679,681-684,686-689,692-693,695-696,698-699,702,714-717,719-721,723,738,756,758
src/props/EffectiveDiffusivityHypre.H            7        7   100%
src/props/FloodFill.cpp                        171      112    65%   111-112,152-153,164-165,167-171,175-183,222,230,288,291,322-325,327,342-345,348-349,354,357-359,369,373,384,386-387,390,392-399,410,412,415,418-419,421
src/props/HypreStructSolver.cpp                343      212    61%   87-88,121,133-134,145,303,315,350,360,362,365,371-374,376-380,382-383,385-389,392-393,395-396,398,401-402,405-406,408-411,413-417,419-420,422-426,429-430,432-433,435,438-439,442-443,445-447,449-455,457-461,464-465,467-468,470,473-474,477,479-481,483-489,491-495,498-499,501-502,504,507-508,511,513-515,517-520,522-526,529-530,532-533,535,538-539,542,545-546,559
src/props/HypreStructSolver.H                    6        6   100%
src/props/MacroGeometry.H                       17       17   100%
src/props/ParticleSizeDistribution.cpp          11       11   100%
src/props/ParticleSizeDistribution.H             6        6   100%
src/props/PercolationCheck.cpp                  53       46    86%   32-33,49-51,68,73
src/props/PercolationCheck.H                     4        4   100%
src/props/PhysicsConfig.H                       90       89    98%   150
src/props/ResultsJSON.H                        225      209    92%   151-154,157-158,209-215,242,395,416
src/props/REVStudy.cpp                         151      128    84%   72,83-91,159,170-173,175,183-186,188-190
src/props/SolverConfig.H                        32       20    62%   30,32,37-44,75-76
src/props/SpecificSurfaceArea.cpp               73       60    82%   53,106-111,114-117,119,121
src/props/SpecificSurfaceArea.H                  6        6   100%
src/props/ThroughThicknessProfile.cpp           38       38   100%
src/props/ThroughThicknessProfile.H              5        5   100%
src/props/Tortuosity.H                           2        2   100%
src/props/TortuosityDirect.cpp                 219      191    87%   81-83,86,100-106,113-114,125,134,140,202-209,226,394,424,433
src/props/TortuosityDirect.H                     5        5   100%
src/props/TortuosityHypre.cpp                  822      576    70%   150-151,156-157,179-180,182,184-190,236,268-271,274-277,340,364-366,369-370,372,400-402,405-407,437-440,649,673,677,698,715-716,718-720,723-730,737-738,740,742,745-755,759-765,767-771,775-777,779-781,784-791,798-799,801,803-813,817-825,827-830,832,842,848-851,853-855,864-867,869-871,928,931-932,952-954,957,968-971,973-974,991,996-999,1001-1004,1006-1009,1011-1012,1014-1017,1019-1020,1026-1028,1030,1077,1086,1091,1094-1099,1115-1118,1132-1136,1141-1146,1162,1166-1170,1173-1176,1183-1186,1197,1206,1208,1212,1214,1239,1281-1282,1317-1323,1342-1348,1375-1377,1504-1507
src/props/TortuosityHypre.H                     15       15   100%
src/props/TortuosityHypreFill.H                127       98    77%   85,203,205-212,237-239,241-245,247-248,250,252,255-256,258-262
src/props/TortuosityKernels.H                   97       53    54%   52,56-60,62-65,69-74,76-80,84-85,90,129,143,157,243,245-248,250-253,257-260,262-265
src/props/TortuosityMLMG.cpp                   129      120    93%   227-229,231-233,235-236,248
src/props/TortuosityMLMG.H                       1        1   100%
src/props/TortuositySolverBase.cpp             372      294    79%   63-64,66,68,98,116-118,120-122,141-147,165,169,171,236,251-254,309,312,314,466,482,485-487,489,497-500,502-508,513,518-521,527-528,530-533,587,591-593,596,601-604,606-607,621,625-628,630-631,633-634,639
src/props/TortuositySolverBase.H                13       13   100%
src/props/VolumeFraction.cpp                    25       25   100%
src/props/VolumeFraction.H                       4        4   100%
------------------------------------------------------------------------------
TOTAL                                         5691     3978    69%
------------------------------------------------------------------------------


Generated by CI — coverage data from gcovr

@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 84.00735% with 87 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
python/openimpala/facade.py 70.0% 51 Missing ⚠️
python/openimpala/_io.py 89.8% 27 Missing ⚠️
python/openimpala/session.py 50.0% 8 Missing ⚠️
python/openimpala/datasets.py 97.8% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

devops documentation Improvements or additions to documentation physics python tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant