# cantaro86/financial-models-numerical-methods architecture

> Architecture diagram of the GitHub repository cantaro86/financial-models-numerical-methods, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cantaro86/financial-models-numerical-methods
- Repository: https://github.com/cantaro86/financial-models-numerical-methods

## Overview

##### Main Components
- Interactive Jupyter Notebooks: These are the “front-end” for educational exploration. Each notebook (e.g., “1.1 Black-Scholes numerical methods.ipynb”, “2.1 Black-Scholes PDE and sparse matrices.ipynb”, etc.) is almost self-contained and illustrates different financial models and numerical methods.
- Core Computational Library (FMNM): Located in the src/FMNM directory, this Python package (with files such as BS_pricer.py, Heston_pricer.py, Kalman_filter.py, and more) contains implementations of various pricing algorithms, simulation methods, and numerical solvers.
- C-based Computational Engine: Under src/C, there are C source files (e.g., PDE_solver.c, SOR.c) along with a Makefile. These files are used for performance optimization tasks and are integrated via Cython (as seen in src/FMNM/cython).
- Data Layer: The data directory holds example CSV files (historical_data.csv, options data, stocks_data.csv) which provide input data for simulations and learning exercises.
- Configuration and Environment: Files like environment.yml, requirements.txt, setup.py, and pyproject.toml indicate dependency management and build scripts. They are essential for reproducing the environment in which the notebooks and libraries operate.
- Deployment/Containerization: The Dockerfile and docker-compose.yml denote container support to run JupyterLab, making the project portable and reproducible.

##### Relationships and Interactions
- The Interactive Notebooks drive the user experience: when executed, they import modules from the FMNM package.
- The FMNM package, in turn, makes calls into the C code (or its Cython wrappers) for computationally intensive routines. This separation ensures that the interactive layer remains responsive while leveraging optimized code.
- External Data is loaded into notebooks and the FMNM modules for simulations and model calibration.
- Dependency and environment management files ensure that the correct versions of libraries and compilers are available for both Python and C components.
- Deployment through Docker encapsulates the entire runtime environment, enabling consistent use across systems.

##### Architectural and Design Patterns
- Separation of Concerns: The project divides responsibilities among interactive notebooks (user interface and demonstration), core numerical methods (the FMNM library), and optimized lower-level computational routines (the C code). This modular approach supports maintainability and potential future extensions.
- Layered Architecture: At the top is the user’s Jupyter notebook interface. Below this lies the Python business logic (FMNM) that abstracts details about different pricing models; underneath that is the performance layer written in C/Cython.
- Use of Containers: Docker files and docker-compose facilitate deployment and reproduce the exact environment needed, including all dependencies.

##### Technologies, Frameworks, and Libraries
- Jupyter Notebook/Lab for interactive exploration.
- Python and associated libraries (likely numpy, scipy, pandas, etc.) for numerical computations.
- C and Cython for performance-critical sections.
- Docker (Dockerfile and docker-compose.yml) for containerization.
- Conda and pip are used for environment dependency management (as evidenced by environment.yml and requirements.txt).

##### Elements
- Clear labels for each component, e.g.:
– “Jupyter Notebooks” (with examples like 1.1, 2.1, etc. noted as sample topics)
– “FMNM Python Package” (listing major modules such as pricing models, Kalman filter, Fourier inversion, etc.)
– “C/Cython Performance Layer” (including components like SOR solver, PDE solver, etc.)
– “Data Sources” (CSV files and any other input data)
– “Environment & Deployment” (Docker, conda/venv setups)
– From Data Sources to Notebooks
– From Notebooks to FMNM library functions
– From FMNM to optimized C routines (where applicable)
– Rectangles for software components/modules.

- Below that, layer the FMNM library as the core processing engine.
- Underneath, put the C/Cython optimization layer to indicate back-end computational resources.
- On one side, position the “Data” component that feeds into these layers.
- On another side, annotate the environment and containerization stack (Docker, conda/pip) indicating how these components are built and deployed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    Data["Data Sources (CSV files)"]:::data

    %% Interactive Layer: Jupyter Notebooks
    subgraph "Interactive Layer"
        NB1["1.1 Black-Scholes numerical methods.ipynb"]:::interactive
        NB2["2.1 Black-Scholes PDE and sparse matrices.ipynb"]:::interactive
    end

    %% Core Processing: FMNM Library
    subgraph "Core Processing"
        FMNM["FMNM Python Package"]:::core
    end

    %% Performance Layer: C and Cython components
    subgraph "Performance Layer"
        C_Code["C Engine (src/C)"]:::performance
        Cython["Cython Wrappers (src/FMNM/cython)"]:::performance
    end

    %% Deployment & Environment: Config files and Containerization
    subgraph "Deployment & Environment"
        Config["Config & Environment Files"]:::config
        Dockerfile["Dockerfile"]:::deployment
        DockerCompose["docker-compose.yml"]:::deployment
    end

    %% Relationships
    Data -->|"input"| NB1
    Data -->|"input"| NB2

    NB1 -->|"imports"| FMNM
    NB2 -->|"imports"| FMNM

    FMNM -->|"calls"| C_Code
    FMNM -->|"calls"| Cython

    Config -->|"configures"| NB1
    Config -->|"configures"| NB2
    Config -->|"configures"| FMNM

    Dockerfile -->|"containerizes"| Config
    DockerCompose -->|"orchestrates"| Config

    %% Click Events
    click NB1 "https://github.com/cantaro86/financial-models-numerical-methods/blob/master/1.1 Black-Scholes numerical methods.ipynb"
    click NB2 "https://github.com/cantaro86/financial-models-numerical-methods/blob/master/2.1 Black-Scholes PDE and sparse matrices.ipynb"
    click FMNM "https://github.com/cantaro86/financial-models-numerical-methods/tree/master/src/FMNM"
    click C_Code "https://github.com/cantaro86/financial-models-numerical-methods/tree/master/src/C"
    click Cython "https://github.com/cantaro86/financial-models-numerical-methods/tree/master/src/FMNM/cython"
    click Data "https://github.com/cantaro86/financial-models-numerical-methods/tree/master/data"
    click Config "https://github.com/cantaro86/financial-models-numerical-methods/blob/master/environment.yml"
    click Dockerfile "https://github.com/cantaro86/financial-models-numerical-methods/tree/master/Dockerfile"
    click DockerCompose "https://github.com/cantaro86/financial-models-numerical-methods/blob/master/docker-compose.yml"

    %% Styles
    classDef interactive fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef performance fill:#ffa500,stroke:#333,stroke-width:2px;
    classDef data fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef config fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef deployment fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
