ofempy 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. ofempy-0.1.0/LICENSE +21 -0
  2. ofempy-0.1.0/MANIFEST.in +1 -0
  3. ofempy-0.1.0/PKG-INFO +316 -0
  4. ofempy-0.1.0/README.md +290 -0
  5. ofempy-0.1.0/ofempy/__init__.py +24 -0
  6. ofempy-0.1.0/ofempy/assembly.py +118 -0
  7. ofempy-0.1.0/ofempy/boundary/__init__.py +8 -0
  8. ofempy-0.1.0/ofempy/boundary/absorbing.py +104 -0
  9. ofempy-0.1.0/ofempy/boundary/base.py +61 -0
  10. ofempy-0.1.0/ofempy/boundary/dirichlet.py +30 -0
  11. ofempy-0.1.0/ofempy/boundary/integration.py +120 -0
  12. ofempy-0.1.0/ofempy/boundary/natural.py +116 -0
  13. ofempy-0.1.0/ofempy/boundary/traces.py +170 -0
  14. ofempy-0.1.0/ofempy/dofs.py +125 -0
  15. ofempy-0.1.0/ofempy/elements/__init__.py +5 -0
  16. ofempy-0.1.0/ofempy/elements/base.py +65 -0
  17. ofempy-0.1.0/ofempy/elements/h1.py +193 -0
  18. ofempy-0.1.0/ofempy/elements/hcurl.py +319 -0
  19. ofempy-0.1.0/ofempy/elements/hdiv.py +176 -0
  20. ofempy-0.1.0/ofempy/elements/vector.py +60 -0
  21. ofempy-0.1.0/ofempy/geometry.py +644 -0
  22. ofempy-0.1.0/ofempy/io/__init__.py +6 -0
  23. ofempy-0.1.0/ofempy/io/inp.py +150 -0
  24. ofempy-0.1.0/ofempy/io/vtu.py +80 -0
  25. ofempy-0.1.0/ofempy/legendre.py +50 -0
  26. ofempy-0.1.0/ofempy/linalg.py +314 -0
  27. ofempy-0.1.0/ofempy/materials.py +28 -0
  28. ofempy-0.1.0/ofempy/preconditioners/__init__.py +5 -0
  29. ofempy-0.1.0/ofempy/preconditioners/additive_jacobi.py +210 -0
  30. ofempy-0.1.0/ofempy/preconditioners/amg.py +181 -0
  31. ofempy-0.1.0/ofempy/preconditioners/hiptmair_xu.py +157 -0
  32. ofempy-0.1.0/ofempy/problem.py +398 -0
  33. ofempy-0.1.0/ofempy/quadrature.py +328 -0
  34. ofempy-0.1.0/ofempy/solvers/__init__.py +3 -0
  35. ofempy-0.1.0/ofempy/solvers/lobpcg.py +254 -0
  36. ofempy-0.1.0/ofempy/tools.py +279 -0
  37. ofempy-0.1.0/ofempy/volume_force.py +28 -0
  38. ofempy-0.1.0/ofempy.egg-info/PKG-INFO +316 -0
  39. ofempy-0.1.0/ofempy.egg-info/SOURCES.txt +52 -0
  40. ofempy-0.1.0/ofempy.egg-info/dependency_links.txt +1 -0
  41. ofempy-0.1.0/ofempy.egg-info/requires.txt +14 -0
  42. ofempy-0.1.0/ofempy.egg-info/top_level.txt +1 -0
  43. ofempy-0.1.0/pyproject.toml +38 -0
  44. ofempy-0.1.0/setup.cfg +4 -0
  45. ofempy-0.1.0/tests/test_examples.py +42 -0
  46. ofempy-0.1.0/tests/test_geometry.py +155 -0
  47. ofempy-0.1.0/tests/test_h1.py +102 -0
  48. ofempy-0.1.0/tests/test_legendre.py +29 -0
  49. ofempy-0.1.0/tests/test_natural_and_time.py +267 -0
  50. ofempy-0.1.0/tests/test_problem.py +269 -0
  51. ofempy-0.1.0/tests/test_quadrature.py +46 -0
  52. ofempy-0.1.0/tests/test_solvers.py +461 -0
  53. ofempy-0.1.0/tests/test_tools.py +309 -0
  54. ofempy-0.1.0/tests/test_vector_elements.py +339 -0
