openseespy-solvers 0.1.0__tar.gz

openseespy_solvers-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+site/
+*.csv

openseespy_solvers-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Documentation: [Recommended solvers](recommended-solvers.md) (CPU/GPU defaults, performance notes vs native OpenSees); installation quick-start recipes.
+- CuPy `eigsh` for `K x = λ M x` with shift-invert (`mass_mode`: `diagonal`, `lumped`, `general`).
+- nvMath `direct_solver` factory: NVIDIA `nvmath.sparse.advanced.DirectSolver` with plan/factorize/solve caching; namespace `openseespy_solvers.nvmath`; optional `[nvmath]` extra (`nvmath-python[cpu]>=0.8.0`). CPU execution uses SciPy sparse matrices; GPU execution also requires `[cupy]` and a GPU-capable nvmath-python install (e.g. `nvmath-python[cu12-dx]`).
+- SciPy `umfpack` solver: 64-bit UMFPACK direct solver (`scikits.umfpack.UmfpackContext("dl")`) with cached symbolic/numeric factorization; optional `[umfpack]` extra (`scikit-umfpack>=0.3.3`).
+
+### Changed
+
+- CuPy `eigsh` default `mass_mode` is `general` (was `diagonal`).
+- `nvmath.direct_solver` default `device` is `'gpu'` (was auto CPU when CuPy missing).
+- CuPy `eigsh` `diagonal` / `lumped` use GPU shift-invert with cached diagonal mass (replaces mass-normalized Lanczos).
+- nvMath documented and packaged as a **GPU** backend (like CuPy): install `nvmath-python[cu12]` or `[cu13]` manually; removed `[nvmath]` pip extra.
+- nvMath factory named `direct_solver` (not `spsolve`) to mirror `nvmath.sparse.advanced.direct_solver` / `DirectSolver`; SciPy and CuPy backends keep `spsolve` for their respective `scipy.sparse.linalg.spsolve` / `cupyx.scipy.sparse.linalg.spsolve` wrappers.
+- Rename `.to_opensees()` to `.to_openseespy()` on solver objects (breaking API change).
+- Require Python ≥ 3.12, NumPy ≥ 1.26, SciPy ≥ 1.12; optional CuPy ≥ 13 via `[cupy]`.
+- Rename optional extra `[gpu]` → `[cupy]` (one extra per backend).
+- Simplify examples to two brick-bar solver-comparison scripts (`brick_bar.py` static, `brick_bar_eigen.py` eigen); remove the RC frame and shell examples.
+
+## [0.1.0] - 2026-06-03
+
+### Added
+
+- Per-backend namespaces `openseespy_solvers.scipy` and `openseespy_solvers.cupy`.
+- SciPy solvers: `spsolve`, `cg`, `gmres`, `eigsh`, `lobpcg`.
+- CuPy solvers: `spsolve`, `cg`, `gmres`, `lobpcg` (no generalized `eigsh`).
+- `.to_opensees()` helper for OpenSeesPy `PythonSparse` system and eigen commands.
+- `formAp` matrix-vector product on all linear solvers.
+- `copy.copy` support via `__copy__` / `__deepcopy__` for OpenSees SOE cloning.
+- Exposed solver arrays: `A`, `b`, `x` (linear) and `K`, `M` (eigen).
+- Preconditioner factories: `M=` accepts a ready operator or callable `M(A)`.
+- Built-in SciPy preconditioners in `openseespy_solvers.scipy.precond` (`jacobi`, `ilu`).
+- Solver statistics via `.stats`.
+- Examples and tests that do not require OpenSeesPy.

openseespy_solvers-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, openseespy-solvers contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

