How nixtla/neuralforecast works
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