# nixtla/neuralforecast architecture

> Architecture diagram of the GitHub repository nixtla/neuralforecast, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nixtla/neuralforecast
- Repository: https://github.com/nixtla/neuralforecast

## Overview

##### Project type and purpose
- This is an open-source Python library (“NeuralForecast”) that provides a unified API for over 30 state-of-the-art neural time-series forecasting models.
- It is not a client/server application, but a modular library that users import into their code or notebooks, train models, and get forecasts.

##### File structure
- Top-level packaging & config:
- setup.py, pyproject.toml, settings.ini, environment-*.yml, MANIFEST.in
- CI/CD & GitHub workflows in .circleci/ and .github/
- Documentation scaffolding and notebooks under nbs/, and experiments/
- Core library code under neuralforecast/:
- neuralforecast/core.py and NeuralForecast API entrypoint
- neuralforecast/common/ (base classes, dataset & scaler utilities, model checks)
- neuralforecast/models/ (30+ model implementations)
- neuralforecast/losses/ (NumPy and PyTorch loss functions)
- neuralforecast/tsdataset.py (data handling)
- neuralforecast/utils.py (data loaders, sample data)
- Tests under test/
- Example-driven experiment scripts under experiments/ and action_files/

##### Insights from the README
- The “NeuralForecast” class is the single façade: user constructs it with a list of model instances, calls .fit() on a pandas DataFrame, then .predict().
- Models adhere to a common interface (inherited from common/_base_model.py) and are dynamically discovered via _modidx.py.
- Integrations / optional dependencies:
- PyTorch for model implementations
- NumPy for lighter-weight versions
- Ray or Optuna for hyperparameter tuning
- StatsForecast, MLForecast interfaces for interoperability

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User API Layer
    UserAPI["NeuralForecast\n(core.py)"]:::coreAPI
    click UserAPI "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/core.py"

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        TSDataset["TSDataset\n(tsdataset.py)"]:::data
        click TSDataset "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/tsdataset.py"
        Scalers["Scalers & Utils\n(_scalers.py)"]:::data
        click Scalers "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/common/_scalers.py"
        CommonUtils["Utilities\n(utils.py)"]:::data
        click CommonUtils "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/utils.py"
    end

    %% Model Registry & Loader
    ModelRegistry["Model Registry & Loader\n(_modidx.py)"]:::coreAPI
    click ModelRegistry "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/_modidx.py"

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        BaseModel["BaseModel & Engine\n(_base_model.py)"]:::coreAPI
        click BaseModel "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/common/_base_model.py"
        ModelChecks["Model Checks & Validation\n(_model_checks.py)"]:::coreAPI
        click ModelChecks "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/common/_model_checks.py"
        subgraph "Implementations" 
            direction TB
            NBeats["NBeats\n(nbeats.py)"]:::modelImpl
            click NBeats "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/models/nbeats.py"
            LSTM["LSTM\n(lstm.py)"]:::modelImpl
            click LSTM "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/models/lstm.py"
            Transformer["Transformer\n(tft.py)"]:::modelImpl
            click Transformer "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/models/transformer/tft.py"
            Others["Other Models\n(models/)"]:::modelImpl
        end
    end

    %% Loss Functions
    subgraph "Loss Functions"
        direction TB
        LossNumPy["NumPy Losses\n(numpy.py)"]:::data
        click LossNumPy "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/losses/numpy.py"
        LossTorch["PyTorch Losses\n(pytorch.py)"]:::data
        click LossTorch "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/losses/pytorch.py"
    end

    %% Auto-tuning
    subgraph "Auto-tuning"
        direction TB
        BaseAuto["Base Auto-tuning\n(_base_auto.py)"]:::coreAPI
        click BaseAuto "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/common/_base_auto.py"
        AutoAdapter["Optuna/Ray Adapter\n(auto.py)"]:::coreAPI
        click AutoAdapter "https://github.com/nixtla/neuralforecast/blob/main/neuralforecast/auto.py"
    end

    %% Experiments & Notebooks
    subgraph "Experiments & Docs"
        direction TB
        Experiments["Experiment Scripts\n(run_experiment.py)"]:::docs
        click Experiments "https://github.com/nixtla/neuralforecast/blob/main/experiments/kan_benchmark/run_experiment.py"
        Notebooks["Tutorial Notebooks\n(01_getting_started_complete.ipynb)"]:::docs
        click Notebooks "https://github.com/nixtla/neuralforecast/blob/main/nbs/docs/tutorials/01_getting_started_complete.ipynb"
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        CI["CI Workflows\n(ci.yaml)"]:::infra
        click CI "https://github.com/nixtla/neuralforecast/blob/main/.github/workflows/ci.yaml"
        Circle["CircleCI Config\n(config.yml)"]:::infra
        click Circle "https://github.com/nixtla/neuralforecast/blob/main/.circleci/config.yml"
        Packaging["Packaging & Config\n(setup.py,pyproject.toml,settings.ini)"]:::infra
        click Packaging "https://github.com/nixtla/neuralforecast/blob/main/setup.py"
        click Packaging "https://github.com/nixtla/neuralforecast/blob/main/pyproject.toml"
        click Packaging "https://github.com/nixtla/neuralforecast/blob/main/settings.ini"
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch"]:::external
        NumPy["NumPy"]:::external
        Pandas["Pandas"]:::external
        Ray["Ray"]:::external
        Optuna["Optuna"]:::external
    end

    %% Flow
    UserAPI -->|"fit(df)"| TSDataset
    UserAPI -->|"fit(df)"| Scalers
    TSDataset -->|data| BaseModel
    Scalers -->|scaled data| BaseModel
    BaseModel -->|loads| ModelRegistry
    ModelRegistry -->|instantiates| NBeats
    ModelRegistry -->|instantiates| LSTM
    ModelRegistry -->|instantiates| Transformer
    ModelRegistry -->|instantiates| Others
    NBeats -->|batch→loss| LossNumPy
    NBeats -->|batch→loss| LossTorch
    LSTM -->|batch→loss| LossTorch
    Transformer -->|batch→loss| LossTorch
    BaseModel -->|train loop| LossTorch
    BaseModel -->|validate| ModelChecks
    UserAPI -->|"predict()"| BaseModel
    UserAPI -->|"predict()"| ModelRegistry
    BaseModel -->|predictions| UserAPI

    BaseAuto -->|config| BaseModel
    AutoAdapter -->|tune| BaseModel
    BaseAuto -->|loop fits| AutoAdapter
    AutoAdapter -->|best config| UserAPI

    Experiments -->|import| UserAPI
    Notebooks -->|import| UserAPI

    Packaging -->|publishes| CI
    CI -->|runs tests| BaseModel
    CI -->|builds| Packaging
    Circle -->|runs| CI

    PyTorch -->|backend| LossTorch
    NumPy -->|backend| LossNumPy
    Pandas -->|used by| UserAPI
    Ray -->|used by| AutoAdapter
    Optuna -->|used by| AutoAdapter

    %% Styles
    classDef coreAPI fill:#d0e1f9,stroke:#1f77b4,color:#1f77b4;
    classDef data fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00;
    classDef modelImpl fill:#d4f4dd,stroke:#2ca02c,color:#2ca02c;
    classDef docs fill:#f9e5ff,stroke:#9467bd,color:#9467bd;
    classDef infra fill:#e0e0e0,stroke:#7f7f7f,color:#7f7f7f;
    classDef external fill:#e5e5ff,stroke:#9467bd,color:#9467bd;
```