ofempy-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Myromax
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ prune examples
ofempy-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,316 @@
1
+ Metadata-Version: 2.4
2
+ Name: ofempy
3
+ Version: 0.1.0
4
+ Summary: Python port of the oFEM finite element package
5
+ Author: Myromax
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Myromax/oFEMpy
8
+ Project-URL: Repository, https://github.com/Myromax/oFEMpy.git
9
+ Project-URL: Issues, https://github.com/Myromax/oFEMpy/issues
10
+ Requires-Python: >=3.10
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Requires-Dist: numpy>=1.26
14
+ Requires-Dist: scipy>=1.12
15
+ Requires-Dist: sympy>=1.12
16
+ Requires-Dist: gmsh>=4.11
17
+ Requires-Dist: pyamg>=5.0
18
+ Requires-Dist: threadpoolctl>=3.1
19
+ Provides-Extra: test
20
+ Requires-Dist: pytest>=8; extra == "test"
21
+ Requires-Dist: matplotlib>=3.7; extra == "test"
22
+ Requires-Dist: meshio>=5.3; extra == "test"
23
+ Provides-Extra: plot
24
+ Requires-Dist: matplotlib>=3.7; extra == "plot"
25
+ Dynamic: license-file
26
+
27
+ # ofempy
28
+
29
+ <https://github.com/Myromax/oFEMpy>
30
+
31
+ Python port of [oFEM](../oFEM) (`source/+ofem_v2`): H1, H(curl) and H(div)
32
+ finite elements of arbitrary degree on triangles and tetrahedra, boundary
33
+ conditions, time stepping, AMG / Hiptmair-Xu preconditioners and LOBPCG.
34
+
35
+ ## Setup
36
+
37
+ ```sh
38
+ python3 -m venv .venv
39
+ .venv/bin/pip install -e '.[test]'
40
+ .venv/bin/python -m pytest
41
+ ```
42
+
43
+ Dependencies: numpy, scipy (>= 1.12), sympy, gmsh, pyamg, threadpoolctl;
44
+ matplotlib for plots (`pip install -e '.[plot]'`); the tests also use
45
+ meshio.
46
+
47
+ The PyPI `gmsh` wheel links against `libGLU.so.1`. If `import gmsh` fails
48
+ with `libGLU.so.1: cannot open shared object file`, either install the
49
+ system package (`mesa-libGLU` on Fedora; `rpm-ostree install mesa-libGLU`
50
+ on Atomic/Bazzite), or copy a 64-bit `libGLU.so.1` next to
51
+ `.venv/lib/libgmsh.so*` (the library's runpath includes its own folder).
52
+
53
+ ## Meshes
54
+
55
+ Meshes come straight from the gmsh Python API, without writing a file:
56
+
57
+ ```python
58
+ import gmsh
59
+ from ofempy import Geometry
60
+
61
+ gmsh.initialize()
62
+ gmsh.model.occ.addRectangle(0, 0, 0, 1, 1)
63
+ gmsh.model.occ.synchronize()
64
+ gmsh.model.addPhysicalGroup(2, [1], name="M:Domain")
65
+ gmsh.model.addPhysicalGroup(1, [4], name="BD:left")
66
+ gmsh.model.mesh.generate(2)
67
+ mesh = Geometry.from_gmsh() # reads the current model
68
+ gmsh.finalize()
69
+ ```
70
+
71
+ Files work as well: `Geometry.from_msh(path)` (through gmsh) and
72
+ `Geometry.from_inp(path)` (Cubit / Trelis Abaqus files, pure Python parser:
73
+ side sets become boundaries, section materials are attached to the parts
74
+ with the Abaqus property names). `Geometry.hypercube(x0, extent)` and
75
+ `uniform_refine()` build structured meshes.
76
+
77
+ Physical groups follow the oFEM naming: `M:` parts, `BD:` boundaries,
78
+ `ROI:`/`ROI1:`/`ROI2:` regions of interest.
79
+
80
+ oFEM's MEX reader only reads MSH 2.2 (a MSH 4.1 file makes it hang); write
81
+ meshes meant for MATLAB with `gmsh.option.setNumber("Mesh.MshFileVersion", 2.2)`.
82
+
83
+ ## Example: Capacitor2D
84
+
85
+ ```python
86
+ from ofempy import *
87
+
88
+ mesh = Geometry.from_msh("CapacitorExample2d.msh")
89
+ fe = H1Element(2, 1).compute_basis()
90
+ dofs = DOFHandler(mesh); dofs.attach(fe)
91
+ cap = PhysicalProblem(fe, mesh, has_stiffness=True)
92
+ cap.attach_dof_handler(dofs)
93
+ mesh.set_material("Paper", Material(epsilon=1e-4))
94
+ mesh.set_material("Glas", Material(epsilon=5e-4))
95
+ cap.set_para_s("epsilon")
96
+ cap.set_boundary_condition(Dirichlet(0, "left", mesh))
97
+ cap.set_boundary_condition(Dirichlet(5, "right", mesh))
98
+ dofs.generate_dofs()
99
+ cap.assemble()
100
+ cap.solve()
101
+ cap.export_vtu("export/2dCapacitor", "U", cell_data={"E": cap.grad_cell()})
102
+ ```
103
+
104
+ ## Examples
105
+
106
+ [examples/](examples/README.md) contains ports of all oFEM examples (H1,
107
+ H(curl), H(div), tools). They are not part of the package; the fast ones
108
+ run with `pytest -m examples`.
109
+
110
+ ## Differences to the MATLAB API
111
+
112
+ * Indices are 0-based: `el`, `ed`, `el2ed`, `fa`, `el2fa`, `fa2ed`, DOFs,
113
+ and `refTet` in {0, 1}.
114
+ * Per-element arrays have the element index first: `co` is `(Nco, dim)`,
115
+ `DinvT`/`Dk` are `(Ne, d, d)`, `detD` is `(Ne,)`; field values are
116
+ `(Ne, Np, dim)` instead of `dim x Ne x Np`. Connectivity is `int32`.
117
+ * Functions of space (materials, forces, boundary data) take points as
118
+ `(N, dim)` arrays and return `(N,)`, `(N, dim)` or `(N, d, d)`; boundary
119
+ data may also be `f(X, n)` with the outer unit normals `n`.
120
+ * Method names are snake_case (`generate_dofs`, `set_para_s`,
121
+ `set_boundary_condition`, `grad_cell`, `ams_dofs`, ...).
122
+ * `gauss_simplex(dim, order)` returns `(w, l)` with `l` of shape
123
+ `(Nq, dim)`; in 1D `order` is the polynomial degree (as in 2D/3D), not
124
+ the number of points.
125
+ * Element bases are evaluated at many points at once: `phi(l)` is
126
+ `(2, Nq, 1, Ns)`, `dphi(l)` / `N(l)` `(2, Nq, dim, Ns)`, the first axis
127
+ being the `refTet` variant. No precomputed element files are needed;
128
+ the bases are built with sympy in seconds, once per element type, degree
129
+ and dimension in a process (later `compute_basis` calls reuse them).
130
+ * Fixed DOFs are a boolean mask (`DOFHandler.fixed`); `freeDOFs` is derived
131
+ from it. Between two Dirichlet boundaries that share nodes (for
132
+ `DirichletEdge` / `NormalTrace`: edges) the first one keeps them (with a
133
+ warning, or `assemble(interactive=True)` to choose); natural and Robin
134
+ boundaries never take nodes from a Dirichlet one.
135
+ * `PhysicalProblem.solve(matrix=...)` lifts the Dirichlet values with the
136
+ matrix it solves (Physical_Problem lifted with `S + M + D + M_robin` but
137
+ solved with `S`) and returns a complex `u` for complex systems.
138
+ `solve` and `parabolic_solve` take `method="cg"` (CG with smoothed
139
+ aggregation AMG) for large 3D and higher order problems, whose LU
140
+ factorisation is slow (54k DOFs in 3D: 40 s).
141
+ * Boundary conditions need no boundary element (`feBd`):
142
+ `Neumann(value, name, mesh)`, `Robin(value, alpha, beta, name, mesh,
143
+ lumped=False)`, `AbsorbingBoundaryCondition(name, mesh, factor)`,
144
+ `DirichletEdge(value, name, mesh)`, `NormalTrace(name, mesh, value=0)`
145
+ (a nonzero normal trace is an extension), `WaveguideInput(u_in, x, name,
146
+ mesh)`.
147
+ * `lobpcg_mod_proj(X, S, M, n, maxit, tol, Y, dofs, YMY)`: MATLAB argument
148
+ order without the unused `C`.
149
+ * Export writes VTK `.vtu` (ParaView) instead of UCD `.inp`, with an own
150
+ writer (`ofempy/io/vtu.py`): zlib level 1 instead of meshio's level 6
151
+ gives the same file size for FE fields and writes them 1.6x faster
152
+ (exporting every time step dominated some examples); complex fields
153
+ become `<name>_re` / `<name>_im`. `tools.export_points` replaces
154
+ `exportAtQuad`.
155
+ * `PhysicalProblem.gradu` fits the local quadratic centred at the node
156
+ (same fit as MATLAB, better conditioned).
157
+ * Solvers and preconditioners keep MATLAB's memory design by default
158
+ (`storage="tril"`): the system matrix and every AMG level are stored as
159
+ `tril(A)` + `diag(A)` only. The triangle is kept with a unit diagonal,
160
+ and both Gauss-Seidel sweeps call SuperLU's triangular solve on it
161
+ directly (half the time of `spsolve_triangular`, which resets the
162
+ diagonal, checks the format and converts the matrix on every call).
163
+ `storage="full"` keeps `A` in CSR (the caller's matrix, not a copy) and
164
+ sweeps with PyAMG's compiled Gauss-Seidel kernel, faster again; as the
165
+ finest matrix is then shared with the Krylov solver, an AMG hierarchy
166
+ needs less memory than with the triangle (H1 degree 2: half), while
167
+ `HiptmairXu.from_problem` keeps a full copy of the restricted matrix.
168
+ `solve(method="cg")` uses it. Assembled matrices are symmetric up to
169
+ rounding; they are used as they are (no symmetrised copy). Complex
170
+ vectors are preconditioned by real and imaginary part (SciPy converts a
171
+ real sparse matrix to complex on every product with a complex vector).
172
+ * Aggregation uses PyAMG's C++ `standard_aggregation` (the same greedy
173
+ algorithm). Nodes without strong connections are left to the smoother,
174
+ as in PyAMG and the SA literature; SmoothedAggregationAMG.m made each a
175
+ one-node aggregate, which keeps the coarse grids of higher order
176
+ matrices large (H1 degree 4: operator complexity 4.2 instead of 1.3,
177
+ setup 13 s instead of 1.5 s, same iteration count). The AMG damping
178
+ estimate uses a seeded random start.
179
+ * SciPy has no sparse or incomplete Cholesky: `'chol'` uses CHOLMOD if
180
+ scikit-sparse is installed, else SuperLU; `'ict'` uses ILUT (`spilu`).
181
+ `AdditiveJacobi.gradient_correction` also offers `solver='amg'`. The
182
+ accurate `gradient_solve` uses PCG with AMG: PCG with the non-symmetric
183
+ ILU stagnated at a relative residual of 1e-2 in the eddy current sweep
184
+ (MATLAB's `ichol` is symmetric).
185
+
186
+ ## Bugs found in oFEM during the port
187
+
188
+ The port turned up several bugs in the MATLAB code. They are fixed in
189
+ oFEM (branch PagedArrays, commits 6c66ea5 and bb123ca), and both versions
190
+ now agree:
191
+
192
+ | MATLAB | Problem | Fix |
193
+ |---|---|---|
194
+ | `DirichletEdge.m` | only correct for zero data (summed `value . t` per quadrature point without weights, basis or edge length); function data rejected | L2 projection of the tangential trace (`tangentialProjection.m`) |
195
+ | `WaveguideInput.m` | same assignment, wrong sign for the Whitney DOFs | mode interpolation as before, set by the projection |
196
+ | `Robin.m` | equal row and column indices lumped the boundary mass matrix; one point per edge; areas and face edges mixed up in 3D; function values evaluated at the normal | trace integration through the adjacent elements (`traceData.m`, `traceBasis.m`); `bc.lumped = true` reproduces the old matrix |
197
+ | `AbsorbingBoundaryCondition.m` | lowest order on faces in the xy plane only | any degree and face orientation |
198
+ | `HCurlElement.AMS` | 2D interior stencil of the wrong size for degree >= 3 | correct group counts (`S G = 0`) |
199
+ | `DOFHandler.AMSDOFs` | only the last Dirichlet boundary excluded; no higher-order columns without boundary conditions | all fixed boundaries |
200
+ | `Geometry.uniform_refine` | one child of the 3D octahedron split overlaps its neighbours (non-conforming mesh) | `[5,8,6,10]` -> `[5,8,6,9]` |
201
+ | `Geometry.hypercube`, `barycentric_coordinates` | `matrixarray` coordinates broke `jacobiandata`, 3-D transpose, NaN indices: `pointLocation` could not run | double coordinates, `pagemtimes` |
202
+ | `tools/reconstruct.m`, `reconstructCurl.m` | barycentric coordinates of the returned points in the wrong order | fixed; `reconstruct2D.m` (could not run) delegates to `reconstruct` |
203
+ | `tools/matrixCurlRecovery.m` | missing `sign(detD)` | added |
204
+ | `tools/exportAtQuad.m` | undefined variables, invalid header | rewritten (UCD point cloud) |
205
+
206
+ The oFEM examples give the same results as before, except tempSquare and
207
+ tempCube, which now use the consistent Robin mass matrix.
208
+
209
+ ## Verified against MATLAB
210
+
211
+ * Mesh topology, `refTet` and Jacobians on the Diffusion2D, Capacitor3D and
212
+ EddyCurrent `wire` meshes are identical (up to the index shift); so are
213
+ the `.inp` meshes (CubitPlanarCapacitor2D/3D, CubitChargedSphere) incl.
214
+ parts, side sets and materials.
215
+ * H1, HCurl and HDiv bases (2D/3D, degree 0–4, both variants) agree to
216
+ 1e-14.
217
+ * H1: `el2DOF`, free DOFs, `S`, `b`, `u` and cell gradients agree to
218
+ rounding for Capacitor2D (P1), Capacitor3D (degree 1–3) and a degree-3
219
+ case with function and tensor materials, function and constant volume
220
+ forces and function Dirichlet data.
221
+ * Neumann + time stepping (Diffusion2D, P1) and time stepping at degree 3
222
+ (Heat2D): `S`, `M`, `b` and `u` after 10 implicit Euler steps agree to
223
+ rounding. Robin: tempSquare (P1, consistent and lumped) and tempCube
224
+ (degree 2, 54k DOFs, 20 time steps) agree to 1e-13.
225
+ * HCurl / HDiv: `el2DOF`, stiffness (scalar and tensor), mass (function and
226
+ tensor), constant and function volume forces, the curl load, the velocity
227
+ term and the free DOFs agree to 1e-15 for degree 0–2 on the rect, channel
228
+ and cube_h2 meshes; DirichletEdge with constant and function data to
229
+ 2e-15; `AMS` and `AMSDOFs` identical (also with two Dirichlet
230
+ boundaries).
231
+ * PEC cube (preconditionerScaling.m, MATLAB's right hand sides), PCG
232
+ iterations for h = 2, 4, 6, 8: none 72/167/244/322 (MATLAB
233
+ 72/168/245/322), AdditiveJacobi 31/53/67/86 (same), HX multiplicative
234
+ 9/10/11/11 (9/10/11/10), HX additive 17/21/21/23 (same).
235
+ * Eddy current sweep (eddyCurrentSweep.m, wire mesh, 93k DOFs): magnetic
236
+ energy and losses agree to 7 digits at 1e2 ... 1e6 Hz; HX BiCGStab
237
+ iterations 13/14/19/21/17 (MATLAB 13/14.5/19/20.5/17).
238
+ * Maxwell eigenvalues (MaxwellEigenvalue2D, degree 0–2): identical to
239
+ MATLAB's lobpcgModProj and to a dense eigensolver.
240
+ * `gradu`: 3D identical (5e-15); 2D identical except at 3 of 669 nodes
241
+ where the 10th nearest neighbour is a tie that the KD tree breaks
242
+ differently. `reconstruct`, `reconstructCurl`, `nodalRecovery` and
243
+ `nodalCurlRecovery` agree to 1e-15.
244
+
245
+ ## Performance
246
+
247
+ Unit cube, 560,380 tetrahedra, one process per run (MATLAB R2026a):
248
+
249
+ | Stage | MATLAB | Python |
250
+ |---|---|---|
251
+ | Load mesh (`load_from_msh` / `from_msh`) | 2.9 s | 1.5 s |
252
+ | DOF numbering, degree 1 / 2 | 0.02 s / 0.05 s | 0.00 s / 0.02 s |
253
+ | Assemble S + M, degree 1 (98k DOFs) | 0.7 s | 0.6 s |
254
+ | Assemble S + M, degree 2 (774k DOFs) | 5.9 s | 3.7 s |
255
+
256
+ Hiptmair-Xu, PEC cube with lowest order H(curl), PCG on S + M to 1e-8:
257
+
258
+ | | MATLAB (941k free DOFs) | Python (978k), `storage="tril"` | Python (978k), `storage="full"` |
259
+ |---|---|---|---|
260
+ | iterations | 11 | 11 | 11 |
261
+ | HX setup | 5.6 s | 7.4 s | 6.4 s |
262
+ | PCG solve | 3.2 s (0.29 s/it) | 2.9 s (0.27 s/it) | 2.0 s (0.18 s/it) |
263
+
264
+ (PCG inside `blas_threads()`, see below.)
265
+
266
+ Python peaks at 2.8 GB for this run (mesh, assembly and HX). Before the
267
+ direct SuperLU calls, the real / imaginary splitting and the aggregation
268
+ change, the PCG solve took 0.34 s per iteration on a 879k DOF cube.
269
+
270
+ OpenBLAS starts one thread per core (32 here). After every BLAS call of a
271
+ Krylov loop (vector operations, memory bound) its idle threads keep
272
+ spinning and slow down the single threaded sparse kernels (Gauss-Seidel,
273
+ CSR products). ofempy therefore runs its own Krylov loops (`solve` and
274
+ `parabolic_solve` with `method="cg"`, `gradient_solve`, the P1 projections,
275
+ `lobpcg_mod_proj`) with one BLAS thread (threadpoolctl;
276
+ `ofempy.linalg.KRYLOV_BLAS_THREADS`, `None` switches it off). Wrap your
277
+ own SciPy solver calls the same way, as the examples do:
278
+
279
+ ```python
280
+ from ofempy.linalg import blas_threads
281
+
282
+ with blas_threads():
283
+ x, info = spla.cg(A, b, rtol=1e-8, M=hx.aslinearoperator())
284
+ ```
285
+
286
+ Without the limit (32 BLAS threads) the PCG solve above takes 3.2 s
287
+ (`"tril"`) / 2.4 s (`"full"`), CG with AMG (`storage="full"`) on the 3D
288
+ heat problem (54k DOFs) 0.41 s instead of 0.27 s, and LOBPCG for the
289
+ degree 2 cavity 4.8 s instead of 2.9 s.
290
+
291
+ ## Status
292
+
293
+ | MATLAB | Python |
294
+ |---|---|
295
+ | `Geometry.m` | `ofempy/geometry.py`, `ofempy/io/inp.py`, `ofempy/io/vtu.py` |
296
+ | `DOFHandler.m` | `ofempy/dofs.py` |
297
+ | `Physical_Problem.m`, `Initial_Condition.m`, `Volume_force.m`, `materials/Material.m` | `ofempy/problem.py`, `ofempy/volume_force.py`, `ofempy/materials.py` |
298
+ | `elements/H1Element.m`, `HCurlElement.m`, `HDivElement.m` | `ofempy/elements/` |
299
+ | `tools/gaussSimplex.m`, `LegPoly.m`, `refTensorMatrices.m`, `geometryFactor.m` | `ofempy/quadrature.py`, `ofempy/legendre.py`, `ofempy/assembly.py` |
300
+ | `boundary/*` | `ofempy/boundary/` |
301
+ | `preconditioners/SmoothedAggregationAMG.m`, `HiptmairXu.m`, `AdditiveJacobi.m` | `ofempy/preconditioners/` |
302
+ | `solvers/lobpcgModProj.m` | `ofempy/solvers/lobpcg.py` |
303
+ | `tools/reconstruct*`, `nodal*Recovery`, `matrix*Recovery`, `integrateOverROI`, `pointLocation`, `plot`, `exportAtQuad` | `ofempy/tools.py` |
304
+
305
+ Not ported:
306
+
307
+ * `+oBEM` (a working BEM implementation lives in a separate repository).
308
+ * The older LOBPCG variants, `MultiLevelV.m` (unfinished), `pcgTest.m`
309
+ (SciPy has `lobpcg` and `cg`), the Nedelec variants
310
+ (`NedelecIngel*.m`, `NedelecZagl*.m`, `*_original.m`), `shrinkMesh.m`
311
+ and `degenTensorTet.m` (unfinished), and `HCurlElement.el2edges` (equal
312
+ to `volume_force` with per element values).
313
+
314
+ ## License
315
+
316
+ MIT, see [LICENSE](LICENSE).
ofempy-0.1.0/README.md ADDED
@@ -0,0 +1,290 @@
1
+ # ofempy
2
+
3
+ <https://github.com/Myromax/oFEMpy>
4
+
5
+ Python port of [oFEM](../oFEM) (`source/+ofem_v2`): H1, H(curl) and H(div)
6
+ finite elements of arbitrary degree on triangles and tetrahedra, boundary
7
+ conditions, time stepping, AMG / Hiptmair-Xu preconditioners and LOBPCG.
8
+
9
+ ## Setup
10
+
11
+ ```sh
12
+ python3 -m venv .venv
13
+ .venv/bin/pip install -e '.[test]'
14
+ .venv/bin/python -m pytest
15
+ ```
16
+
17
+ Dependencies: numpy, scipy (>= 1.12), sympy, gmsh, pyamg, threadpoolctl;
18
+ matplotlib for plots (`pip install -e '.[plot]'`); the tests also use
19
+ meshio.
20
+
21
+ The PyPI `gmsh` wheel links against `libGLU.so.1`. If `import gmsh` fails
22
+ with `libGLU.so.1: cannot open shared object file`, either install the
23
+ system package (`mesa-libGLU` on Fedora; `rpm-ostree install mesa-libGLU`
24
+ on Atomic/Bazzite), or copy a 64-bit `libGLU.so.1` next to
25
+ `.venv/lib/libgmsh.so*` (the library's runpath includes its own folder).
26
+
27
+ ## Meshes
28
+
29
+ Meshes come straight from the gmsh Python API, without writing a file:
30
+
31
+ ```python
32
+ import gmsh
33
+ from ofempy import Geometry
34
+
35
+ gmsh.initialize()
36
+ gmsh.model.occ.addRectangle(0, 0, 0, 1, 1)
37
+ gmsh.model.occ.synchronize()
38
+ gmsh.model.addPhysicalGroup(2, [1], name="M:Domain")
39
+ gmsh.model.addPhysicalGroup(1, [4], name="BD:left")
40
+ gmsh.model.mesh.generate(2)
41
+ mesh = Geometry.from_gmsh() # reads the current model
42
+ gmsh.finalize()
43
+ ```
44
+
45
+ Files work as well: `Geometry.from_msh(path)` (through gmsh) and
46
+ `Geometry.from_inp(path)` (Cubit / Trelis Abaqus files, pure Python parser:
47
+ side sets become boundaries, section materials are attached to the parts
48
+ with the Abaqus property names). `Geometry.hypercube(x0, extent)` and
49
+ `uniform_refine()` build structured meshes.
50
+
51
+ Physical groups follow the oFEM naming: `M:` parts, `BD:` boundaries,
52
+ `ROI:`/`ROI1:`/`ROI2:` regions of interest.
53
+
54
+ oFEM's MEX reader only reads MSH 2.2 (a MSH 4.1 file makes it hang); write
55
+ meshes meant for MATLAB with `gmsh.option.setNumber("Mesh.MshFileVersion", 2.2)`.
56
+
57
+ ## Example: Capacitor2D
58
+
59
+ ```python
60
+ from ofempy import *
61
+
62
+ mesh = Geometry.from_msh("CapacitorExample2d.msh")
63
+ fe = H1Element(2, 1).compute_basis()
64
+ dofs = DOFHandler(mesh); dofs.attach(fe)
65
+ cap = PhysicalProblem(fe, mesh, has_stiffness=True)
66
+ cap.attach_dof_handler(dofs)
67
+ mesh.set_material("Paper", Material(epsilon=1e-4))
68
+ mesh.set_material("Glas", Material(epsilon=5e-4))
69
+ cap.set_para_s("epsilon")
70
+ cap.set_boundary_condition(Dirichlet(0, "left", mesh))
71
+ cap.set_boundary_condition(Dirichlet(5, "right", mesh))
72
+ dofs.generate_dofs()
73
+ cap.assemble()
74
+ cap.solve()
75
+ cap.export_vtu("export/2dCapacitor", "U", cell_data={"E": cap.grad_cell()})
76
+ ```
77
+
78
+ ## Examples
79
+
80
+ [examples/](examples/README.md) contains ports of all oFEM examples (H1,
81
+ H(curl), H(div), tools). They are not part of the package; the fast ones
82
+ run with `pytest -m examples`.
83
+
84
+ ## Differences to the MATLAB API
85
+
86
+ * Indices are 0-based: `el`, `ed`, `el2ed`, `fa`, `el2fa`, `fa2ed`, DOFs,
87
+ and `refTet` in {0, 1}.
88
+ * Per-element arrays have the element index first: `co` is `(Nco, dim)`,
89
+ `DinvT`/`Dk` are `(Ne, d, d)`, `detD` is `(Ne,)`; field values are
90
+ `(Ne, Np, dim)` instead of `dim x Ne x Np`. Connectivity is `int32`.
91
+ * Functions of space (materials, forces, boundary data) take points as
92
+ `(N, dim)` arrays and return `(N,)`, `(N, dim)` or `(N, d, d)`; boundary
93
+ data may also be `f(X, n)` with the outer unit normals `n`.
94
+ * Method names are snake_case (`generate_dofs`, `set_para_s`,
95
+ `set_boundary_condition`, `grad_cell`, `ams_dofs`, ...).
96
+ * `gauss_simplex(dim, order)` returns `(w, l)` with `l` of shape
97
+ `(Nq, dim)`; in 1D `order` is the polynomial degree (as in 2D/3D), not
98
+ the number of points.
99
+ * Element bases are evaluated at many points at once: `phi(l)` is
100
+ `(2, Nq, 1, Ns)`, `dphi(l)` / `N(l)` `(2, Nq, dim, Ns)`, the first axis
101
+ being the `refTet` variant. No precomputed element files are needed;
102
+ the bases are built with sympy in seconds, once per element type, degree
103
+ and dimension in a process (later `compute_basis` calls reuse them).
104
+ * Fixed DOFs are a boolean mask (`DOFHandler.fixed`); `freeDOFs` is derived
105
+ from it. Between two Dirichlet boundaries that share nodes (for
106
+ `DirichletEdge` / `NormalTrace`: edges) the first one keeps them (with a
107
+ warning, or `assemble(interactive=True)` to choose); natural and Robin
108
+ boundaries never take nodes from a Dirichlet one.
109
+ * `PhysicalProblem.solve(matrix=...)` lifts the Dirichlet values with the
110
+ matrix it solves (Physical_Problem lifted with `S + M + D + M_robin` but
111
+ solved with `S`) and returns a complex `u` for complex systems.
112
+ `solve` and `parabolic_solve` take `method="cg"` (CG with smoothed
113
+ aggregation AMG) for large 3D and higher order problems, whose LU
114
+ factorisation is slow (54k DOFs in 3D: 40 s).
115
+ * Boundary conditions need no boundary element (`feBd`):
116
+ `Neumann(value, name, mesh)`, `Robin(value, alpha, beta, name, mesh,
117
+ lumped=False)`, `AbsorbingBoundaryCondition(name, mesh, factor)`,
118
+ `DirichletEdge(value, name, mesh)`, `NormalTrace(name, mesh, value=0)`
119
+ (a nonzero normal trace is an extension), `WaveguideInput(u_in, x, name,
120
+ mesh)`.
121
+ * `lobpcg_mod_proj(X, S, M, n, maxit, tol, Y, dofs, YMY)`: MATLAB argument
122
+ order without the unused `C`.
123
+ * Export writes VTK `.vtu` (ParaView) instead of UCD `.inp`, with an own
124
+ writer (`ofempy/io/vtu.py`): zlib level 1 instead of meshio's level 6
125
+ gives the same file size for FE fields and writes them 1.6x faster
126
+ (exporting every time step dominated some examples); complex fields
127
+ become `<name>_re` / `<name>_im`. `tools.export_points` replaces
128
+ `exportAtQuad`.
129
+ * `PhysicalProblem.gradu` fits the local quadratic centred at the node
130
+ (same fit as MATLAB, better conditioned).
131
+ * Solvers and preconditioners keep MATLAB's memory design by default
132
+ (`storage="tril"`): the system matrix and every AMG level are stored as
133
+ `tril(A)` + `diag(A)` only. The triangle is kept with a unit diagonal,
134
+ and both Gauss-Seidel sweeps call SuperLU's triangular solve on it
135
+ directly (half the time of `spsolve_triangular`, which resets the
136
+ diagonal, checks the format and converts the matrix on every call).
137
+ `storage="full"` keeps `A` in CSR (the caller's matrix, not a copy) and
138
+ sweeps with PyAMG's compiled Gauss-Seidel kernel, faster again; as the
139
+ finest matrix is then shared with the Krylov solver, an AMG hierarchy
140
+ needs less memory than with the triangle (H1 degree 2: half), while
141
+ `HiptmairXu.from_problem` keeps a full copy of the restricted matrix.
142
+ `solve(method="cg")` uses it. Assembled matrices are symmetric up to
143
+ rounding; they are used as they are (no symmetrised copy). Complex
144
+ vectors are preconditioned by real and imaginary part (SciPy converts a
145
+ real sparse matrix to complex on every product with a complex vector).
146
+ * Aggregation uses PyAMG's C++ `standard_aggregation` (the same greedy
147
+ algorithm). Nodes without strong connections are left to the smoother,
148
+ as in PyAMG and the SA literature; SmoothedAggregationAMG.m made each a
149
+ one-node aggregate, which keeps the coarse grids of higher order
150
+ matrices large (H1 degree 4: operator complexity 4.2 instead of 1.3,
151
+ setup 13 s instead of 1.5 s, same iteration count). The AMG damping
152
+ estimate uses a seeded random start.
153
+ * SciPy has no sparse or incomplete Cholesky: `'chol'` uses CHOLMOD if
154
+ scikit-sparse is installed, else SuperLU; `'ict'` uses ILUT (`spilu`).
155
+ `AdditiveJacobi.gradient_correction` also offers `solver='amg'`. The
156
+ accurate `gradient_solve` uses PCG with AMG: PCG with the non-symmetric
157
+ ILU stagnated at a relative residual of 1e-2 in the eddy current sweep
158
+ (MATLAB's `ichol` is symmetric).
159
+
160
+ ## Bugs found in oFEM during the port
161
+
162
+ The port turned up several bugs in the MATLAB code. They are fixed in
163
+ oFEM (branch PagedArrays, commits 6c66ea5 and bb123ca), and both versions
164
+ now agree:
165
+
166
+ | MATLAB | Problem | Fix |
167
+ |---|---|---|
168
+ | `DirichletEdge.m` | only correct for zero data (summed `value . t` per quadrature point without weights, basis or edge length); function data rejected | L2 projection of the tangential trace (`tangentialProjection.m`) |
169
+ | `WaveguideInput.m` | same assignment, wrong sign for the Whitney DOFs | mode interpolation as before, set by the projection |
170
+ | `Robin.m` | equal row and column indices lumped the boundary mass matrix; one point per edge; areas and face edges mixed up in 3D; function values evaluated at the normal | trace integration through the adjacent elements (`traceData.m`, `traceBasis.m`); `bc.lumped = true` reproduces the old matrix |
171
+ | `AbsorbingBoundaryCondition.m` | lowest order on faces in the xy plane only | any degree and face orientation |
172
+ | `HCurlElement.AMS` | 2D interior stencil of the wrong size for degree >= 3 | correct group counts (`S G = 0`) |
173
+ | `DOFHandler.AMSDOFs` | only the last Dirichlet boundary excluded; no higher-order columns without boundary conditions | all fixed boundaries |
174
+ | `Geometry.uniform_refine` | one child of the 3D octahedron split overlaps its neighbours (non-conforming mesh) | `[5,8,6,10]` -> `[5,8,6,9]` |
175
+ | `Geometry.hypercube`, `barycentric_coordinates` | `matrixarray` coordinates broke `jacobiandata`, 3-D transpose, NaN indices: `pointLocation` could not run | double coordinates, `pagemtimes` |
176
+ | `tools/reconstruct.m`, `reconstructCurl.m` | barycentric coordinates of the returned points in the wrong order | fixed; `reconstruct2D.m` (could not run) delegates to `reconstruct` |
177
+ | `tools/matrixCurlRecovery.m` | missing `sign(detD)` | added |
178
+ | `tools/exportAtQuad.m` | undefined variables, invalid header | rewritten (UCD point cloud) |
179
+
180
+ The oFEM examples give the same results as before, except tempSquare and
181
+ tempCube, which now use the consistent Robin mass matrix.
182
+
183
+ ## Verified against MATLAB
184
+
185
+ * Mesh topology, `refTet` and Jacobians on the Diffusion2D, Capacitor3D and
186
+ EddyCurrent `wire` meshes are identical (up to the index shift); so are
187
+ the `.inp` meshes (CubitPlanarCapacitor2D/3D, CubitChargedSphere) incl.
188
+ parts, side sets and materials.
189
+ * H1, HCurl and HDiv bases (2D/3D, degree 0–4, both variants) agree to
190
+ 1e-14.
191
+ * H1: `el2DOF`, free DOFs, `S`, `b`, `u` and cell gradients agree to
192
+ rounding for Capacitor2D (P1), Capacitor3D (degree 1–3) and a degree-3
193
+ case with function and tensor materials, function and constant volume
194
+ forces and function Dirichlet data.
195
+ * Neumann + time stepping (Diffusion2D, P1) and time stepping at degree 3
196
+ (Heat2D): `S`, `M`, `b` and `u` after 10 implicit Euler steps agree to
197
+ rounding. Robin: tempSquare (P1, consistent and lumped) and tempCube
198
+ (degree 2, 54k DOFs, 20 time steps) agree to 1e-13.
199
+ * HCurl / HDiv: `el2DOF`, stiffness (scalar and tensor), mass (function and
200
+ tensor), constant and function volume forces, the curl load, the velocity
201
+ term and the free DOFs agree to 1e-15 for degree 0–2 on the rect, channel
202
+ and cube_h2 meshes; DirichletEdge with constant and function data to
203
+ 2e-15; `AMS` and `AMSDOFs` identical (also with two Dirichlet
204
+ boundaries).
205
+ * PEC cube (preconditionerScaling.m, MATLAB's right hand sides), PCG
206
+ iterations for h = 2, 4, 6, 8: none 72/167/244/322 (MATLAB
207
+ 72/168/245/322), AdditiveJacobi 31/53/67/86 (same), HX multiplicative
208
+ 9/10/11/11 (9/10/11/10), HX additive 17/21/21/23 (same).
209
+ * Eddy current sweep (eddyCurrentSweep.m, wire mesh, 93k DOFs): magnetic
210
+ energy and losses agree to 7 digits at 1e2 ... 1e6 Hz; HX BiCGStab
211
+ iterations 13/14/19/21/17 (MATLAB 13/14.5/19/20.5/17).
212
+ * Maxwell eigenvalues (MaxwellEigenvalue2D, degree 0–2): identical to
213
+ MATLAB's lobpcgModProj and to a dense eigensolver.
214
+ * `gradu`: 3D identical (5e-15); 2D identical except at 3 of 669 nodes
215
+ where the 10th nearest neighbour is a tie that the KD tree breaks
216
+ differently. `reconstruct`, `reconstructCurl`, `nodalRecovery` and
217
+ `nodalCurlRecovery` agree to 1e-15.
218
+
219
+ ## Performance
220
+
221
+ Unit cube, 560,380 tetrahedra, one process per run (MATLAB R2026a):
222
+
223
+ | Stage | MATLAB | Python |
224
+ |---|---|---|
225
+ | Load mesh (`load_from_msh` / `from_msh`) | 2.9 s | 1.5 s |
226
+ | DOF numbering, degree 1 / 2 | 0.02 s / 0.05 s | 0.00 s / 0.02 s |
227
+ | Assemble S + M, degree 1 (98k DOFs) | 0.7 s | 0.6 s |
228
+ | Assemble S + M, degree 2 (774k DOFs) | 5.9 s | 3.7 s |
229
+
230
+ Hiptmair-Xu, PEC cube with lowest order H(curl), PCG on S + M to 1e-8:
231
+
232
+ | | MATLAB (941k free DOFs) | Python (978k), `storage="tril"` | Python (978k), `storage="full"` |
233
+ |---|---|---|---|
234
+ | iterations | 11 | 11 | 11 |
235
+ | HX setup | 5.6 s | 7.4 s | 6.4 s |
236
+ | PCG solve | 3.2 s (0.29 s/it) | 2.9 s (0.27 s/it) | 2.0 s (0.18 s/it) |
237
+
238
+ (PCG inside `blas_threads()`, see below.)
239
+
240
+ Python peaks at 2.8 GB for this run (mesh, assembly and HX). Before the
241
+ direct SuperLU calls, the real / imaginary splitting and the aggregation
242
+ change, the PCG solve took 0.34 s per iteration on a 879k DOF cube.
243
+
244
+ OpenBLAS starts one thread per core (32 here). After every BLAS call of a
245
+ Krylov loop (vector operations, memory bound) its idle threads keep
246
+ spinning and slow down the single threaded sparse kernels (Gauss-Seidel,
247
+ CSR products). ofempy therefore runs its own Krylov loops (`solve` and
248
+ `parabolic_solve` with `method="cg"`, `gradient_solve`, the P1 projections,
249
+ `lobpcg_mod_proj`) with one BLAS thread (threadpoolctl;
250
+ `ofempy.linalg.KRYLOV_BLAS_THREADS`, `None` switches it off). Wrap your
251
+ own SciPy solver calls the same way, as the examples do:
252
+
253
+ ```python
254
+ from ofempy.linalg import blas_threads
255
+
256
+ with blas_threads():
257
+ x, info = spla.cg(A, b, rtol=1e-8, M=hx.aslinearoperator())
258
+ ```
259
+
260
+ Without the limit (32 BLAS threads) the PCG solve above takes 3.2 s
261
+ (`"tril"`) / 2.4 s (`"full"`), CG with AMG (`storage="full"`) on the 3D
262
+ heat problem (54k DOFs) 0.41 s instead of 0.27 s, and LOBPCG for the
263
+ degree 2 cavity 4.8 s instead of 2.9 s.
264
+
265
+ ## Status
266
+
267
+ | MATLAB | Python |
268
+ |---|---|
269
+ | `Geometry.m` | `ofempy/geometry.py`, `ofempy/io/inp.py`, `ofempy/io/vtu.py` |
270
+ | `DOFHandler.m` | `ofempy/dofs.py` |
271
+ | `Physical_Problem.m`, `Initial_Condition.m`, `Volume_force.m`, `materials/Material.m` | `ofempy/problem.py`, `ofempy/volume_force.py`, `ofempy/materials.py` |
272
+ | `elements/H1Element.m`, `HCurlElement.m`, `HDivElement.m` | `ofempy/elements/` |
273
+ | `tools/gaussSimplex.m`, `LegPoly.m`, `refTensorMatrices.m`, `geometryFactor.m` | `ofempy/quadrature.py`, `ofempy/legendre.py`, `ofempy/assembly.py` |
274
+ | `boundary/*` | `ofempy/boundary/` |
275
+ | `preconditioners/SmoothedAggregationAMG.m`, `HiptmairXu.m`, `AdditiveJacobi.m` | `ofempy/preconditioners/` |
276
+ | `solvers/lobpcgModProj.m` | `ofempy/solvers/lobpcg.py` |
277
+ | `tools/reconstruct*`, `nodal*Recovery`, `matrix*Recovery`, `integrateOverROI`, `pointLocation`, `plot`, `exportAtQuad` | `ofempy/tools.py` |
278
+
279
+ Not ported:
280
+
281
+ * `+oBEM` (a working BEM implementation lives in a separate repository).
282
+ * The older LOBPCG variants, `MultiLevelV.m` (unfinished), `pcgTest.m`
283
+ (SciPy has `lobpcg` and `cg`), the Nedelec variants
284
+ (`NedelecIngel*.m`, `NedelecZagl*.m`, `*_original.m`), `shrinkMesh.m`
285
+ and `degenTensorTet.m` (unfinished), and `HCurlElement.el2edges` (equal
286
+ to `volume_force` with per element values).
287
+
288
+ ## License
289
+
290
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,24 @@
1
+ """Python port of oFEM (ofem_v2).
2
+
3
+ Conventions that differ from the MATLAB version:
4
+
5
+ * all indices are 0-based (``el``, ``ed``, ``el2ed``, ``refTet``, DOFs, ...),
6
+ * per-element arrays have the element index first, e.g. ``DinvT`` has
7
+ shape ``(Ne, d, d)`` instead of ``d x d x Ne``,
8
+ * coordinates are stored as ``co`` with shape ``(Nco, dim)``, and
9
+ functions of space take points as ``(N, dim)`` arrays.
10
+ """
11
+
12
+ from .boundary import (AbsorbingBoundaryCondition, Dirichlet, DirichletEdge, Neumann, NormalTrace, Robin,
13
+ WaveguideInput)
14
+ from .dofs import DOFHandler
15
+ from .elements import H1Element, HCurlElement, HDivElement
16
+ from .geometry import Boundary, Geometry, Part
17
+ from .materials import Material
18
+ from .problem import InitialCondition, PhysicalProblem
19
+ from .quadrature import gauss_simplex
20
+ from .volume_force import VolumeForce
21
+
22
+ __all__ = ["AbsorbingBoundaryCondition", "Boundary", "DOFHandler", "Dirichlet", "DirichletEdge", "Geometry", "H1Element", "HCurlElement",
23
+ "HDivElement", "InitialCondition", "Material", "Neumann", "NormalTrace", "Part", "PhysicalProblem",
24
+ "Robin", "VolumeForce", "WaveguideInput", "gauss_simplex"]