Skip to content

Commit 6f362c9

Browse files
authored
v0.5.0: Improve package structure and docs (#1)
* rename internal files * rename ICMPBP to SolverCore * rename ICMBPData to AugmentedPBData * Add SciMLPublic * Ensure explicit imports * Move code from pluto notebook to normal files * Add lots of docs with help of Claude
1 parent fb1249b commit 6f362c9

19 files changed

Lines changed: 1472 additions & 1131 deletions

.pre-commit-config.yaml

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v5.0.0
4+
hooks:
5+
- id: check-added-large-files
6+
args: [--maxkb=8192]
7+
- id: check-merge-conflict
8+
- id: check-toml
9+
- id: check-yaml
10+
args: [--allow-multiple-documents]
11+
- id: no-commit-to-branch
12+
args: [--branch,master]
13+
- repo: https://github.com/gitleaks/gitleaks
14+
rev: v8.24.2
15+
hooks:
16+
- id: gitleaks
17+
- repo: https://github.com/fredrikekre/runic-pre-commit
18+
rev: v1.0.0
19+
hooks:
20+
- id: runic
21+
- repo: https://github.com/codespell-project/codespell
22+
rev: v2.4.1
23+
hooks:
24+
- id: codespell
25+
- repo: https://github.com/psf/black
26+
rev: 25.9.0
27+
hooks:
28+
- id: black
29+
language_version: python3
30+
- repo: https://github.com/pycqa/isort
31+
rev: 6.0.1
32+
hooks:
33+
- id: isort
34+
args: ["--profile", "black"]

Project.toml

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,35 @@ version = "0.5.0"
44
authors = ["Jürgen Fuhrmann <juergen-fuhrmann@web.de>, Jason Landini <landinjm@umich.edu>"]
55

66
[deps]
7+
DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
78
ExtendableGrids = "cfc395e8-590f-11e8-1f13-43a2532b2fa8"
8-
InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
99
LessUnitful = "f29f6376-6e90-4d80-80c9-fb8ec61203d5"
1010
LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
11-
Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
1211
PreallocationTools = "d236fae5-4411-538c-8e31-a6e3d9e00b46"
1312
SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
13+
SciMLPublic = "431bcebd-1456-4ced-9d72-93c2757fff0b"
1414
Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
1515
VoronoiFVM = "82b139dc-5afc-11e9-35da-9b9bdfd336f3"
1616

1717
[compat]
18+
DocStringExtensions = "0.9.5"
19+
ExplicitImports = "1.14.0"
1820
ExtendableGrids = "1.14.0"
19-
InteractiveUtils = "1.10.0"
2021
LessUnitful = "1.2.1"
2122
LinearAlgebra = "1.10.0"
2223
Markdown = "1.10.0"
2324
PreallocationTools = "0.4.34"
2425
SciMLBase = "2.127.0"
26+
SciMLPublic = "1.0.0"
2527
Unitful = "1.25.1"
2628
VoronoiFVM = "2.13.0"
2729
julia = "1.10"
2830

2931
[extras]
32+
ExplicitImports = "7d51a73a-1435-4ff3-83d9-f097790105c7"
33+
LessUnitful = "f29f6376-6e90-4d80-80c9-fb8ec61203d5"
34+
Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
3035
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
3136

3237
[targets]
33-
test = ["Test"]
38+
test = ["Test", "ExplicitImports", "Markdown", "LessUnitful"]

docs/Project.toml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[deps]
22
AugmentedPoissonBoltzmann = "d8b18f01-5396-498d-b34d-247825c18ff1"
33
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
4+
VoronoiFVM = "82b139dc-5afc-11e9-35da-9b9bdfd336f3"
5+
SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
46

57
[sources]
6-
AugmentedPoissonBoltzmann = {rev = "main", url = ".."}
8+
AugmentedPoissonBoltzmann = {path = "/home/fuhrmann/Wias/work/julia/dev/AugmentedPoissonBoltzmann"}

docs/make.jl

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,21 @@
1-
using Documenter, AugmentedPoissonBoltzmann
1+
using Documenter, AugmentedPoissonBoltzmann, AugmentedPoissonBoltzmann.SolverCore
2+
using VoronoiFVM, SciMLBase
23

34
function mkdocs()
45
makedocs(
56
sitename = "AugmentedPoissonBoltzmann.jl",
6-
modules = [AugmentedPoissonBoltzmann],
7+
modules = [AugmentedPoissonBoltzmann, AugmentedPoissonBoltzmann.SolverCore],
78
clean = false,
89
doctest = false,
9-
warnonly = true,
10-
authors = "J. Fuhrmann, J. Landini",
10+
# warnonly = true,
11+
authors = "J. Fuhrmann, J. Landini, M. Landstorfer",
1112
repo = "https://github.com/IPAM-ECH2025/AugmentedPoissonBoltzmann.jl",
1213
pages = [
1314
"Home" => "index.md",
15+
"Python Access" => "pyapi.md",
16+
"Cells API" => "cells.md",
17+
"SolverCore API" => "solvercore.md",
18+
"Helpers" => "helpers.md",
1419
]
1520
)
1621
return if !isinteractive()

docs/src/cells.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Electrochemical cells
2+
3+
## Cell Types
4+
5+
### Abstract Types
6+
```@docs
7+
AugmentedPoissonBoltzmann.SolverCore.AbstractAugmentedPBCell
8+
AugmentedPoissonBoltzmann.SolverCore.AbstractHalfCell
9+
AugmentedPoissonBoltzmann.SolverCore.AbstractSymmetricCell
10+
```
11+
12+
### Concrete Cell Types
13+
```@docs
14+
AugmentedPoissonBoltzmann.SolverCore.AppliedPotentialHalfCell
15+
AugmentedPoissonBoltzmann.SolverCore.AppliedPotentialSymmetricCell
16+
AugmentedPoissonBoltzmann.SolverCore.SurfaceChargedHalfCell
17+
AugmentedPoissonBoltzmann.SolverCore.SurfaceChargedSymmetricCell
18+
```
19+
20+
## Cell Constructors
21+
```@docs
22+
AugmentedPoissonBoltzmann.SolverCore.AppliedPotentialHalfCell(grid, data; dielectric_decrement=false, valuetype=Float64)
23+
AugmentedPoissonBoltzmann.SolverCore.SurfaceChargedSymmetricCell(grid, data; dielectric_decrement=false, valuetype=Float64)
24+
```
25+
26+
## Solving and Initialization
27+
```@docs
28+
VoronoiFVM.unknowns(cell::AbstractAugmentedPBCell)
29+
SciMLBase.solve(cell::AbstractAugmentedPBCell; inival=unknowns(cell), verbose="", damp_initial=0.1, kwargs...)
30+
```
31+
32+
## Helper Functions
33+
34+
### Data Access
35+
```@docs
36+
AugmentedPoissonBoltzmann.SolverCore.apbdata
37+
```
38+
39+
### Calculation Functions
40+
```@docs
41+
AugmentedPoissonBoltzmann.SolverCore.calc_cmol(sol, cell::AbstractAugmentedPBCell)
42+
AugmentedPoissonBoltzmann.SolverCore.calc_c0mol(sol, cell::AbstractAugmentedPBCell)
43+
AugmentedPoissonBoltzmann.SolverCore.calc_χ(sol, cell::AbstractAugmentedPBCell)
44+
```
45+
46+
### Getter Functions
47+
```@docs
48+
AugmentedPoissonBoltzmann.SolverCore.get_E
49+
AugmentedPoissonBoltzmann.SolverCore.get_φ
50+
AugmentedPoissonBoltzmann.SolverCore.get_p
51+
```
52+
53+
### Setter Functions
54+
```@docs
55+
AugmentedPoissonBoltzmann.SolverCore.set_κ!
56+
AugmentedPoissonBoltzmann.SolverCore.set_molarity!(cell::AbstractAugmentedPBCell, M)
57+
AugmentedPoissonBoltzmann.SolverCore.set_φ!
58+
AugmentedPoissonBoltzmann.SolverCore.set_q!
59+
```
60+
61+
## Analysis Functions
62+
```@docs
63+
AugmentedPoissonBoltzmann.SolverCore.dlcapsweep
64+
```
65+
66+
## Boundary Conditions (Internal)
67+
```@docs
68+
AugmentedPoissonBoltzmann.SolverCore.halfcell_applied_potential_bcondition!
69+
AugmentedPoissonBoltzmann.SolverCore.symmcell_surfacecharge_bcondition!
70+
```
71+

docs/src/helpers.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
```@docs
2+
AugmentedPoissonBoltzmann.SolverCore.pramp
3+
```
4+

docs/src/pyapi.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Python Access
2+
3+
```@docs
4+
mpbpsolve
5+
icmpbpsolve
6+
```
7+
8+
## Internal
9+
```@docs
10+
AugmentedPoissonBoltzmann.prepare_grid
11+
```
12+
13+

docs/src/solvercore.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
## AugmentedPBSystem
2+
3+
```@docs
4+
AugmentedPoissonBoltzmann.SolverCore.AugmentedPBSystem
5+
VoronoiFVM.unknowns
6+
AugmentedPoissonBoltzmann.SolverCore.calc_cnum
7+
AugmentedPoissonBoltzmann.SolverCore.calc_c0num
8+
AugmentedPoissonBoltzmann.SolverCore.calc_cmol
9+
AugmentedPoissonBoltzmann.SolverCore.calc_c0mol
10+
AugmentedPoissonBoltzmann.SolverCore.calc_χ
11+
AugmentedPoissonBoltzmann.SolverCore.calc_spacecharge
12+
AugmentedPoissonBoltzmann.SolverCore.ysum(::VoronoiFVM.System, sol)
13+
AugmentedPoissonBoltzmann.SolverCore.qsweep
14+
```
15+
16+
## AugementedPBData
17+
18+
```@docs
19+
AugmentedPoissonBoltzmann.SolverCore.AugmentedPBData
20+
AugmentedPoissonBoltzmann.SolverCore.apply_voltage!
21+
AugmentedPoissonBoltzmann.SolverCore.apply_charge!
22+
AugmentedPoissonBoltzmann.SolverCore.set_molarity!
23+
AugmentedPoissonBoltzmann.SolverCore.L_Debye
24+
AugmentedPoissonBoltzmann.SolverCore.dlcap0
25+
AugmentedPoissonBoltzmann.SolverCore.capscalc
26+
```
27+
28+
29+
## Internal: Constitutive model
30+
```@docs
31+
AugmentedPoissonBoltzmann.SolverCore.DerivedData
32+
AugmentedPoissonBoltzmann.SolverCore.DerivedData(data::AugmentedPBData)
33+
AugmentedPoissonBoltzmann.SolverCore.DerivedData(data::AugmentedPBData, n_E)
34+
AugmentedPoissonBoltzmann.SolverCore.makeδ
35+
AugmentedPoissonBoltzmann.SolverCore.W
36+
AugmentedPoissonBoltzmann.SolverCore.Λ
37+
AugmentedPoissonBoltzmann.SolverCore.y_α
38+
AugmentedPoissonBoltzmann.SolverCore.y0
39+
AugmentedPoissonBoltzmann.SolverCore.ysum(u, ::AugmentedPBData)
40+
AugmentedPoissonBoltzmann.SolverCore.spacecharge
41+
AugmentedPoissonBoltzmann.SolverCore.susceptibility
42+
AugmentedPoissonBoltzmann.SolverCore.c_num!
43+
AugmentedPoissonBoltzmann.SolverCore.c0_num
44+
```
45+
46+
## Internal: System
47+
```@docs
48+
AugmentedPoissonBoltzmann.SolverCore.reaction!
49+
AugmentedPoissonBoltzmann.SolverCore.poisson_and_p_flux!
50+
AugmentedPoissonBoltzmann.SolverCore.bcondition!
51+
AugmentedPoissonBoltzmann.SolverCore.ionconservation!
52+
```

src/AugmentedPoissonBoltzmann.jl

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ Development initiated during the [IPAM Long Program - Bridging the Gap: Transiti
77
"""
88
module AugmentedPoissonBoltzmann
99

10+
using ExtendableGrids: ExtendableGrids, bfacemask!
11+
using LessUnitful: LessUnitful, @ufac_str
12+
using VoronoiFVM: VoronoiFVM, solve, unknowns
13+
using LessUnitful: LessUnitful, @ufac_str
14+
1015
include("units.jl")
1116
using .Units
1217

@@ -23,21 +28,33 @@ include("equations.jl")
2328
using .Equations
2429

2530

26-
module ICMPBP
27-
using LessUnitful
28-
using ExtendableGrids
29-
using VoronoiFVM
30-
using LinearAlgebra
31-
using SciMLBase
31+
module SolverCore
32+
using DocStringExtensions: TYPEDFIELDS
33+
using ExtendableGrids: ExtendableGrids, BFaceNodes, Coordinates, num_nodes
34+
using LessUnitful: LessUnitful, @ph_str, @ufac_str
35+
using SciMLBase: SciMLBase, solve, solve!
36+
using SciMLPublic: @public
37+
using VoronoiFVM: VoronoiFVM, boundary_dirichlet!, boundary_neumann!,
38+
enable_boundary_species!, enable_species!, nodevolumes,
39+
unknown_indices, unknowns
3240

3341
include("pramp.jl")
34-
include("icmbp-p.jl")
42+
include("augmentedpbdata.jl")
43+
include("augmentedpbconstitutive.jl")
44+
include("augmentedpbsystem.jl")
3545
include("cells.jl")
46+
export pramp
47+
export set_molarity!, set_κ!, set_q!, set_φ
48+
@public L_debye, dlcap0
49+
export calc_cmol, calc_c0mol, calc_χ
50+
export get_E, get_φ, get_p
51+
export AbstractAugmentedPBCell, AbstractHalfCell, AbstractSymmetricCell
52+
export AugmentedPBData, SurfaceChargedSymmetricCell, AppliedPotentialHalfCell
53+
@public W, Λ
3654
end
3755

38-
include("api.jl")
56+
include("pyapi.jl")
3957

40-
export pramp
4158
export mpbpsolve
4259
export icmpbpsolve
4360
end

0 commit comments

Comments
 (0)