<p align="center">
<img
src="https://raw.githubusercontent.com/earthai-tech/fusionlab-learn/main/docs/source/_static/fusionlab.svg"
alt="FusionLab Logo"
width="200"
>
</p>
-----------------------------------------------------
<h1 align="center">fusionlab-learn</h1>
<p align="center"><em>A Research-Oriented Library for Advanced Time Series Forecasting with Hybrid, Transformer, and Physics-Informed Models</em></p>
<p align="center">
<a href="https://pypi.org/project/fusionlab-learn/"><img src="https://img.shields.io/pypi/v/fusionlab-learn" alt="PyPI Version"></a>
<a href="https://fusion-lab.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/fusion-lab/badge/?version=latest" alt="Documentation Status"></a>
<a href="https://github.com/earthai-tech/fusionlab-learn/actions"><img src="https://img.shields.io/github/actions/workflow/status/earthai-tech/fusionlab-learn/.github%2Fworkflows%2Fpython-package-conda.yml" alt="Build Status"></a>
<a href="https://www.python.org/downloads/release/python-390/"><img src="https://img.shields.io/badge/Python-3.9%2B-blue" alt="Python Version"></a>
<a href="https://github.com/earthai-tech/fusionlab-learn/blob/main/LICENSE"><img src="https://img.shields.io/github/license/earthai-tech/fusionlab-learn?style=flat&color=cyan" alt="License"></a>
</p>
**fusionlab-learn** is a flexible and extensible Python package for building and experimenting with state-of-the-art time series models. It provides robust, research-grade implementations of advanced architectures, from data-driven forecasters to novel Physics-Informed Neural Networks (PINNs).
Whether you're a researcher exploring new architectures or a practitioner building production-grade forecasting systems, `fusionlab-learn` provides tools built on **TensorFlow/Keras** to accelerate your work.
---
## ✨ Key Features
### 🏛️ A Spectrum of Advanced Architectures
The library provides implementations across three major families of forecasting models.
* **[Hybrid Models](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/hybrid/index.html):** Architectures like `HALNet` and `XTFT` that fuse the sequential processing power of LSTMs with the long-range context modeling of attention mechanisms.
* **[Pure Transformers](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/transformers/index.html):** Implementations of the standard "Attention Is All You Need" encoder-decoder architecture, adapted for time series forecasting.
* **[Physics-Informed Models (PINNs)](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/pinn/index.html):** State-of-the-art hybrid models like `TransFlowSubsNet` that integrate physical laws (PDEs) directly into the training process to produce physically consistent and robust forecasts.
### 🧩 Modular & Reusable Components
Build custom models with a rich set of well-tested neural network blocks, including:
* [Gated Residual Networks (GRNs) & Variable Selection Networks (VSNs)](https://fusion-lab.readthedocs.io/en/latest/user_guide/components.html)
* Specialized [Attention Layers](https://fusion-lab.readthedocs.io/en/latest/user_guide/user_guide/components.html#attention-mechanisms): `CrossAttention`, `HierarchicalAttention`, and `MemoryAugmentedAttention`
* [Multi-Scale LSTMs](https://fusion-lab.readthedocs.io/en/latest/user_guide/components.html#multiscalelstm) for capturing temporal patterns at various resolutions.
### ⚛️ PINN Capabilities
- Solve coupled-physics problems with models like **[TransFlowSubsNet](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/pinn/transflow_subnet.html)**.
- Perform **inverse modeling** by configuring physical coefficients (`K`, `Ss`, `C`) as learnable parameters.
- Utilize specialized **[PINN data utilities](https://fusion-lab.readthedocs.io/en/latest/user_guide/utils/pinn_utils.html)** for the unique sequence and coordinate preparation required by these models.
### 🛠️ Unified Hyperparameter Tuning
- Leverage the **[HydroTuner](https://fusion-lab.readthedocs.io/en/latest/user_guide/forecast_tuner/hydro_tuner_guide.html)** to automatically find optimal hyperparameters for all hydrogeological PINN models.
- Use dedicated tuners for data-driven models like `HALNet` and `XTFT`.
- The tuner's `.create()` factory method automatically infers data dimensions, making setup fast and easy.
---
## 🚀 Getting Started
### Installation
1. **Prerequisites:**
* Python 3.9+
* [TensorFlow >=2.15](https://www.tensorflow.org/install)
2. **Install from PyPI (Recommended):**
```bash
pip install fusionlab-learn
```
3. **Install from Source (for Development):**
```bash
git clone https://github.com/earthai-tech/fusionlab-learn.git
cd fusionlab-learn
pip install -e .
```
### Quick Example
```python
import numpy as np
import tensorflow as tf
from fusionlab.nn.models import HALNet # Or any other model
# --- 1. Prepare Dummy Data ---
# (Replace with your actual preprocessed & sequenced data)
B, T, D_dyn = 16, 10, 3 # Batch, TimeSteps, DynamicFeatures
D_stat = 2 # StaticFeatures
D_fut = 1 # FutureFeatures
H = 5 # Forecast Horizon
# Model expects list: [Static, Dynamic, Future]
dummy_static = np.random.rand(B, D_stat).astype(np.float32)
dummy_dynamic = np.random.rand(B, T, D_dyn).astype(np.float32)
# For 'tft_like' mode, future input spans past + horizon
dummy_future = np.random.rand(B, T + H, D_fut).astype(np.float32)
dummy_target = np.random.rand(B, H, 1).astype(np.float32)
model_inputs = [dummy_static, dummy_dynamic, dummy_future]
# --- 2. Instantiate Model ---
model = HALNet(
static_input_dim=D_stat,
dynamic_input_dim=D_dyn,
future_input_dim=D_fut,
forecast_horizon=H,
max_window_size=T,
output_dim=1,
hidden_units=16, # Smaller units for quick example
num_heads=2
)
# --- 3. Compile & Train ---
model.compile(optimizer='adam', loss='mse')
print("Training simple model...")
model.fit(model_inputs, dummy_target, epochs=2, batch_size=4, verbose=0)
print("Training finished.")
# --- 4. Predict ---
print("Making predictions...")
predictions = model.predict(model_inputs)
print("Prediction shape:", predictions.shape)
# Expected: (16, 5, 1) -> (Batch, Horizon, NumOutputs)
```
*(See the* [*Quickstart Guide*](https://fusion-lab.readthedocs.io/en/latest/quickstart.html) *for a more detailed walkthrough.)*
-----
## 📚 Documentation
For detailed usage, tutorials, API reference, and explanations of the
underlying concepts, please see the full documentation:
**[Read the Documentation](https://fusion-lab.readthedocs.io/)**
-----
## 📄 License
This project is licensed under the **BSD-3-Clause**. See the
[LICENSE](https://github.com/earthai-tech/fusionlab-learn/blob/main/LICENSE) file for details.
----
## 🤝 Contributing
We welcome contributions\! Whether it's adding new features, fixing bugs,
or improving documentation, your help is appreciated. Please see our
[Contribution Guidelines](https://fusion-lab.readthedocs.io/en/latest/contributing.html) for more details on how to get
started.
-----
## 📞 Contact & Support
* **Bug Reports & Feature Requests:** The best place to report issues,
ask questions about usage, or request new features is the
[**GitHub Issues**](https://github.com/earthai-tech/fusionlab-learn/issues) page for the project.
* **Developer Contact:** For direct inquiries related to the project's
origins or specific collaborations, you can reach the author:
* **Name:** Laurent Kouadio
* 📧 **Email:** [etanoyau@gmail.com](mailto:etanoyau@gmail.com)
* 💼 **LinkedIn:** [linkedin.com/in/laurent-kouadio-483b2baa](https://linkedin.com/in/laurent-kouadio-483b2baa)
* 🆔 **ORCID:** [0000-0001-7259-7254](https://orcid.org/0000-0001-7259-7254)
Raw data
{
"_id": null,
"home_page": "https://github.com/earthai-tech/fusionlab-learn",
"name": "fusionlab-learn",
"maintainer": "Laurent Kouadio",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Laurent Kouadio <etanoyau@gmail.com>",
"keywords": "time-series forecasting, machine learning, temporal fusion, deep learning",
"author": "Laurent Kouadio",
"author_email": "Laurent Kouadio <etanoyau@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/17/28/d48f81c1e370231ffb781c1047561102ee2fdb61eaa6f5d370feb671a5bd/fusionlab_learn-0.3.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\r\n <img\r\n src=\"https://raw.githubusercontent.com/earthai-tech/fusionlab-learn/main/docs/source/_static/fusionlab.svg\"\r\n alt=\"FusionLab Logo\"\r\n width=\"200\"\r\n >\r\n</p>\r\n\r\n-----------------------------------------------------\r\n\r\n<h1 align=\"center\">fusionlab-learn</h1>\r\n\r\n<p align=\"center\"><em>A Research-Oriented Library for Advanced Time Series Forecasting with Hybrid, Transformer, and Physics-Informed Models</em></p>\r\n\r\n<p align=\"center\">\r\n <a href=\"https://pypi.org/project/fusionlab-learn/\"><img src=\"https://img.shields.io/pypi/v/fusionlab-learn\" alt=\"PyPI Version\"></a>\r\n <a href=\"https://fusion-lab.readthedocs.io/en/latest/?badge=latest\"><img src=\"https://readthedocs.org/projects/fusion-lab/badge/?version=latest\" alt=\"Documentation Status\"></a>\r\n <a href=\"https://github.com/earthai-tech/fusionlab-learn/actions\"><img src=\"https://img.shields.io/github/actions/workflow/status/earthai-tech/fusionlab-learn/.github%2Fworkflows%2Fpython-package-conda.yml\" alt=\"Build Status\"></a>\r\n <a href=\"https://www.python.org/downloads/release/python-390/\"><img src=\"https://img.shields.io/badge/Python-3.9%2B-blue\" alt=\"Python Version\"></a>\r\n <a href=\"https://github.com/earthai-tech/fusionlab-learn/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/earthai-tech/fusionlab-learn?style=flat&color=cyan\" alt=\"License\"></a>\r\n</p>\r\n\r\n**fusionlab-learn** is a flexible and extensible Python package for building and experimenting with state-of-the-art time series models. It provides robust, research-grade implementations of advanced architectures, from data-driven forecasters to novel Physics-Informed Neural Networks (PINNs).\r\n\r\nWhether you're a researcher exploring new architectures or a practitioner building production-grade forecasting systems, `fusionlab-learn` provides tools built on **TensorFlow/Keras** to accelerate your work.\r\n\r\n---\r\n\r\n## \u2728 Key Features\r\n\r\n### \ud83c\udfdb\ufe0f A Spectrum of Advanced Architectures\r\nThe library provides implementations across three major families of forecasting models.\r\n\r\n* **[Hybrid Models](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/hybrid/index.html):** Architectures like `HALNet` and `XTFT` that fuse the sequential processing power of LSTMs with the long-range context modeling of attention mechanisms.\r\n* **[Pure Transformers](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/transformers/index.html):** Implementations of the standard \"Attention Is All You Need\" encoder-decoder architecture, adapted for time series forecasting.\r\n* **[Physics-Informed Models (PINNs)](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/pinn/index.html):** State-of-the-art hybrid models like `TransFlowSubsNet` that integrate physical laws (PDEs) directly into the training process to produce physically consistent and robust forecasts.\r\n\r\n### \ud83e\udde9 Modular & Reusable Components\r\nBuild custom models with a rich set of well-tested neural network blocks, including:\r\n* [Gated Residual Networks (GRNs) & Variable Selection Networks (VSNs)](https://fusion-lab.readthedocs.io/en/latest/user_guide/components.html)\r\n* Specialized [Attention Layers](https://fusion-lab.readthedocs.io/en/latest/user_guide/user_guide/components.html#attention-mechanisms): `CrossAttention`, `HierarchicalAttention`, and `MemoryAugmentedAttention`\r\n* [Multi-Scale LSTMs](https://fusion-lab.readthedocs.io/en/latest/user_guide/components.html#multiscalelstm) for capturing temporal patterns at various resolutions.\r\n\r\n### \u269b\ufe0f PINN Capabilities\r\n- Solve coupled-physics problems with models like **[TransFlowSubsNet](https://fusion-lab.readthedocs.io/en/latest/user_guide/models/pinn/transflow_subnet.html)**.\r\n- Perform **inverse modeling** by configuring physical coefficients (`K`, `Ss`, `C`) as learnable parameters.\r\n- Utilize specialized **[PINN data utilities](https://fusion-lab.readthedocs.io/en/latest/user_guide/utils/pinn_utils.html)** for the unique sequence and coordinate preparation required by these models.\r\n\r\n### \ud83d\udee0\ufe0f Unified Hyperparameter Tuning\r\n- Leverage the **[HydroTuner](https://fusion-lab.readthedocs.io/en/latest/user_guide/forecast_tuner/hydro_tuner_guide.html)** to automatically find optimal hyperparameters for all hydrogeological PINN models.\r\n- Use dedicated tuners for data-driven models like `HALNet` and `XTFT`.\r\n- The tuner's `.create()` factory method automatically infers data dimensions, making setup fast and easy.\r\n\r\n---\r\n\r\n## \ud83d\ude80 Getting Started\r\n\r\n### Installation\r\n\r\n1. **Prerequisites:**\r\n * Python 3.9+\r\n * [TensorFlow >=2.15](https://www.tensorflow.org/install)\r\n\r\n2. **Install from PyPI (Recommended):**\r\n ```bash\r\n pip install fusionlab-learn\r\n ```\r\n\r\n3. **Install from Source (for Development):**\r\n ```bash\r\n git clone https://github.com/earthai-tech/fusionlab-learn.git\r\n cd fusionlab-learn\r\n pip install -e .\r\n ```\r\n\r\n### Quick Example\r\n\r\n```python\r\nimport numpy as np\r\nimport tensorflow as tf\r\nfrom fusionlab.nn.models import HALNet # Or any other model\r\n\r\n# --- 1. Prepare Dummy Data ---\r\n# (Replace with your actual preprocessed & sequenced data)\r\nB, T, D_dyn = 16, 10, 3 # Batch, TimeSteps, DynamicFeatures\r\nD_stat = 2 # StaticFeatures\r\nD_fut = 1 # FutureFeatures\r\nH = 5 # Forecast Horizon\r\n\r\n# Model expects list: [Static, Dynamic, Future]\r\ndummy_static = np.random.rand(B, D_stat).astype(np.float32)\r\ndummy_dynamic = np.random.rand(B, T, D_dyn).astype(np.float32)\r\n# For 'tft_like' mode, future input spans past + horizon\r\ndummy_future = np.random.rand(B, T + H, D_fut).astype(np.float32)\r\ndummy_target = np.random.rand(B, H, 1).astype(np.float32)\r\n\r\nmodel_inputs = [dummy_static, dummy_dynamic, dummy_future]\r\n\r\n# --- 2. Instantiate Model ---\r\nmodel = HALNet(\r\n static_input_dim=D_stat,\r\n dynamic_input_dim=D_dyn,\r\n future_input_dim=D_fut,\r\n forecast_horizon=H,\r\n max_window_size=T,\r\n output_dim=1,\r\n hidden_units=16, # Smaller units for quick example\r\n num_heads=2\r\n)\r\n\r\n# --- 3. Compile & Train ---\r\nmodel.compile(optimizer='adam', loss='mse')\r\nprint(\"Training simple model...\")\r\nmodel.fit(model_inputs, dummy_target, epochs=2, batch_size=4, verbose=0)\r\nprint(\"Training finished.\")\r\n\r\n# --- 4. Predict ---\r\nprint(\"Making predictions...\")\r\npredictions = model.predict(model_inputs)\r\nprint(\"Prediction shape:\", predictions.shape)\r\n# Expected: (16, 5, 1) -> (Batch, Horizon, NumOutputs)\r\n\r\n```\r\n\r\n*(See the* [*Quickstart Guide*](https://fusion-lab.readthedocs.io/en/latest/quickstart.html) *for a more detailed walkthrough.)*\r\n\r\n-----\r\n\r\n## \ud83d\udcda Documentation\r\n\r\nFor detailed usage, tutorials, API reference, and explanations of the\r\nunderlying concepts, please see the full documentation:\r\n\r\n**[Read the Documentation](https://fusion-lab.readthedocs.io/)**\r\n\r\n-----\r\n\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the **BSD-3-Clause**. See the\r\n[LICENSE](https://github.com/earthai-tech/fusionlab-learn/blob/main/LICENSE) file for details.\r\n\r\n----\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions\\! Whether it's adding new features, fixing bugs,\r\nor improving documentation, your help is appreciated. Please see our\r\n[Contribution Guidelines](https://fusion-lab.readthedocs.io/en/latest/contributing.html) for more details on how to get\r\nstarted.\r\n\r\n-----\r\n\r\n## \ud83d\udcde Contact & Support\r\n\r\n * **Bug Reports & Feature Requests:** The best place to report issues,\r\n ask questions about usage, or request new features is the\r\n [**GitHub Issues**](https://github.com/earthai-tech/fusionlab-learn/issues) page for the project.\r\n\r\n * **Developer Contact:** For direct inquiries related to the project's\r\n origins or specific collaborations, you can reach the author:\r\n\r\n * **Name:** Laurent Kouadio\r\n * \ud83d\udce7 **Email:** [etanoyau@gmail.com](mailto:etanoyau@gmail.com)\r\n * \ud83d\udcbc **LinkedIn:** [linkedin.com/in/laurent-kouadio-483b2baa](https://linkedin.com/in/laurent-kouadio-483b2baa)\r\n * \ud83c\udd94 **ORCID:** [0000-0001-7259-7254](https://orcid.org/0000-0001-7259-7254)\r\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Next-Gen Temporal Fusion Architectures for Time-Series Forecasting",
"version": "0.3.1",
"project_urls": {
"API Documentation": "https://fusion-lab.readthedocs.io/en/latest/api.html",
"Bugs tracker": "https://github.com/earthai-tech/fusionlab-learn/issues",
"Home page": "https://fusion-lab.readthedocs.io",
"Homepage": "https://github.com/earthai-tech/fusionlab-learn",
"Installation guide": "https://fusion-lab.readthedocs.io/en/latest/installation.html",
"User guide": "https://fusion-lab.readthedocs.io/en/latest/user_guide.html"
},
"split_keywords": [
"time-series forecasting",
" machine learning",
" temporal fusion",
" deep learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "53989422ddd894054123aea30cc2dc3aa977a0b68145dd7aa0aed76e7b2a9b2c",
"md5": "e747d8b8c1f5fcde459360b006074720",
"sha256": "11883ed1505739747ebc436b838829ee62f4fa867c45a9a8db335a40a6a230d3"
},
"downloads": -1,
"filename": "fusionlab_learn-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e747d8b8c1f5fcde459360b006074720",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 2422565,
"upload_time": "2025-07-19T10:01:10",
"upload_time_iso_8601": "2025-07-19T10:01:10.257397Z",
"url": "https://files.pythonhosted.org/packages/53/98/9422ddd894054123aea30cc2dc3aa977a0b68145dd7aa0aed76e7b2a9b2c/fusionlab_learn-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1728d48f81c1e370231ffb781c1047561102ee2fdb61eaa6f5d370feb671a5bd",
"md5": "c9c9ce82cc96376592064c7da6a0c329",
"sha256": "bd2fe4d97341fb12cacee2b0e9d9ee3854ef39021ccf73d488e847b5187b0a26"
},
"downloads": -1,
"filename": "fusionlab_learn-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c9c9ce82cc96376592064c7da6a0c329",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 2241290,
"upload_time": "2025-07-19T10:01:11",
"upload_time_iso_8601": "2025-07-19T10:01:11.917135Z",
"url": "https://files.pythonhosted.org/packages/17/28/d48f81c1e370231ffb781c1047561102ee2fdb61eaa6f5d370feb671a5bd/fusionlab_learn-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 10:01:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "earthai-tech",
"github_project": "fusionlab-learn",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fusionlab-learn"
}
JSON
