fips 0.1.0b3__tar.gz

fips-0.1.0b3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 James Mineau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fips-0.1.0b3/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: fips
+Version: 0.1.0b3
+Summary: Flexible Inverse Problem Solver (FIPS)
+Author-email: James Mineau <jameskmineau@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jmineau/fips
+Project-URL: Documentation, https://jmineau.github.io/fips/
+Project-URL: Repository, https://github.com/jmineau/fips
+Project-URL: Issues, https://github.com/jmineau/fips/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: joblib>=1.4.0
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scipy>=1.8.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: xarray>=2022.3.0
+Provides-Extra: flux
+Requires-Dist: cartopy>=0.24.0; extra == "flux"
+Requires-Dist: h5py>=3.11.0; extra == "flux"
+Requires-Dist: matplotlib>=3.6.0; extra == "flux"
+Requires-Dist: pystilt>=0.1.0a1; extra == "flux"
+Dynamic: license-file
+
+<div align=center>
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jmineau/fips/main/docs/_static/logo_dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jmineau/fips/main/docs/_static/logo.png">
+    <img alt="fips logo" src="https://raw.githubusercontent.com/jmineau/fips/main/docs/_static/logo.png" width="600">
+</picture>
+</div>
+
+[![Tests](https://github.com/jmineau/fips/actions/workflows/tests.yml/badge.svg)](https://github.com/jmineau/fips/actions/workflows/tests.yml)
+[![Documentation](https://github.com/jmineau/fips/actions/workflows/docs.yml/badge.svg)](https://github.com/jmineau/fips/actions/workflows/docs.yml)
+[![Code Quality](https://github.com/jmineau/fips/actions/workflows/quality.yml/badge.svg)](https://github.com/jmineau/fips/actions/workflows/quality.yml)
+[![codecov](https://codecov.io/gh/jmineau/fips/branch/main/graph/badge.svg)](https://codecov.io/gh/jmineau/fips)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Pyright](https://img.shields.io/badge/pyright-checked-brightgreen.svg)](https://github.com/microsoft/pyright)
+
+> **⚠️ Beta Release**: FIPS is currently in beta (v0.1.0b1). The core API is stable and ready for testing, but may evolve based on user feedback. Please [report any issues or edge cases](https://github.com/jmineau/fips/issues) you encounter.
+
+## Bridging Physics and Data
+Inverse problems in geophysics and atmospheric science are incredibly complex, often involving massive state spaces, deeply heterogeneous observational networks, and explicit matrix-algebra requirements. While many general-purpose optimization tools exist, they often force researchers to strip away critical spatiotemporal metadata or translate pre-computed physical models into rigid, abstract array structures.
+
+**FIPS (Flexible Inverse Problem Solver)** is built from the ground up to solve linear, matrix-based inverse problems without losing the context of your data. It provides the structural flexibility to handle messy, real-world realities seamlessly:
+
+- **Native N-Dimensional Alignment**: FIPS natively utilizes `pandas.MultiIndex` to smoothly align heterogeneous datasets across any dimension. Whether you are mixing temporal, spatial, spectral, or sensor-specific data, your coordinates are never dropped or misaligned.
+
+- **Modular Block Architecture**: Avoid wrangling monolithic arrays. Construct massive, multi-source state spaces and observation networks piece-by-piece using specialized `Block` and `MatrixBlock` objects.
+
+- **Speak Your Domain's Language**: Built explicitly around the standard `y = Hx + error` paradigm. Directly plug in your pre-computed forward operators ($H$), prior covariances ($S_0$), and model-data mismatches ($S_z$).
+
+- **Analytical Speed & Sparse Support**: FIPS is built for scale. By leveraging optimized sparse data structures and direct linear algebra rather than expensive sampling algorithms, it computes exact analytical Maximum A Posteriori (MAP) estimates for massive state spaces in seconds.
+
+## Installation
+
+### From GitHub
+```bash
+pip install git+https://github.com/jmineau/fips
+```
+
+### From Source
+
+```bash
+git clone https://github.com/jmineau/fips.git
+cd fips
+pip install -e .
+```
+
+## Usage
+
+### Single-block — one observation source
+
+```python
+import numpy as np
+import pandas as pd
+from fips import Block, CovarianceMatrix
+from fips.problems.flux import FluxProblem
+
+# State: gridded prior fluxes (time × lat × lon)
+flux_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=3, freq="MS"), [37.0, 38.0], [-112.0, -111.0]],
+    names=["time", "lat", "lon"],
+)
+prior = pd.Series(np.ones(12) * 1.5, index=flux_idx, name="flux")
+
+# Observations: tower concentration measurements
+obs_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=8, freq="2W"), ["UOU"]],
+    names=["time", "site"],
+)
+obs = pd.Series(np.ones(8) * 400.0, index=obs_idx, name="concentration")
+
+# Forward operator (Jacobian), flux error covariance, obs error covariance
+H   = pd.DataFrame(np.random.rand(8, 12), index=obs_idx,  columns=flux_idx)
+S_0 = pd.DataFrame(np.eye(12) * 0.5,  index=flux_idx, columns=flux_idx)
+S_z = pd.DataFrame(np.eye(8)  * 0.1,  index=obs_idx,  columns=obs_idx)
+
+problem = FluxProblem(
+    obs=obs, prior=prior,
+    forward_operator=H, prior_error=S_0, modeldata_mismatch=S_z,
+).solve()
+
+print(problem.posterior_fluxes)        # posterior pd.Series indexed by (time, lat, lon)
+print(problem.estimator.reduced_chi2)  # reduced chi-squared statistic
+```
+
+### Multi-block — combined station + satellite observations
+
+```python
+import numpy as np
+import pandas as pd
+from fips import Block, Vector, Matrix, MatrixBlock, CovarianceMatrix, InverseProblem
+
+# State: same gridded prior fluxes (from above)
+N_f = 12
+
+# Obs block 1: ground station in-situ concentrations
+station_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=8, freq="2W"), ["UOU"]],
+    names=["time", "site"],
+)
+station_obs = Block(pd.Series(np.ones(8) * 400.0,
+                              index=station_idx, name="station"))
+
+# Obs block 2: satellite column-average concentrations
+satellite_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=3, freq="MS"), [37.5], [-111.5]],
+    names=["time", "lat", "lon"],
+)
+satellite_obs = Block(pd.Series(np.ones(3) * 0.00400,
+                                index=satellite_idx, name="satellite"))
+
+# Combine obs blocks into a list
+obs_blks = [station_obs, satellite_obs]
+
+# Jacobian: one MatrixBlock per obs type, both mapping to the "flux" state block
+H_blks = [
+    MatrixBlock(
+        pd.DataFrame(np.random.rand(8, N_f),
+        index=station_idx, columns=flux_idx),
+        row_block="station", col_block="flux",
+    ),
+    MatrixBlock(
+        pd.DataFrame(np.random.rand(3, N_f),
+        index=satellite_idx, columns=flux_idx),
+        row_block="satellite", col_block="flux",
+    ),]
+
+# Prior error covariance: only flux errors, no cross-block covariances
+S_0 = CovarianceMatrix(np.eye(N_f) * 0.5, index=flux_idx, columns=flux_idx)
+
+# Model-data mismatch covariance: block-diagonal with separate error levels for stations vs. satellite
+S_z_blks = [
+    CovarianceMatrix(np.eye(8) * 0.1, index=station_idx, columns=station_idx),
+    CovarianceMatrix(np.eye(3) * 0.2, index=satellite_idx, columns=satellite_idx),
+]
+
+# Pass blocks to the InverseProblem and solve
+problem = InverseProblem(
+    obs=obs_blks, prior=prior,
+    forward_operator=H_blks, prior_error=S_0, modeldata_mismatch=S_z_blks,
+).solve()
+
+print(problem.posterior['flux'])       # posterior pd.Series indexed by (time, lat, lon)
+print(problem.estimator.reduced_chi2)  # reduced chi-squared statistic
+```
+
+## Documentation
+
+Full documentation is available at [https://jmineau.github.io/fips/](https://jmineau.github.io/fips/)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

fips-0.1.0b3/README.md

@@ -0,0 +1,152 @@
+<div align=center>
+<picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jmineau/fips/main/docs/_static/logo_dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jmineau/fips/main/docs/_static/logo.png">
+    <img alt="fips logo" src="https://raw.githubusercontent.com/jmineau/fips/main/docs/_static/logo.png" width="600">
+</picture>
+</div>
+
+[![Tests](https://github.com/jmineau/fips/actions/workflows/tests.yml/badge.svg)](https://github.com/jmineau/fips/actions/workflows/tests.yml)
+[![Documentation](https://github.com/jmineau/fips/actions/workflows/docs.yml/badge.svg)](https://github.com/jmineau/fips/actions/workflows/docs.yml)
+[![Code Quality](https://github.com/jmineau/fips/actions/workflows/quality.yml/badge.svg)](https://github.com/jmineau/fips/actions/workflows/quality.yml)
+[![codecov](https://codecov.io/gh/jmineau/fips/branch/main/graph/badge.svg)](https://codecov.io/gh/jmineau/fips)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Pyright](https://img.shields.io/badge/pyright-checked-brightgreen.svg)](https://github.com/microsoft/pyright)
+
+> **⚠️ Beta Release**: FIPS is currently in beta (v0.1.0b1). The core API is stable and ready for testing, but may evolve based on user feedback. Please [report any issues or edge cases](https://github.com/jmineau/fips/issues) you encounter.
+
+## Bridging Physics and Data
+Inverse problems in geophysics and atmospheric science are incredibly complex, often involving massive state spaces, deeply heterogeneous observational networks, and explicit matrix-algebra requirements. While many general-purpose optimization tools exist, they often force researchers to strip away critical spatiotemporal metadata or translate pre-computed physical models into rigid, abstract array structures.
+
+**FIPS (Flexible Inverse Problem Solver)** is built from the ground up to solve linear, matrix-based inverse problems without losing the context of your data. It provides the structural flexibility to handle messy, real-world realities seamlessly:
+
+- **Native N-Dimensional Alignment**: FIPS natively utilizes `pandas.MultiIndex` to smoothly align heterogeneous datasets across any dimension. Whether you are mixing temporal, spatial, spectral, or sensor-specific data, your coordinates are never dropped or misaligned.
+
+- **Modular Block Architecture**: Avoid wrangling monolithic arrays. Construct massive, multi-source state spaces and observation networks piece-by-piece using specialized `Block` and `MatrixBlock` objects.
+
+- **Speak Your Domain's Language**: Built explicitly around the standard `y = Hx + error` paradigm. Directly plug in your pre-computed forward operators ($H$), prior covariances ($S_0$), and model-data mismatches ($S_z$).
+
+- **Analytical Speed & Sparse Support**: FIPS is built for scale. By leveraging optimized sparse data structures and direct linear algebra rather than expensive sampling algorithms, it computes exact analytical Maximum A Posteriori (MAP) estimates for massive state spaces in seconds.
+
+## Installation
+
+### From GitHub
+```bash
+pip install git+https://github.com/jmineau/fips
+```
+
+### From Source
+
+```bash
+git clone https://github.com/jmineau/fips.git
+cd fips
+pip install -e .
+```
+
+## Usage
+
+### Single-block — one observation source
+
+```python
+import numpy as np
+import pandas as pd
+from fips import Block, CovarianceMatrix
+from fips.problems.flux import FluxProblem
+
+# State: gridded prior fluxes (time × lat × lon)
+flux_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=3, freq="MS"), [37.0, 38.0], [-112.0, -111.0]],
+    names=["time", "lat", "lon"],
+)
+prior = pd.Series(np.ones(12) * 1.5, index=flux_idx, name="flux")
+
+# Observations: tower concentration measurements
+obs_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=8, freq="2W"), ["UOU"]],
+    names=["time", "site"],
+)
+obs = pd.Series(np.ones(8) * 400.0, index=obs_idx, name="concentration")
+
+# Forward operator (Jacobian), flux error covariance, obs error covariance
+H   = pd.DataFrame(np.random.rand(8, 12), index=obs_idx,  columns=flux_idx)
+S_0 = pd.DataFrame(np.eye(12) * 0.5,  index=flux_idx, columns=flux_idx)
+S_z = pd.DataFrame(np.eye(8)  * 0.1,  index=obs_idx,  columns=obs_idx)
+
+problem = FluxProblem(
+    obs=obs, prior=prior,
+    forward_operator=H, prior_error=S_0, modeldata_mismatch=S_z,
+).solve()
+
+print(problem.posterior_fluxes)        # posterior pd.Series indexed by (time, lat, lon)
+print(problem.estimator.reduced_chi2)  # reduced chi-squared statistic
+```
+
+### Multi-block — combined station + satellite observations
+
+```python
+import numpy as np
+import pandas as pd
+from fips import Block, Vector, Matrix, MatrixBlock, CovarianceMatrix, InverseProblem
+
+# State: same gridded prior fluxes (from above)
+N_f = 12
+
+# Obs block 1: ground station in-situ concentrations
+station_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=8, freq="2W"), ["UOU"]],
+    names=["time", "site"],
+)
+station_obs = Block(pd.Series(np.ones(8) * 400.0,
+                              index=station_idx, name="station"))
+
+# Obs block 2: satellite column-average concentrations
+satellite_idx = pd.MultiIndex.from_product(
+    [pd.date_range("2023-01", periods=3, freq="MS"), [37.5], [-111.5]],
+    names=["time", "lat", "lon"],
+)
+satellite_obs = Block(pd.Series(np.ones(3) * 0.00400,
+                                index=satellite_idx, name="satellite"))
+
+# Combine obs blocks into a list
+obs_blks = [station_obs, satellite_obs]
+
+# Jacobian: one MatrixBlock per obs type, both mapping to the "flux" state block
+H_blks = [
+    MatrixBlock(
+        pd.DataFrame(np.random.rand(8, N_f),
+        index=station_idx, columns=flux_idx),
+        row_block="station", col_block="flux",
+    ),
+    MatrixBlock(
+        pd.DataFrame(np.random.rand(3, N_f),
+        index=satellite_idx, columns=flux_idx),
+        row_block="satellite", col_block="flux",
+    ),]
+
+# Prior error covariance: only flux errors, no cross-block covariances
+S_0 = CovarianceMatrix(np.eye(N_f) * 0.5, index=flux_idx, columns=flux_idx)
+
+# Model-data mismatch covariance: block-diagonal with separate error levels for stations vs. satellite
+S_z_blks = [
+    CovarianceMatrix(np.eye(8) * 0.1, index=station_idx, columns=station_idx),
+    CovarianceMatrix(np.eye(3) * 0.2, index=satellite_idx, columns=satellite_idx),
+]
+
+# Pass blocks to the InverseProblem and solve
+problem = InverseProblem(
+    obs=obs_blks, prior=prior,
+    forward_operator=H_blks, prior_error=S_0, modeldata_mismatch=S_z_blks,
+).solve()
+
+print(problem.posterior['flux'])       # posterior pd.Series indexed by (time, lat, lon)
+print(problem.estimator.reduced_chi2)  # reduced chi-squared statistic
+```
+
+## Documentation
+
+Full documentation is available at [https://jmineau.github.io/fips/](https://jmineau.github.io/fips/)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

fips-0.1.0b3/pyproject.toml

@@ -0,0 +1,130 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fips"
+version = "0.1.0b3"
+description = "Flexible Inverse Problem Solver (FIPS)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "James Mineau", email = "jameskmineau@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "joblib>=1.4.0",
+    "numpy>=1.22.0",
+    "pandas>=2.0.0",  # need pandas 2.0 for upgraded Index object
+    "scipy>=1.8.0",
+    "typing-extensions>=4.0.0",
+    "xarray>=2022.3.0",
+]
+
+[project.optional-dependencies]
+flux = [
+    "cartopy>=0.24.0",  # numpy 2.0 support
+    "h5py>=3.11.0",  # numpy 2.0 support
+    "matplotlib>=3.6.0",
+    "pystilt>=0.1.0a1",
+]
+
+[dependency-groups]
+dev = [
+    "fips[flux]",
+    "docstr-coverage>=2.0.0",
+    "ipykernel>=7.2.0",
+    "myst-parser>=2.0.0",
+    "nbsphinx>=0.9.0",
+    "pre-commit>=3.0.0",
+    "pydata-sphinx-theme>=0.14.0",
+    "pyright[nodejs]>=1.1.0",
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "sphinx>=7.0.0",
+    "sphinx-autodoc-typehints>=1.24.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jmineau/fips"
+Documentation = "https://jmineau.github.io/fips/"
+Repository = "https://github.com/jmineau/fips"
+Issues = "https://github.com/jmineau/fips/issues"
+
+[tool.coverage.run]
+source = ["src/fips"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.coverage.report]
+# Regexes for lines to exclude from consideration
+exclude_also = [
+    # Don't complain about missing debug-only code:
+    "def __repr__",
+    "if self\\.debug",
+
+    # Don't complain if tests don't hit defensive assertion code:
+    "raise AssertionError",
+    "raise NotImplementedError",
+
+    # Don't complain if non-runnable code isn't run:
+    "if 0:",
+    "if __name__ == .__main__.:",
+
+    # Don't complain about abstract methods, they aren't run:
+    "@(abc\\.)?abstractmethod",
+    ]
+
+[tool.pyright]
+include = ["src"]
+exclude = ["**/__pycache__", "**/.venv"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore:numpy.core.multiarray is deprecated:DeprecationWarning",
+]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle
+    "F",  # Pyflakes
+    "UP",  # pyupgrade
+    "B",  # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "I",  # isort
+    "D",  # pydocstyle
+]
+ignore = [
+    "E501",  # line too long, handled by formatter
+    "D200",  # One-line docstring should fit on one line with quotes
+    "D212",  # Multi-line docstring summary should start at the first line
+    "D400", # First line should end with a period, question mark, or exclamation point
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["fips"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"fips" = ["py.typed"]

fips-0.1.0b3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fips-0.1.0b3/src/fips/__init__.py

@@ -0,0 +1,35 @@
+"""
+Flexible Inverse Problem Solver (FIPS).
+
+A Pythonic framework for solving linear inverse problems using Bayesian estimation.
+Provides data structures for state vectors, observations, forward operators, and
+covariance matrices; estimators for computing posteriors; and interfaces for
+serialization, visualization, and specialized applications like atmospheric
+flux inversion.
+"""
+
+import logging
+
+from .covariance import CovarianceMatrix
+from .estimators import Estimator, available_estimators
+from .matrix import Matrix, MatrixBlock
+from .operators import ForwardOperator, convolve
+from .pipeline import InversionPipeline
+from .problem import InverseProblem
+from .vector import Block, Vector
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "Block",
+    "Vector",
+    "Matrix",
+    "MatrixBlock",
+    "Estimator",
+    "available_estimators",
+    "ForwardOperator",
+    "CovarianceMatrix",
+    "InversionPipeline",
+    "InverseProblem",
+    "convolve",
+]