<div align="center">
<img src="https://pl-public-data.s3.amazonaws.com/assets_lightning/fabric_logo.png" width="400px">
**Fabric is the fast and lightweight way to scale PyTorch models without boilerplate**
______________________________________________________________________
<p align="center">
<a href="https://lightning.ai/">Website</a> •
<a href="https://lightning.ai/docs/fabric/">Docs</a> •
<a href="#getting-started">Getting started</a> •
<a href="#faq">FAQ</a> •
<a href="#asking-for-help">Help</a> •
<a href="https://discord.gg/VptPCZkGNa">Discord</a>
</p>
[](https://pypi.org/project/lightning_fabric/)
[](https://badge.fury.io/py/lightning_fabric)
[](https://pepy.tech/project/lightning-fabric)
[](https://anaconda.org/conda-forge/lightning_fabric)
</div>
# Lightning Fabric: Expert control.
Run on any device at any scale with expert-level control over PyTorch training loop and scaling strategy. You can even write your own Trainer.
Fabric is designed for the most complex models like foundation model scaling, LLMs, diffusion, transformers, reinforcement learning, active learning. Of any size.
<table>
<tr>
<th>What to change</th>
<th>Resulting Fabric Code (copy me!)</th>
</tr>
<tr>
<td>
<sub>
```diff
+ import lightning as L
import torch; import torchvision as tv
dataset = tv.datasets.CIFAR10("data", download=True,
train=True,
transform=tv.transforms.ToTensor())
+ fabric = L.Fabric()
+ fabric.launch()
model = tv.models.resnet18()
optimizer = torch.optim.SGD(model.parameters(), lr=0.001)
- device = "cuda" if torch.cuda.is_available() else "cpu"
- model.to(device)
+ model, optimizer = fabric.setup(model, optimizer)
dataloader = torch.utils.data.DataLoader(dataset, batch_size=8)
+ dataloader = fabric.setup_dataloaders(dataloader)
model.train()
num_epochs = 10
for epoch in range(num_epochs):
for batch in dataloader:
inputs, labels = batch
- inputs, labels = inputs.to(device), labels.to(device)
optimizer.zero_grad()
outputs = model(inputs)
loss = torch.nn.functional.cross_entropy(outputs, labels)
- loss.backward()
+ fabric.backward(loss)
optimizer.step()
```
</sub>
<td>
<sub>
```Python
import lightning as L
import torch; import torchvision as tv
dataset = tv.datasets.CIFAR10("data", download=True,
train=True,
transform=tv.transforms.ToTensor())
fabric = L.Fabric()
fabric.launch()
model = tv.models.resnet18()
optimizer = torch.optim.SGD(model.parameters(), lr=0.001)
model, optimizer = fabric.setup(model, optimizer)
dataloader = torch.utils.data.DataLoader(dataset, batch_size=8)
dataloader = fabric.setup_dataloaders(dataloader)
model.train()
num_epochs = 10
for epoch in range(num_epochs):
for batch in dataloader:
inputs, labels = batch
optimizer.zero_grad()
outputs = model(inputs)
loss = torch.nn.functional.cross_entropy(outputs, labels)
fabric.backward(loss)
optimizer.step()
```
</sub>
</td>
</tr>
</table>
## Key features
<details>
<summary>Easily switch from running on CPU to GPU (Apple Silicon, CUDA, …), TPU, multi-GPU or even multi-node training</summary>
```python
# Use your available hardware
# no code changes needed
fabric = Fabric()
# Run on GPUs (CUDA or MPS)
fabric = Fabric(accelerator="gpu")
# 8 GPUs
fabric = Fabric(accelerator="gpu", devices=8)
# 256 GPUs, multi-node
fabric = Fabric(accelerator="gpu", devices=8, num_nodes=32)
# Run on TPUs
fabric = Fabric(accelerator="tpu")
```
</details>
<details>
<summary>Use state-of-the-art distributed training strategies (DDP, FSDP, DeepSpeed) and mixed precision out of the box</summary>
```python
# Use state-of-the-art distributed training techniques
fabric = Fabric(strategy="ddp")
fabric = Fabric(strategy="deepspeed")
fabric = Fabric(strategy="fsdp")
# Switch the precision
fabric = Fabric(precision="16-mixed")
fabric = Fabric(precision="64")
```
</details>
<details>
<summary>All the device logic boilerplate is handled for you</summary>
```diff
# no more of this!
- model.to(device)
- batch.to(device)
```
</details>
<details>
<summary>Build your own custom Trainer using Fabric primitives for training checkpointing, logging, and more</summary>
```python
import lightning as L
class MyCustomTrainer:
def __init__(self, accelerator="auto", strategy="auto", devices="auto", precision="32-true"):
self.fabric = L.Fabric(accelerator=accelerator, strategy=strategy, devices=devices, precision=precision)
def fit(self, model, optimizer, dataloader, max_epochs):
self.fabric.launch()
model, optimizer = self.fabric.setup(model, optimizer)
dataloader = self.fabric.setup_dataloaders(dataloader)
model.train()
for epoch in range(max_epochs):
for batch in dataloader:
input, target = batch
optimizer.zero_grad()
output = model(input)
loss = loss_fn(output, target)
self.fabric.backward(loss)
optimizer.step()
```
You can find a more extensive example in our [examples](../../examples/fabric/build_your_own_trainer)
</details>
______________________________________________________________________
<div align="center">
<a href="https://lightning.ai/docs/fabric/stable/">Read the Lightning Fabric docs</a>
</div>
______________________________________________________________________
## Continuous Integration
Lightning is rigorously tested across multiple CPUs and GPUs and against major Python and PyTorch versions.
###### \*Codecov is > 90%+ but build delays may show less
<details>
<summary>Current build statuses</summary>
<center>
| System / PyTorch ver. | 1.12 | 1.13 | 2.0 | 2.1 |
| :--------------------------------: | :-------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------: |
| Linux py3.9 \[GPUs\] | | | |  |
| Linux (multiple Python versions) |  |  |  |  |
| OSX (multiple Python versions) |  |  |  |  |
| Windows (multiple Python versions) |  |  |  |  |
</center>
</details>
______________________________________________________________________
# Getting started
## Install Lightning
<details>
<summary>Prerequisites</summary>
> TIP: We strongly recommend creating a virtual environment first.
> Don’t know what this is? Follow our [beginner guide here](https://lightning.ai/docs/stable/install/installation.html).
- Python 3.8.x or later (3.8.x, 3.9.x, 3.10.x, ...)
</details>
```bash
pip install -U lightning
```
## Convert your PyTorch to Fabric
1. Create the `Fabric` object at the beginning of your training code.
```
import Lightning as L
fabric = L.Fabric()
```
1. Call `setup()` on each model and optimizer pair and `setup_dataloaders()` on all your data loaders.
```
model, optimizer = fabric.setup(model, optimizer)
dataloader = fabric.setup_dataloaders(dataloader)
```
1. Remove all `.to` and `.cuda` calls -> Fabric will take care of it.
```diff
- model.to(device)
- batch.to(device)
```
1. Replace `loss.backward()` by `fabric.backward(loss)`.
```diff
- loss.backward()
+ fabric.backward(loss)
```
1. Run the script from the terminal with
```bash
lightning run model path/to/train.py
```
or use the launch() method in a notebook. Learn more about [launching distributed training](https://lightning.ai/docs/fabric/stable/fundamentals/launch.html).
______________________________________________________________________
# FAQ
## When to use Fabric?
- **Minimum code changes**- You want to scale your PyTorch model to use multi-GPU or use advanced strategies like DeepSpeed without having to refactor. You don’t care about structuring your code- you just want to scale it as fast as possible.
- **Maximum control**- Write your own training and/or inference logic down to the individual optimizer calls. You aren’t forced to conform to a standardized epoch-based training loop like the one in Lightning Trainer. You can do flexible iteration based training, meta-learning, cross-validation and other types of optimization algorithms without digging into framework internals. This also makes it super easy to adopt Fabric in existing PyTorch projects to speed-up and scale your models without the compromise on large refactors. Just remember: With great power comes a great responsibility.
- **Maximum flexibility**- You want to have full control over your entire training- in Fabric all features are opt-in, and it provides you with a tool box of primitives so you can build your own Trainer.
## When to use the [Lightning Trainer](https://lightning.ai/docs/pytorch/stable/common/trainer.html)?
- You want to have all the engineering boilerplate handled for you - dozens of features like checkpointing, logging and early stopping out of the box. Less hassle, less error prone, easy to try different techniques and features.
- You want to have good defaults chosen for you - so you can have a better starting point.
- You want your code to be modular, readable and well structured - easy to share between projects and with collaborators.
## Can I use Fabric with my LightningModule or Lightning Callback?
Yes :) Fabric works with PyTorch LightningModules and Callbacks, so you can choose how to structure your code and reuse existing models and callbacks as you wish. Read more [here](https://lightning.ai/docs/fabric/stable/fundamentals/code_structure.html).
<img src="https://pl-public-data.s3.amazonaws.com/assets_lightning/continuum.png" width="800px">
______________________________________________________________________
# Examples
- [GAN](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/dcgan)
- [Meta learning](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/meta_learning)
- [Reinforcement learning](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/reinforcement_learning)
- [K-Fold cross validation](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/kfold_cv)
______________________________________________________________________
## Asking for help
If you have any questions please:
1. [Read the docs](https://lightning.ai/docs/fabric).
1. [Ask a question in our forum](https://lightning.ai/forums/).
1. [Join our discord community](https://discord.com/invite/tfXFetEZxv).
Raw data
{
"_id": null,
"home_page": "https://github.com/Lightning-AI/lightning",
"name": "lightning-fabric",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "deep learning, pytorch, AI",
"author": "Lightning AI et al.",
"author_email": "pytorch@lightning.ai",
"download_url": "https://files.pythonhosted.org/packages/d0/76/c1dc2da5f2e3d90ffa623ac42470326f35a6c73ca4ce56d1c73d71a473db/lightning-fabric-2.2.4.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n<img src=\"https://pl-public-data.s3.amazonaws.com/assets_lightning/fabric_logo.png\" width=\"400px\">\n\n**Fabric is the fast and lightweight way to scale PyTorch models without boilerplate**\n\n______________________________________________________________________\n\n<p align=\"center\">\n <a href=\"https://lightning.ai/\">Website</a> \u2022\n <a href=\"https://lightning.ai/docs/fabric/\">Docs</a> \u2022\n <a href=\"#getting-started\">Getting started</a> \u2022\n <a href=\"#faq\">FAQ</a> \u2022\n <a href=\"#asking-for-help\">Help</a> \u2022\n <a href=\"https://discord.gg/VptPCZkGNa\">Discord</a>\n</p>\n\n[](https://pypi.org/project/lightning_fabric/)\n[](https://badge.fury.io/py/lightning_fabric)\n[](https://pepy.tech/project/lightning-fabric)\n[](https://anaconda.org/conda-forge/lightning_fabric)\n\n</div>\n\n# Lightning Fabric: Expert control.\n\nRun on any device at any scale with expert-level control over PyTorch training loop and scaling strategy. You can even write your own Trainer.\n\nFabric is designed for the most complex models like foundation model scaling, LLMs, diffusion, transformers, reinforcement learning, active learning. Of any size.\n\n<table>\n<tr>\n<th>What to change</th>\n<th>Resulting Fabric Code (copy me!)</th>\n</tr>\n<tr>\n<td>\n<sub>\n\n```diff\n+ import lightning as L\n import torch; import torchvision as tv\n\n dataset = tv.datasets.CIFAR10(\"data\", download=True,\n train=True,\n transform=tv.transforms.ToTensor())\n\n+ fabric = L.Fabric()\n+ fabric.launch()\n\n model = tv.models.resnet18()\n optimizer = torch.optim.SGD(model.parameters(), lr=0.001)\n- device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n- model.to(device)\n+ model, optimizer = fabric.setup(model, optimizer)\n\n dataloader = torch.utils.data.DataLoader(dataset, batch_size=8)\n+ dataloader = fabric.setup_dataloaders(dataloader)\n\n model.train()\n num_epochs = 10\n for epoch in range(num_epochs):\n for batch in dataloader:\n inputs, labels = batch\n- inputs, labels = inputs.to(device), labels.to(device)\n optimizer.zero_grad()\n outputs = model(inputs)\n loss = torch.nn.functional.cross_entropy(outputs, labels)\n- loss.backward()\n+ fabric.backward(loss)\n optimizer.step()\n```\n\n</sub>\n<td>\n<sub>\n\n```Python\nimport lightning as L\nimport torch; import torchvision as tv\n\ndataset = tv.datasets.CIFAR10(\"data\", download=True,\n train=True,\n transform=tv.transforms.ToTensor())\n\nfabric = L.Fabric()\nfabric.launch()\n\nmodel = tv.models.resnet18()\noptimizer = torch.optim.SGD(model.parameters(), lr=0.001)\nmodel, optimizer = fabric.setup(model, optimizer)\n\ndataloader = torch.utils.data.DataLoader(dataset, batch_size=8)\ndataloader = fabric.setup_dataloaders(dataloader)\n\nmodel.train()\nnum_epochs = 10\nfor epoch in range(num_epochs):\n for batch in dataloader:\n inputs, labels = batch\n optimizer.zero_grad()\n outputs = model(inputs)\n loss = torch.nn.functional.cross_entropy(outputs, labels)\n fabric.backward(loss)\n optimizer.step()\n```\n\n</sub>\n</td>\n</tr>\n</table>\n\n## Key features\n\n<details>\n <summary>Easily switch from running on CPU to GPU (Apple Silicon, CUDA, \u2026), TPU, multi-GPU or even multi-node training</summary>\n\n```python\n# Use your available hardware\n# no code changes needed\nfabric = Fabric()\n\n# Run on GPUs (CUDA or MPS)\nfabric = Fabric(accelerator=\"gpu\")\n\n# 8 GPUs\nfabric = Fabric(accelerator=\"gpu\", devices=8)\n\n# 256 GPUs, multi-node\nfabric = Fabric(accelerator=\"gpu\", devices=8, num_nodes=32)\n\n# Run on TPUs\nfabric = Fabric(accelerator=\"tpu\")\n```\n\n</details>\n\n<details>\n <summary>Use state-of-the-art distributed training strategies (DDP, FSDP, DeepSpeed) and mixed precision out of the box</summary>\n\n```python\n# Use state-of-the-art distributed training techniques\nfabric = Fabric(strategy=\"ddp\")\nfabric = Fabric(strategy=\"deepspeed\")\nfabric = Fabric(strategy=\"fsdp\")\n\n# Switch the precision\nfabric = Fabric(precision=\"16-mixed\")\nfabric = Fabric(precision=\"64\")\n```\n\n</details>\n\n<details>\n <summary>All the device logic boilerplate is handled for you</summary>\n\n```diff\n # no more of this!\n- model.to(device)\n- batch.to(device)\n```\n\n</details>\n\n<details>\n <summary>Build your own custom Trainer using Fabric primitives for training checkpointing, logging, and more</summary>\n\n```python\nimport lightning as L\n\n\nclass MyCustomTrainer:\n def __init__(self, accelerator=\"auto\", strategy=\"auto\", devices=\"auto\", precision=\"32-true\"):\n self.fabric = L.Fabric(accelerator=accelerator, strategy=strategy, devices=devices, precision=precision)\n\n def fit(self, model, optimizer, dataloader, max_epochs):\n self.fabric.launch()\n\n model, optimizer = self.fabric.setup(model, optimizer)\n dataloader = self.fabric.setup_dataloaders(dataloader)\n model.train()\n\n for epoch in range(max_epochs):\n for batch in dataloader:\n input, target = batch\n optimizer.zero_grad()\n output = model(input)\n loss = loss_fn(output, target)\n self.fabric.backward(loss)\n optimizer.step()\n```\n\nYou can find a more extensive example in our [examples](../../examples/fabric/build_your_own_trainer)\n\n</details>\n\n______________________________________________________________________\n\n<div align=\"center\">\n <a href=\"https://lightning.ai/docs/fabric/stable/\">Read the Lightning Fabric docs</a>\n</div>\n\n______________________________________________________________________\n\n## Continuous Integration\n\nLightning is rigorously tested across multiple CPUs and GPUs and against major Python and PyTorch versions.\n\n###### \\*Codecov is > 90%+ but build delays may show less\n\n<details>\n <summary>Current build statuses</summary>\n\n<center>\n\n| System / PyTorch ver. | 1.12 | 1.13 | 2.0 | 2.1 |\n| :--------------------------------: | :-------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------: |\n| Linux py3.9 \\[GPUs\\] | | | |  |\n| Linux (multiple Python versions) |  |  |  |  |\n| OSX (multiple Python versions) |  |  |  |  |\n| Windows (multiple Python versions) |  |  |  |  |\n\n</center>\n</details>\n\n______________________________________________________________________\n\n# Getting started\n\n## Install Lightning\n\n<details>\n\n<summary>Prerequisites</summary>\n\n> TIP: We strongly recommend creating a virtual environment first.\n> Don\u2019t know what this is? Follow our [beginner guide here](https://lightning.ai/docs/stable/install/installation.html).\n\n- Python 3.8.x or later (3.8.x, 3.9.x, 3.10.x, ...)\n\n</details>\n\n```bash\npip install -U lightning\n```\n\n## Convert your PyTorch to Fabric\n\n1. Create the `Fabric` object at the beginning of your training code.\n\n ```\n import Lightning as L\n\n fabric = L.Fabric()\n ```\n\n1. Call `setup()` on each model and optimizer pair and `setup_dataloaders()` on all your data loaders.\n\n ```\n model, optimizer = fabric.setup(model, optimizer)\n dataloader = fabric.setup_dataloaders(dataloader)\n ```\n\n1. Remove all `.to` and `.cuda` calls -> Fabric will take care of it.\n\n ```diff\n - model.to(device)\n - batch.to(device)\n ```\n\n1. Replace `loss.backward()` by `fabric.backward(loss)`.\n\n ```diff\n - loss.backward()\n + fabric.backward(loss)\n ```\n\n1. Run the script from the terminal with\n\n ```bash\n lightning run model path/to/train.py\n ```\n\nor use the launch() method in a notebook. Learn more about [launching distributed training](https://lightning.ai/docs/fabric/stable/fundamentals/launch.html).\n\n______________________________________________________________________\n\n# FAQ\n\n## When to use Fabric?\n\n- **Minimum code changes**- You want to scale your PyTorch model to use multi-GPU or use advanced strategies like DeepSpeed without having to refactor. You don\u2019t care about structuring your code- you just want to scale it as fast as possible.\n- **Maximum control**- Write your own training and/or inference logic down to the individual optimizer calls. You aren\u2019t forced to conform to a standardized epoch-based training loop like the one in Lightning Trainer. You can do flexible iteration based training, meta-learning, cross-validation and other types of optimization algorithms without digging into framework internals. This also makes it super easy to adopt Fabric in existing PyTorch projects to speed-up and scale your models without the compromise on large refactors. Just remember: With great power comes a great responsibility.\n- **Maximum flexibility**- You want to have full control over your entire training- in Fabric all features are opt-in, and it provides you with a tool box of primitives so you can build your own Trainer.\n\n## When to use the [Lightning Trainer](https://lightning.ai/docs/pytorch/stable/common/trainer.html)?\n\n- You want to have all the engineering boilerplate handled for you - dozens of features like checkpointing, logging and early stopping out of the box. Less hassle, less error prone, easy to try different techniques and features.\n- You want to have good defaults chosen for you - so you can have a better starting point.\n- You want your code to be modular, readable and well structured - easy to share between projects and with collaborators.\n\n## Can I use Fabric with my LightningModule or Lightning Callback?\n\nYes :) Fabric works with PyTorch LightningModules and Callbacks, so you can choose how to structure your code and reuse existing models and callbacks as you wish. Read more [here](https://lightning.ai/docs/fabric/stable/fundamentals/code_structure.html).\n\n<img src=\"https://pl-public-data.s3.amazonaws.com/assets_lightning/continuum.png\" width=\"800px\">\n\n______________________________________________________________________\n\n# Examples\n\n- [GAN](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/dcgan)\n- [Meta learning](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/meta_learning)\n- [Reinforcement learning](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/reinforcement_learning)\n- [K-Fold cross validation](https://github.com/Lightning-AI/lightning/tree/master/examples/fabric/kfold_cv)\n\n______________________________________________________________________\n\n## Asking for help\n\nIf you have any questions please:\n\n1. [Read the docs](https://lightning.ai/docs/fabric).\n1. [Ask a question in our forum](https://lightning.ai/forums/).\n1. [Join our discord community](https://discord.com/invite/tfXFetEZxv).\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": null,
"version": "2.2.4",
"project_urls": {
"Bug Tracker": "https://github.com/Lightning-AI/lightning/issues",
"Documentation": "https://pytorch-lightning.rtfd.io/en/latest/",
"Download": "https://github.com/Lightning-AI/lightning",
"Homepage": "https://github.com/Lightning-AI/lightning",
"Source Code": "https://github.com/Lightning-AI/lightning"
},
"split_keywords": [
"deep learning",
" pytorch",
" ai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8bacf6f4cf0bc43907ff304218b7f0618e0c7936ff298c5e94e7efac77b6e7e",
"md5": "427c5a26b94d6f275dda082b4080f7dd",
"sha256": "aaa7fc039f1bf730a04361580bf3fa51867ce362e95ad30d1af6335155a23e1f"
},
"downloads": -1,
"filename": "lightning_fabric-2.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "427c5a26b94d6f275dda082b4080f7dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 243411,
"upload_time": "2024-05-01T22:58:18",
"upload_time_iso_8601": "2024-05-01T22:58:18.298850Z",
"url": "https://files.pythonhosted.org/packages/d8/ba/cf6f4cf0bc43907ff304218b7f0618e0c7936ff298c5e94e7efac77b6e7e/lightning_fabric-2.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d076c1dc2da5f2e3d90ffa623ac42470326f35a6c73ca4ce56d1c73d71a473db",
"md5": "190c4a470d4186ee479d521fafab12df",
"sha256": "18883f628063f325b6e09adf4d5804ddd3216a88967ccd3277a65595f1cd46c9"
},
"downloads": -1,
"filename": "lightning-fabric-2.2.4.tar.gz",
"has_sig": false,
"md5_digest": "190c4a470d4186ee479d521fafab12df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 189454,
"upload_time": "2024-05-01T22:58:21",
"upload_time_iso_8601": "2024-05-01T22:58:21.299456Z",
"url": "https://files.pythonhosted.org/packages/d0/76/c1dc2da5f2e3d90ffa623ac42470326f35a6c73ca4ce56d1c73d71a473db/lightning-fabric-2.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 22:58:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Lightning-AI",
"github_project": "lightning",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "lightning-fabric"
}
JSON
