mean-field-tools 0.1.0__tar.gz

mean_field_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Felipe José Pinto Antunes
+
+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.

mean_field_tools-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: mean-field-tools
+Version: 0.1.0
+Summary: Tools for numerical simulations of mean field games
+License: MIT
+License-File: LICENSE
+Keywords: mean-field-games,mckean-vlasov,fbsde,deep-bsde,elicitability,stochastic-control
+Author: Felipe José Pinto Antunes
+Author-email: fjpantunes2@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: matplotlib (>=3.8.4,<4.0.0)
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: scipy (>=1.13.0,<2.0.0)
+Requires-Dist: torch (>=2.3.0,<3.0.0)
+Requires-Dist: tqdm (>=4.66.4,<5.0.0)
+Project-URL: Homepage, https://github.com/fjpAntunes/mean-field-tools
+Project-URL: Paper, https://arxiv.org/abs/2512.14967
+Project-URL: Repository, https://github.com/fjpAntunes/mean-field-tools
+Description-Content-Type: text/markdown
+
+# Mean Field Tools
+
+A Python library for numerically solving McKean-Vlasov forward-backward stochastic differential equations (MV-FBSDEs) under common noise using elicitability, deep learning and Picard iterations.
+
+It accompanies the paper [*Deep Learning and Elicitability for McKean-Vlasov FBSDEs With Common Noise*](https://arxiv.org/abs/2512.14967) — see [How to cite this work](#how-to-cite-this-work).
+
+## Features
+
+- Deep BSDE (Backward Stochastic Differential Equation) solvers
+- Forward-Backward SDE implementations with Picard iteration
+- Neural-network function approximators (including ResNet architectures)
+- Mean field flow measure approximations (with common-noise support)
+- Filtration tools for Brownian motion and stochastic state tracking
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/fjpAntunes/mean-field-tools.git
+cd mean-field-tools
+
+# Install with Poetry
+poetry install
+```
+
+## Usage
+
+See `mean_field_tools/deep_bsde/README.md` for a detailed overview of the components, and `mean_field_tools/deep_bsde/script/experiments/` for runnable examples (systemic risk, portfolio hedging, economic growth, and more).
+
+## Testing
+
+The project uses pytest for testing. Tests are organized into unit and integration tests within the `mean_field_tools/deep_bsde/test/` directory.
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test categories
+pytest mean_field_tools/deep_bsde/test/unit/
+pytest mean_field_tools/deep_bsde/test/integration/
+
+# Run a specific test file
+pytest mean_field_tools/deep_bsde/test/unit/test_function_approximator.py
+```
+
+## Structure
+
+- `mean_field_tools/deep_bsde/`: Core library — the Deep BSDE solver and its components
+  - `filtration.py`: Brownian motion generation and stochastic state tracking
+  - `forward_backward_sde.py`: Forward/Backward SDE classes and Picard iteration
+  - `function_approximator.py`: Neural-network approximators
+  - `measure_flow.py`: Mean field flow measure approximations
+  - `artist.py`: Plotting and diagnostics
+  - `script/experiments/`: Example applications
+  - `test/`: Unit and integration tests
+
+## How to cite this work
+
+If you use this library in your research, please cite:
+
+> Felipe J. P. Antunes, Yuri F. Saporito, and Sebastian Jaimungal.
+> *Deep Learning and Elicitability for McKean-Vlasov FBSDEs With Common Noise*, 2026.
+> arXiv:[2512.14967](https://arxiv.org/abs/2512.14967).
+
+```bibtex
+@misc{antunes2026deeplearningelicitabilitymckeanvlasov,
+      title={Deep Learning and Elicitability for McKean-Vlasov FBSDEs With Common Noise},
+      author={Felipe J. P. Antunes and Yuri F. Saporito and Sebastian Jaimungal},
+      year={2026},
+      eprint={2512.14967},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2512.14967},
+}
+```
+
+## License
+
+MIT
+

mean_field_tools-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Mean Field Tools
+
+A Python library for numerically solving McKean-Vlasov forward-backward stochastic differential equations (MV-FBSDEs) under common noise using elicitability, deep learning and Picard iterations.
+
+It accompanies the paper [*Deep Learning and Elicitability for McKean-Vlasov FBSDEs With Common Noise*](https://arxiv.org/abs/2512.14967) — see [How to cite this work](#how-to-cite-this-work).
+
+## Features
+
+- Deep BSDE (Backward Stochastic Differential Equation) solvers
+- Forward-Backward SDE implementations with Picard iteration
+- Neural-network function approximators (including ResNet architectures)
+- Mean field flow measure approximations (with common-noise support)
+- Filtration tools for Brownian motion and stochastic state tracking
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/fjpAntunes/mean-field-tools.git
+cd mean-field-tools
+
+# Install with Poetry
+poetry install
+```
+
+## Usage
+
+See `mean_field_tools/deep_bsde/README.md` for a detailed overview of the components, and `mean_field_tools/deep_bsde/script/experiments/` for runnable examples (systemic risk, portfolio hedging, economic growth, and more).
+
+## Testing
+
+The project uses pytest for testing. Tests are organized into unit and integration tests within the `mean_field_tools/deep_bsde/test/` directory.
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test categories
+pytest mean_field_tools/deep_bsde/test/unit/
+pytest mean_field_tools/deep_bsde/test/integration/
+
+# Run a specific test file
+pytest mean_field_tools/deep_bsde/test/unit/test_function_approximator.py
+```
+
+## Structure
+
+- `mean_field_tools/deep_bsde/`: Core library — the Deep BSDE solver and its components
+  - `filtration.py`: Brownian motion generation and stochastic state tracking
+  - `forward_backward_sde.py`: Forward/Backward SDE classes and Picard iteration
+  - `function_approximator.py`: Neural-network approximators
+  - `measure_flow.py`: Mean field flow measure approximations
+  - `artist.py`: Plotting and diagnostics
+  - `script/experiments/`: Example applications
+  - `test/`: Unit and integration tests
+
+## How to cite this work
+
+If you use this library in your research, please cite:
+
+> Felipe J. P. Antunes, Yuri F. Saporito, and Sebastian Jaimungal.
+> *Deep Learning and Elicitability for McKean-Vlasov FBSDEs With Common Noise*, 2026.
+> arXiv:[2512.14967](https://arxiv.org/abs/2512.14967).
+
+```bibtex
+@misc{antunes2026deeplearningelicitabilitymckeanvlasov,
+      title={Deep Learning and Elicitability for McKean-Vlasov FBSDEs With Common Noise},
+      author={Felipe J. P. Antunes and Yuri F. Saporito and Sebastian Jaimungal},
+      year={2026},
+      eprint={2512.14967},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2512.14967},
+}
+```
+
+## License
+
+MIT

mean_field_tools-0.1.0/mean_field_tools/__init__.py

@@ -0,0 +1,10 @@
+"""Tools for numerical simulations of mean field games."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("mean-field-tools")
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

mean_field_tools-0.1.0/mean_field_tools/deep_bsde/README.md

@@ -0,0 +1,85 @@
+Mean Field Tools: Deep Backward Stochastic Differential Equation (BSDE) Solver
+Project Overview
+This project provides a sophisticated computational framework for solving forward-backward stochastic differential equations (FBSDEs) with advanced numerical methods, particularly focusing on mean-field interaction scenarios and systemic risk modeling.
+Key Components
+1. Filtration Module (filtration.py)
+
+Manages stochastic process state tracking
+Generates Brownian motion and increments
+Supports common noise filtration
+Tracks time-dependent system states
+
+2. Forward-Backward SDE Module (forward_backward_sde.py)
+
+Implements numerical solution strategies for SDEs
+Supports Forward and Backward SDE classes
+Uses Picard iterations for numerical convergence
+Handles complex stochastic process interactions
+
+3. Function Approximator (function_approximator.py)
+
+Neural network-based function approximation
+Implements stochastic gradient descent training
+Enables flexible function representation
+
+4. Measure Flow Module (measure_flow.py)
+
+Calculates conditional mean and flow of stochastic processes
+Supports common noise measure flow
+Parametrizes process mean fields
+
+5. Systemic Risk Example (systemic_risk_common_noise.py)
+
+Demonstrates practical application of the framework
+Models a specific systemic risk scenario with common noise
+Provides analytical and numerical solution comparisons
+
+Methodology
+
+Picard Iterations
+
+Iteratively refine forward and backward processes
+Uses neural network approximation
+Converges to solution through damped updates
+
+
+Common Noise Modeling
+
+Introduces correlated noise components
+Enables modeling of systemic interactions
+Separates common and idiosyncratic noise sources
+
+
+Stochastic Differential Equation Solving
+
+Numerical approximation of SDEs
+Supports complex drift and volatility functions
+Handles multi-dimensional processes
+
+
+
+Key Features
+
+Flexible stochastic process modeling
+Neural network-based function approximation
+Supports multiple noise generation strategies
+Comprehensive plotting and visualization tools
+
+Use Cases
+
+Financial risk modeling
+Systemic risk assessment
+Complex stochastic process simulation
+Machine learning-enhanced SDE solving
+
+Dependencies
+
+PyTorch
+NumPy
+Matplotlib
+tqdm
+
+Usage Example
+The systemic_risk_common_noise.py script provides a comprehensive example of setting up and solving a mean-field BSDE with common noise, demonstrating the framework's capabilities.
+Note
+This framework is particularly powerful for modeling complex stochastic systems with intricate interactions and mean-field effects.

mean_field_tools-0.1.0/mean_field_tools/deep_bsde/__init__.py

@@ -0,0 +1,61 @@
+"""Deep BSDE solvers for mean field problems.
+
+The names re-exported here are the supported public API. Anything reachable
+through a module path but absent from this list is an implementation detail and
+may change without a major version bump.
+"""
+
+from mean_field_tools.deep_bsde.artist import (
+    FunctionApproximatorArtist,
+    PicardIterationsArtist,
+)
+from mean_field_tools.deep_bsde.filtration import CommonNoiseFiltration, Filtration
+from mean_field_tools.deep_bsde.forward_backward_sde import (
+    AnalyticForwardSDE,
+    BackwardSDE,
+    CommonNoiseBackwardSDE,
+    ForwardBackwardSDE,
+    NumericalForwardSDE,
+)
+from mean_field_tools.deep_bsde.function_approximator import (
+    FunctionApproximator,
+    HybridApproximator,
+    PathDependentApproximator,
+)
+from mean_field_tools.deep_bsde.measure_flow import (
+    CommonNoiseMeasureFlow,
+    MeasureFlow,
+)
+from mean_field_tools.deep_bsde.utils import (
+    IDENTITY_TERMINAL,
+    L_2_norm,
+    L_inf_norm,
+    QUADRATIC_TERMINAL,
+)
+
+__all__ = [
+    # Filtration
+    "Filtration",
+    "CommonNoiseFiltration",
+    # Forward / backward SDEs
+    "NumericalForwardSDE",
+    "AnalyticForwardSDE",
+    "BackwardSDE",
+    "CommonNoiseBackwardSDE",
+    "ForwardBackwardSDE",
+    # Measure flow
+    "MeasureFlow",
+    "CommonNoiseMeasureFlow",
+    # Function approximators
+    "FunctionApproximator",
+    "PathDependentApproximator",
+    "HybridApproximator",
+    # Plotting and diagnostics
+    "FunctionApproximatorArtist",
+    "PicardIterationsArtist",
+    # Terminal conditions and norms
+    "IDENTITY_TERMINAL",
+    "QUADRATIC_TERMINAL",
+    "L_2_norm",
+    "L_inf_norm",
+]