openseespy_solvers-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: openseespy-solvers
+Version: 0.1.0
+Summary: Ready-to-use, SciPy-style PythonSparse solvers for OpenSeesPy
+Project-URL: Homepage, https://github.com/gaaraujo/openseespy-solvers
+Project-URL: Documentation, https://openseespy-solvers.readthedocs.io/
+Project-URL: Issues, https://github.com/gaaraujo/openseespy-solvers/issues
+Author: openseespy-solvers contributors
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, openseespy-solvers contributors
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Keywords: eigen,finite-element,opensees,openseespy,scipy,solver,sparse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.12
+Provides-Extra: cupy
+Requires-Dist: cupy>=13.0; extra == 'cupy'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: opensees
+Requires-Dist: openseespy; extra == 'opensees'
+Provides-Extra: umfpack
+Requires-Dist: scikit-umfpack>=0.3.3; extra == 'umfpack'
+Description-Content-Type: text/markdown
+
+# openseespy-solvers
+
+Sparse linear algebra solvers for OpenSeesPy
+[`PythonSparse`](https://opensees.github.io/OpenSeesDocumentation/user/manual/analysis/system/PythonSparse.html)
+commands.
+
+**Documentation:** [openseespy-solvers.readthedocs.io](https://openseespy-solvers.readthedocs.io/)
+
+## Installation
+
+Requires **Python ≥ 3.12**, **NumPy ≥ 1.26**, **SciPy ≥ 1.12**, and **serial OpenSeesPy**
+(parallel/MPI OpenSeesPy builds are not supported — see
+[docs](https://openseespy-solvers.readthedocs.io/en/latest/user-guide/pythonsparse-interface/#parallelism)).
+
+### Full setup from scratch
+
+Copy-paste overview — see the [installation guide](https://openseespy-solvers.readthedocs.io/en/latest/installation/#full-setup) for platform notes (UMFPACK, GPU wheels) and the complete verification checklist.
+
+```bash
+# 1. Environment (conda or venv — all platforms)
+conda create -n openseespy-solvers python=3.12 -y
+conda activate openseespy-solvers
+
+# 2. Clone (examples and pytest are in the repo, not the pip wheel)
+git clone https://github.com/gaaraujo/openseespy-solvers.git
+cd openseespy-solvers
+
+# 3. Install
+pip install -e ".[dev,opensees]"
+
+# 4–5. Optional backends — UMFPACK, CuPy, nvMath (see installation guide)
+# 6. pip check
+# 7. Verify
+pytest
+cd examples && python solvers/scipy_spsolve.py && python solvers/scipy_eigsh.py
+python brick_bar.py && python brick_bar_eigen.py
+```
+
+GPU tests in `pytest` run when CuPy/nvMath are installed; skipped otherwise.
+
+### Quick install (library only)
+
+```bash
+pip install openseespy-solvers
+pip install openseespy-solvers[opensees]   # if OpenSeesPy is missing
+```
+
+## Recommended solvers
+
+| Analysis | GPU (CUDA) | CPU |
+|----------|------------|-----|
+| Linear (`PythonSparse`, static/transient/…) | `nvmath.direct_solver` | `scipy.spsolve` or `scipy.umfpack` |
+| Eigen | `cupy.eigsh` | `scipy.eigsh` |
+
+These `PythonSparse` backends are **often faster** than native OpenSees sparse/direct/eigen
+solvers on medium-to-large models because they use optimized library implementations.
+Details: [recommended solvers](https://openseespy-solvers.readthedocs.io/en/latest/recommended-solvers/).
+
+## Example
+
+```python
+from openseespy_solvers import hybrid
+from openseespy_solvers.scipy import spsolve
+
+solver = hybrid(spsolve(), rtol=1e-6, restart=50)
+ops.system("PythonSparse", solver.to_openseespy())
+ops.analyze(n)
+```
+
+For Newton or transient steps where the tangent changes slowly, ``hybrid`` factorizes once
+then reuses that factorization as a GMRES preconditioner until the system size changes or
+GMRES fails to converge.
+
+## Submodules
+
+| Module | Functions |
+|--------|-----------|
+| `openseespy_solvers.scipy` | `spsolve`, `umfpack`, `cg`, `gmres`, `eigsh`, `lobpcg` |
+| `openseespy_solvers.scipy.precond` | `jacobi`, `ilu`, `direct` |
+| `openseespy_solvers.cupy` | `spsolve`, `cg`, `gmres`, `eigsh`, `lobpcg` (GPU) |
+| `openseespy_solvers.cupy.precond` | `jacobi`, `ilu`, `direct` |
+| `openseespy_solvers.nvmath` | `direct_solver` (GPU) |
+| `openseespy_solvers.hybrid` | `hybrid(direct=...)` — frozen factorization + GMRES |
+
+Factory signatures match [`scipy.sparse.linalg`](https://docs.scipy.org/doc/scipy/reference/sparse.linalg.html)
+and [`cupyx.scipy.sparse.linalg`](https://docs.cupy.dev/en/stable/reference/scipy_sparse.html);
+`A` and `b` are supplied by OpenSees at solve time.
+
+See the [tutorial](https://openseespy-solvers.readthedocs.io/en/latest/getting-started/) and
+[API reference](https://openseespy-solvers.readthedocs.io/en/latest/api/scipy/) for details.
+
+## GitHub
+
+Repository: [github.com/gaaraujo/openseespy-solvers](https://github.com/gaaraujo/openseespy-solvers).
+Report bugs and ask questions via
+[issues](https://github.com/gaaraujo/openseespy-solvers/issues); send contributions
+(pull requests) there as well.
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).

openseespy_solvers-0.1.0/README.md

@@ -0,0 +1,101 @@
+# openseespy-solvers
+
+Sparse linear algebra solvers for OpenSeesPy
+[`PythonSparse`](https://opensees.github.io/OpenSeesDocumentation/user/manual/analysis/system/PythonSparse.html)
+commands.
+
+**Documentation:** [openseespy-solvers.readthedocs.io](https://openseespy-solvers.readthedocs.io/)
+
+## Installation
+
+Requires **Python ≥ 3.12**, **NumPy ≥ 1.26**, **SciPy ≥ 1.12**, and **serial OpenSeesPy**
+(parallel/MPI OpenSeesPy builds are not supported — see
+[docs](https://openseespy-solvers.readthedocs.io/en/latest/user-guide/pythonsparse-interface/#parallelism)).
+
+### Full setup from scratch
+
+Copy-paste overview — see the [installation guide](https://openseespy-solvers.readthedocs.io/en/latest/installation/#full-setup) for platform notes (UMFPACK, GPU wheels) and the complete verification checklist.
+
+```bash
+# 1. Environment (conda or venv — all platforms)
+conda create -n openseespy-solvers python=3.12 -y
+conda activate openseespy-solvers
+
+# 2. Clone (examples and pytest are in the repo, not the pip wheel)
+git clone https://github.com/gaaraujo/openseespy-solvers.git
+cd openseespy-solvers
+
+# 3. Install
+pip install -e ".[dev,opensees]"
+
+# 4–5. Optional backends — UMFPACK, CuPy, nvMath (see installation guide)
+# 6. pip check
+# 7. Verify
+pytest
+cd examples && python solvers/scipy_spsolve.py && python solvers/scipy_eigsh.py
+python brick_bar.py && python brick_bar_eigen.py
+```
+
+GPU tests in `pytest` run when CuPy/nvMath are installed; skipped otherwise.
+
+### Quick install (library only)
+
+```bash
+pip install openseespy-solvers
+pip install openseespy-solvers[opensees]   # if OpenSeesPy is missing
+```
+
+## Recommended solvers
+
+| Analysis | GPU (CUDA) | CPU |
+|----------|------------|-----|
+| Linear (`PythonSparse`, static/transient/…) | `nvmath.direct_solver` | `scipy.spsolve` or `scipy.umfpack` |
+| Eigen | `cupy.eigsh` | `scipy.eigsh` |
+
+These `PythonSparse` backends are **often faster** than native OpenSees sparse/direct/eigen
+solvers on medium-to-large models because they use optimized library implementations.
+Details: [recommended solvers](https://openseespy-solvers.readthedocs.io/en/latest/recommended-solvers/).
+
+## Example
+
+```python
+from openseespy_solvers import hybrid
+from openseespy_solvers.scipy import spsolve
+
+solver = hybrid(spsolve(), rtol=1e-6, restart=50)
+ops.system("PythonSparse", solver.to_openseespy())
+ops.analyze(n)
+```
+
+For Newton or transient steps where the tangent changes slowly, ``hybrid`` factorizes once
+then reuses that factorization as a GMRES preconditioner until the system size changes or
+GMRES fails to converge.
+
+## Submodules
+
+| Module | Functions |
+|--------|-----------|
+| `openseespy_solvers.scipy` | `spsolve`, `umfpack`, `cg`, `gmres`, `eigsh`, `lobpcg` |
+| `openseespy_solvers.scipy.precond` | `jacobi`, `ilu`, `direct` |
+| `openseespy_solvers.cupy` | `spsolve`, `cg`, `gmres`, `eigsh`, `lobpcg` (GPU) |
+| `openseespy_solvers.cupy.precond` | `jacobi`, `ilu`, `direct` |
+| `openseespy_solvers.nvmath` | `direct_solver` (GPU) |
+| `openseespy_solvers.hybrid` | `hybrid(direct=...)` — frozen factorization + GMRES |
+
+Factory signatures match [`scipy.sparse.linalg`](https://docs.scipy.org/doc/scipy/reference/sparse.linalg.html)
+and [`cupyx.scipy.sparse.linalg`](https://docs.cupy.dev/en/stable/reference/scipy_sparse.html);
+`A` and `b` are supplied by OpenSees at solve time.
+
+See the [tutorial](https://openseespy-solvers.readthedocs.io/en/latest/getting-started/) and
+[API reference](https://openseespy-solvers.readthedocs.io/en/latest/api/scipy/) for details.
+
+## GitHub
+
+Repository: [github.com/gaaraujo/openseespy-solvers](https://github.com/gaaraujo/openseespy-solvers).
+Report bugs and ask questions via
+[issues](https://github.com/gaaraujo/openseespy-solvers/issues); send contributions
+(pull requests) there as well.
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).

openseespy_solvers-0.1.0/examples/README.md

@@ -0,0 +1,129 @@
+# Examples
+
+## Layout
+
+| Location | Purpose |
+|----------|---------|
+| [`brick_bar.py`](brick_bar.py) | Benchmark-style static sweep vs native OpenSees solvers |
+| [`brick_bar_eigen.py`](brick_bar_eigen.py) | Benchmark-style eigen sweep vs native OpenSees solvers |
+| [`solvers/`](solvers/) | **One script per solver factory** (small mesh, fast smoke test) |
+| [`solvers/_brick_common.py`](solvers/_brick_common.py) | Shared brick-bar model helpers (not run directly) |
+
+We use **one script per factory** under `solvers/` so each backend stays easy to find,
+copy, and run. The benchmark scripts stay separate for timing sweeps.
+
+## Quick start
+
+Clone the repo and follow [Full setup](../docs/installation.md#full-setup) (environment →
+install → [verify](../docs/installation.md#verify)). Then from `examples/`:
+
+```bash
+# Benchmark comparisons (mesh sweeps)
+python brick_bar.py
+python brick_bar_eigen.py
+
+# Finer meshes, more equations (much slower)
+python brick_bar.py --large-test
+python brick_bar_eigen.py --large-test
+
+# Single-solver smoke tests
+python solvers/scipy_spsolve.py
+python solvers/scipy_eigsh.py
+```
+
+Optional backends (UMFPACK, nvMath, CuPy): see the
+[installation guide](../docs/installation.md).
+
+## Solver catalog (`solvers/`)
+
+Each script builds a small 3-D brick bar, runs one analysis, and prints **Passed!** /
+**Failed!**. All use `solver.to_openseespy()` with `ops.system("PythonSparse", ...)`.
+
+Eigen scripts and `brick_bar_eigen` use **two-tier verification**: compare PythonSparse to
+OpenSees **`genBandArpack`** first; if results disagree, fall back to **`fullGenLapack`**
+(dense tiebreaker). The benchmark sweep uses only recommended eigen solvers. Experimental
+`lobpcg` scripts use a larger mesh, share settings in `_lobpcg_example.py`, and verify
+against the matching backend's `eigsh` (not native OpenSees eigen solvers). They are
+**manual-only** (not in pytest smoke tests).
+Use the default mesh sweep for CI; add `--large-test` only when you want heavier runs.
+
+### SciPy (`openseespy_solvers.scipy`)
+
+| Script | Factory |
+|--------|---------|
+| [`scipy_spsolve.py`](solvers/scipy_spsolve.py) | `spsolve()` |
+| [`scipy_umfpack.py`](solvers/scipy_umfpack.py) | `umfpack()` — needs `[umfpack]` |
+| [`hybrid_spsolve.py`](solvers/hybrid_spsolve.py) | `hybrid(spsolve(), ...)` |
+| [`scipy_cg.py`](solvers/scipy_cg.py) | `cg()` |
+| [`scipy_cg_jacobi.py`](solvers/scipy_cg_jacobi.py) | `cg(M=precond.jacobi)` |
+| [`scipy_gmres.py`](solvers/scipy_gmres.py) | `gmres()` |
+| [`scipy_gmres_ilu.py`](solvers/scipy_gmres_ilu.py) | `gmres(M=precond.ilu)` |
+| [`scipy_eigsh.py`](solvers/scipy_eigsh.py) | `eigsh()` |
+| [`scipy_lobpcg.py`](solvers/scipy_lobpcg.py) | `lobpcg()` |
+
+Preconditioner factories live in `openseespy_solvers.scipy.precond`: **`jacobi`**, **`ilu`**,
+**`direct`** (used via `M=` on `cg` / `gmres` / `lobpcg`, as in the scripts above).
+
+### CuPy (`openseespy_solvers.cupy`)
+
+| Script | Factory |
+|--------|---------|
+| [`cupy_spsolve.py`](solvers/cupy_spsolve.py) | `spsolve()` |
+| [`cupy_cg.py`](solvers/cupy_cg.py) | `cg()` |
+| [`cupy_cg_jacobi.py`](solvers/cupy_cg_jacobi.py) | `cg(M=precond.jacobi)` |
+| [`cupy_gmres.py`](solvers/cupy_gmres.py) | `gmres()` |
+| [`cupy_gmres_ilu.py`](solvers/cupy_gmres_ilu.py) | `gmres(M=precond.ilu)` |
+| [`cupy_eigsh.py`](solvers/cupy_eigsh.py) | `eigsh` (default `mass_mode="general"`) |
+| [`cupy_lobpcg.py`](solvers/cupy_lobpcg.py) | `lobpcg()` |
+
+`openseespy_solvers.cupy.precond` exports **`jacobi`**, **`ilu`**, and **`direct`**.
+[`eigsh`](solvers/cupy_eigsh.py) uses shift-invert (`diagonal` / `lumped` on GPU;
+`general` with full mass).
+
+### nvMath (`openseespy_solvers.nvmath`) — GPU
+
+| Script | Factory |
+|--------|---------|
+| [`nvmath_direct_solver.py`](solvers/nvmath_direct_solver.py) | `direct_solver()` — needs `cupy-cuda12x`/`cupy-cuda13x` and matching `nvmath-python[cu12]`/`[cu13]` |
+
+## Benchmark scripts
+
+Change the mesh sweep in one line (bigger number = finer mesh):
+
+```python
+MESH_FACTORS = [1.5, 2.0, 2.5, 3.0]
+```
+
+Benchmarks compare [recommended solvers](../docs/recommended-solvers.md) to native
+OpenSees backends. **Static** (`brick_bar.py`): `scipy.spsolve`, optional
+`scipy.umfpack`, optional `nvmath.direct_solver` (GPU), vs `BandGeneral`,
+`SuperLU`, `UmfPack`. **Eigen** (`brick_bar_eigen.py`): `scipy.eigsh`, optional
+`cupy.eigsh`, vs `genBandArpack` (`fullGenLapack` tiebreaker on mismatch). Other
+factories remain in `solvers/` as smoke tests only.
+
+String-based solver loop (no lambdas):
+
+```python
+from openseespy_solvers.scipy import spsolve
+
+solver = spsolve()
+NATIVE_SOLVERS = brick.NATIVE_STATIC_SOLVERS  # BandGeneral, SuperLU, UmfPack
+
+for factor in MESH_FACTORS:
+    nx, ny, nz = mesh_counts(factor)
+    for name in solvers:
+        build_model(nx, ny, nz)
+        apply_load()
+        if name == "PythonSparse":
+            ops.system("PythonSparse", solver.to_openseespy())
+        else:
+            ops.system(name)
+        # numberer / constraints / integrator / test / algorithm / analysis ...
+        status = ops.analyze(NUM_STEPS)
+```
+
+## See also
+
+- OpenSees [`benchmark_python_sparse.py`](https://github.com/OpenSees/OpenSees/blob/master/EXAMPLES/SolverBenchmark/benchmark_python_sparse.py)
+- OpenSees [`benchmark_python_sparse_eigen.py`](https://github.com/OpenSees/OpenSees/blob/master/EXAMPLES/SolverBenchmark/benchmark_python_sparse_eigen.py)
+- Docs: [Read the Docs](https://openseespy-solvers.readthedocs.io/en/latest/examples/)

openseespy_solvers-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openseespy-solvers"
+version = "0.1.0"
+description = "Ready-to-use, SciPy-style PythonSparse solvers for OpenSeesPy"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [{ name = "openseespy-solvers contributors" }]
+keywords = ["opensees", "openseespy", "solver", "scipy", "sparse", "eigen", "finite-element"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    # SciPy 1.12+ exposes rtol/atol on sparse iterative solvers (used by cg/gmres).
+    "numpy>=1.26",
+    "scipy>=1.12",
+]
+
+[project.optional-dependencies]
+opensees = ["openseespy"]
+# One extra per optional backend (matches openseespy_solvers.cupy, …).
+# Install the CuPy wheel matching your CUDA toolkit, e.g. cupy-cuda12x (see docs).
+# nvMath: GPU-only — install nvmath-python[cu12] or [cu13] manually (see docs).
+cupy = ["cupy>=13.0"]
+# 64-bit UMFPACK direct solver (CPU) for openseespy_solvers.scipy.umfpack.
+# On Windows, prefer: conda install -c conda-forge scikit-umfpack (PyPI is sdist-only).
+umfpack = ["scikit-umfpack>=0.3.3"]
+dev = [
+    "pytest>=8",
+    "ruff>=0.4",
+    "build",
+]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/gaaraujo/openseespy-solvers"
+Documentation = "https://openseespy-solvers.readthedocs.io/"
+Issues = "https://github.com/gaaraujo/openseespy-solvers/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openseespy_solvers"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/openseespy_solvers", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/openseespy_solvers/_base.py" = ["N802", "N803", "N806"]
+"src/openseespy_solvers/scipy/_base.py" = ["N802", "N803", "N806"]
+"src/openseespy_solvers/cupy/_base.py" = ["N802", "N803", "N806"]
+"src/openseespy_solvers/nvmath/_base.py" = ["N802", "N803", "N806"]
+"src/openseespy_solvers/nvmath/__init__.py" = ["F401", "N802", "N803", "N806"]
+"src/openseespy_solvers/scipy/precond.py" = ["N803"]
+"src/openseespy_solvers/scipy/__init__.py" = ["F401", "N802", "N803", "N806"]
+"src/openseespy_solvers/cupy/__init__.py" = ["F401", "N802", "N803", "N806"]
+"src/openseespy_solvers/__init__.py" = ["F401"]
+"tests/**" = ["N803", "N806", "I001"]
+"examples/**" = ["I001", "E402"]
+"src/openseespy_solvers/_hybrid.py" = ["N803", "N806"]
+"src/openseespy_solvers/cupy/precond.py" = ["N803", "N806"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

openseespy_solvers-0.1.0/src/openseespy_solvers/__init__.py

@@ -0,0 +1,41 @@
+"""Ready-to-use PythonSparse solvers for OpenSeesPy."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+from openseespy_solvers.exceptions import (
+    BackendNotAvailableError,
+    InvalidOpenSeesDataError,
+    OpenSeesSolverError,
+    SolverConvergenceError,
+    UnsupportedComputeDtypeError,
+    UnsupportedStorageSchemeError,
+)
+from openseespy_solvers.hybrid import hybrid
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BackendNotAvailableError",
+    "InvalidOpenSeesDataError",
+    "OpenSeesSolverError",
+    "SolverConvergenceError",
+    "UnsupportedComputeDtypeError",
+    "UnsupportedStorageSchemeError",
+    "__version__",
+    "cupy",
+    "hybrid",
+    "scipy",
+]
+
+if TYPE_CHECKING:
+    from openseespy_solvers import cupy as cupy
+    from openseespy_solvers import scipy as scipy
+
+
+def __getattr__(name: str):
+    if name in {"scipy", "cupy"}:
+        return import_module(f"openseespy_solvers.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")