+
+.. displayitem::
+ :header: Level-up with Lightning Apps
+ :description: From Basics to Advanced Skills
+ :col_css: col-md-6
+ :button_link: ../levels/basic/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Understand Lightning App
+ :description: Detailed description
+ :col_css: col-md-6
+ :button_link: lightning_app/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Understand Lightning Flow
+ :description: Detailed description
+ :col_css: col-md-6
+ :button_link: lightning_flow.html
+ :height: 180
+
+.. displayitem::
+ :header: Understand Lightning Work
+ :description: Detailed description
+ :col_css: col-md-6
+ :button_link: lightning_work/index.html
+ :height: 180
diff --git a/docs/source-app/core_api/lightning_app/app.py b/docs/source-app/core_api/lightning_app/app.py
new file mode 100644
index 0000000000..0a435c61c9
--- /dev/null
+++ b/docs/source-app/core_api/lightning_app/app.py
@@ -0,0 +1,27 @@
+import lightning as L
+from lightning.app.utilities.app_helpers import pretty_state
+
+
+class Work(L.LightningWork):
+ def __init__(self):
+ super().__init__(cache_calls=False)
+ # Attributes are registered automatically in the state.
+ self.counter = 0
+
+ def run(self):
+ # Incrementing an attribute gets reflected in the `Flow` state.
+ self.counter += 1
+
+
+class Flow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.w = Work()
+
+ def run(self):
+ if self.w.has_started:
+ print(f"State: {pretty_state(self.state)} \n")
+ self.w.run()
+
+
+app = L.LightningApp(Flow())
diff --git a/docs/source-app/core_api/lightning_app/communication.rst b/docs/source-app/core_api/lightning_app/communication.rst
index a8872585e5..9a823b0844 100644
--- a/docs/source-app/core_api/lightning_app/communication.rst
+++ b/docs/source-app/core_api/lightning_app/communication.rst
@@ -1,138 +1,15 @@
:orphan:
-################################
-Communication Between Components
-################################
+##########################################
+Communication between Lightning Components
+##########################################
**Audience:** Users that want to create interactive applications.
-**Level:** Advanced
+**Level:** Intermediate
-**Prerequisite**: Read the :ref:`access_app_state` guide.
+**Prerequisite**: Read the `Communication in Lightning Apps article <../../access_app_state.html>`_.
----
-***********************************
-Why should components communicate ?
-***********************************
-
-When creating interactive apps with multiple components, you might want your components to share information with each other. You might to rely on that information to control their execution, share progress in the UI, trigger a sequence of operations, etc.
-
-By design, the :class:`~lightning_app.core.flow.LightningFlow` communicates to all :class:`~lightning_app.core.flow.LightningWork` within the application, but :class:`~lightning_app.core.flow.LightningWork` can't communicate between each other directly, they need the flow as a proxy to do so.
-
-Once a ``LightningWork`` is running, any updates to its state is automatically communicated to the flow as a delta (using `DeepDiff `_). The state communication isn't bi-directional, it is only done from work to flow.
-
-Internally, the Lightning App is alternatively collecting deltas sent from all the registered ``LightningWorks`` and/or UI, and running the root flow run method of the app.
-
-*******************************
-Communication From Work to Flow
-*******************************
-
-Below, find an example to better understand this behavior.
-
-The ``WorkCounter`` increments a counter until 1 million and the ``Flow`` prints the work counter.
-
-As the work is running into its own process, its state changes is sent to the Flow which contains the latest value of the counter.
-
-.. code-block:: python
-
- import lightning_app as la
-
-
- class WorkCounter(lapp.LightningWork):
- def __init__(self):
- super().__init__(parallel=True)
- self.counter = 0
-
- def run(self):
- for _ in range(int(10e6)):
- self.counter += 1
-
-
- class Flow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.w = WorkCounter()
-
- def run(self):
- self.w.run()
- print(self.w.counter)
-
-
- app = lapp.LightningApp(Flow())
-
-
-A delta sent from the work to the flow looks like this:
-
-.. code-block:: python
-
- {"values_changed": {"root['works']['w']['vars']['counter']": {"new_value": 425}}}
-
-Here is the associated illustration:
-
-.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/deltas.gif
- :alt: Mechanism showing how delta are sent.
- :width: 100 %
-
-
-*******************************
-Communication From From to Work
-*******************************
-
-Communication from the flow to the work while running isn't support yet. If your application requires this feature, please open an issue on Github.
-
-.. code-block:: python
-
- import lightning_app as la
- from time import sleep
-
-
- class WorkCounter(lapp.LightningWork):
- def __init__(self):
- super().__init__(parallel=True)
- self.counter = 0
-
- def run(self):
- while True:
- sleep(1)
- print(f"Work {self.counter}")
-
-
- class Flow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.w = WorkCounter()
-
- def run(self):
- self.w.run()
- sleep(1)
- print(f"Flow {self.w.counter}")
- self.w.counter += 1
-
-
- app = lapp.LightningApp(Flow())
-
-As you can observe, there is a divergence between the value within the Work and the Flow.
-
-.. code-block:: console
-
- Flow 0
- Flow 1
- Flow 2
- Flow 3
- Work 0
- Flow 4
- Work 0
- Flow 5
- Work 0
- Flow 6
- Work 0
- Flow 7
- Work 0
- Flow 8
- Work 0
- Flow 9
- Work 0
- Flow 10
-
-.. note:: Technically, the flow and works relies on queues to share data (multiprocessing locally and redis lists in the cloud).
+.. include:: ../../core_api/lightning_app/communication_content.rst
diff --git a/docs/source-app/core_api/lightning_app/communication_content.rst b/docs/source-app/core_api/lightning_app/communication_content.rst
new file mode 100644
index 0000000000..8e251412f3
--- /dev/null
+++ b/docs/source-app/core_api/lightning_app/communication_content.rst
@@ -0,0 +1,160 @@
+
+********************************
+Communication Between Components
+********************************
+
+When creating interactive Lightning Apps (App) with multiple components, you may need your components to share information with each other and rely on that information to control their execution, share progress in the UI, trigger a sequence of operations, etc.
+
+To accomplish that, Lightning components can communicate using the App State. The App State is composed of all attributes defined within each component's **__init__** method e.g anything attached to the component with **self.x = y**.
+
+All attributes of all **LightningWork (Work)** components are accessible in the **LightningFlow (Flow)** components in real-time.
+
+By design, the Flows communicate to all **Works** within the application. However, Works can't communicate with each other directly, they must use Flows as a proxy to communicate.
+
+Once a Work is running, any updates to the Work's state is automatically communicated to the Flow, as a delta (using `DeepDiff `_). The state communication isn't bi-directional, communication is only done from Work to Flow.
+
+Internally, the App is alternatively collecting deltas sent from all the registered Works and/or UI, and running the root Flow run method of the App.
+
+----
+
+*************************************************
+Communication from LightningWork to LightningFlow
+*************************************************
+
+LightningFlow (Flow) can access their children's LightningWork (Work) state.
+
+When a running Work attribute gets updated inside its method (separate process locally or remote machine), the app re-executes Flow's run method once it receives the state update from the Work.
+
+Here's an example to better understand communication from Work to Flow.
+
+The ``WorkCounter`` increments a counter until 1 million and the ``Flow`` prints the work counter.
+
+As the Work is running its own process, its state changes are sent to the Flow which contains the latest value of the counter.
+
+.. code-block:: python
+
+ import lightning as L
+
+
+ class WorkCounter(L.LightningWork):
+ def __init__(self):
+ super().__init__(parallel=True)
+ self.counter = 0
+
+ def run(self):
+ for _ in range(int(10e6)):
+ self.counter += 1
+
+
+ class Flow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.w = WorkCounter()
+
+ def run(self):
+ self.w.run()
+ print(self.w.counter)
+
+
+ app = L.LightningApp(Flow())
+
+
+A delta sent from the Work to the Flow looks like this:
+
+.. code-block:: python
+
+ {"values_changed": {"root['works']['w']['vars']['counter']": {"new_value": 425}}}
+
+Here is the associated illustration:
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/deltas.gif
+ :alt: Mechanism showing how delta are sent.
+ :width: 100 %
+
+Here's another example that is slightly different. Here we define a Flow and Work, where the Work increments a counter indefinitely and the Flow prints its state which contain the Work.
+
+You can easily check the state of your entire app as follows:
+
+.. literalinclude:: ../../core_api/lightning_app/app.py
+
+Run the app with:
+
+.. code-block:: bash
+
+ lightning run app docs/source-app/core_api/lightning_app/app.py
+
+And here's the output you get when running the App using the **Lightning CLI**:
+
+.. code-block:: console
+
+ INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+ State: {'works': {'w': {'vars': {'counter': 1}}}}
+ State: {'works': {'w': {'vars': {'counter': 2}}}}
+ State: {'works': {'w': {'vars': {'counter': 3}}}}
+ State: {'works': {'w': {'vars': {'counter': 3}}}}
+ State: {'works': {'w': {'vars': {'counter': 4}}}}
+ ...
+
+----
+
+*************************************************
+Communication from LightningFlow to LightningWork
+*************************************************
+
+Communication from the LightningFlow (Flow) to the LightningWork (Work) while running **isn't supported yet**. If your application requires this feature, please open an issue on Github.
+
+Here's an example of what would happen if you try to have the Flow communicate with the Work:
+
+.. code-block:: python
+
+ import lightning as L
+ from time import sleep
+
+
+ class WorkCounter(L.LightningWork):
+ def __init__(self):
+ super().__init__(parallel=True)
+ self.counter = 0
+
+ def run(self):
+ while True:
+ sleep(1)
+ print(f"Work {self.counter}")
+
+
+ class Flow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.w = WorkCounter()
+
+ def run(self):
+ self.w.run()
+ sleep(1)
+ print(f"Flow {self.w.counter}")
+ self.w.counter += 1
+
+
+ app = L.LightningApp(Flow())
+
+As you can see, there is a divergence between the values within the Work and the Flow.
+
+.. code-block:: console
+
+ Flow 0
+ Flow 1
+ Flow 2
+ Flow 3
+ Work 0
+ Flow 4
+ Work 0
+ Flow 5
+ Work 0
+ Flow 6
+ Work 0
+ Flow 7
+ Work 0
+ Flow 8
+ Work 0
+ Flow 9
+ Work 0
+ Flow 10
diff --git a/docs/source-app/core_api/lightning_app/dynamic_work.rst b/docs/source-app/core_api/lightning_app/dynamic_work.rst
index b4ad9d1144..bf202aa590 100644
--- a/docs/source-app/core_api/lightning_app/dynamic_work.rst
+++ b/docs/source-app/core_api/lightning_app/dynamic_work.rst
@@ -1,187 +1,15 @@
:orphan:
-############
-Dynamic Work
-############
+.. _dynamic_work:
-**Audience:** Users who want to learn how to create application which adapts to user demands.
+#####################
+Dynamic LightningWork
+#####################
-**Level:** Intermediate
+**Audience:** Users who want to create applications that adapt to user demands.
+
+**Level:** Advanced
----
-***************************************************
-Why should I care about creating work dynamically ?
-***************************************************
-
-Imagine you want to create a research notebook app for your team, where every member can create multiple `JupyterLab `_.
-
-The Notebook Manager
-^^^^^^^^^^^^^^^^^^^^
-
-In the component below, we are dynamically creating ``JupyterLabWork`` every time as user clicks the ``Create Jupyter Notebook`` button.
-
-To do so, we are iterating over the list of ``jupyter_config_requests`` infinitely.
-
-.. code-block:: python
-
- import lightning_app as la
-
-
- class JupyterLabManager(lapp.LightningFlow):
- """This flow manages the users notebooks running within works."""
-
- def __init__(self):
- super().__init__()
- self.jupyter_works = lapp.structures.Dict()
- self.jupyter_config_requests = []
-
- def run(self):
- for idx, jupyter_config in enumerate(self.jupyter_config_requests):
-
- # The Jupyter Config has this form is:
- # {"use_gpu": False/True, "token": None, "username": ..., "stop": False}
-
- # Step 1: Check if JupyterWork already exists for this username
- username = jupyter_config["username"]
- if username not in self.jupyter_works:
- jupyter_config["ready"] = False
-
- # Set the hardware selected by the user: GPU or CPU.
- cloud_compute = lapp.CloudCompute("gpu" if jupyter_config["use_gpu"] else "cpu-small")
-
- # Step 2: Create new JupyterWork dynamically !
- self.jupyter_works[username] = JupyterLabWork(cloud_compute=cloud_compute)
-
- # Step 3: Run the JupyterWork
- self.jupyter_works[username].run()
-
- # Step 4: Store the notebook token in the associated config.
- # We are using this to know when the notebook is ready
- # and display the stop button on the UI.
- if self.jupyter_works[username].token:
- jupyter_config["token"] = self.jupyter_works[username].token
-
- # Step 5: Stop the work if the user requested it.
- if jupyter_config["stop"]:
- self.jupyter_works[username].stop()
- self.jupyter_config_requests.pop(idx)
-
- def configure_layout(self):
- return StreamlitFrontend(render_fn=render_fn)
-
-
-The StreamLit UI
-^^^^^^^^^^^^^^^^
-
-In the UI below, we receive the **state** of the Jupyter Manager and it can be modified directly from the UI interaction.
-
-.. code-block:: python
-
- def render_fn(state):
- import streamlit as st
-
- # Step 1: Enable users to select their notebooks and create them
- column_1, column_2, column_3 = st.columns(3)
- with column_1:
- create_jupyter = st.button("Create Jupyter Notebook")
- with column_2:
- username = st.text_input("Enter your username", "tchaton")
- assert username
- with column_3:
- use_gpu = st.checkbox("Use GPU")
-
- # Step 2: If a user clicked the button, add an element to the list of configs
- # Note: state.jupyter_config_requests = ... will sent the state update to the component.
- if create_jupyter:
- new_config = [{"use_gpu": use_gpu, "token": None, "username": username, "stop": False}]
- state.jupyter_config_requests = state.jupyter_config_requests + new_config
-
- # Step 3: List of running notebooks.
- for idx, config in enumerate(state.jupyter_config_requests):
- column_1, column_2, column_3 = st.columns(3)
- with column_1:
- if not idx:
- st.write(f"Idx")
- st.write(f"{idx}")
- with column_2:
- if not idx:
- st.write(f"Use GPU")
- st.write(config["use_gpu"])
- with column_3:
- if not idx:
- st.write(f"Stop")
- if config["token"]:
- should_stop = st.button("Stop this notebook")
-
- # Step 4: Change stop if the user clicked the button
- if should_stop:
- config["stop"] = should_stop
- state.jupyter_config_requests = state.jupyter_config_requests
+.. include:: dynamic_work_content.rst
diff --git a/docs/source-app/core_api/lightning_app/dynamic_work_content.rst b/docs/source-app/core_api/lightning_app/dynamic_work_content.rst
new file mode 100644
index 0000000000..d1f76d4b1f
--- /dev/null
+++ b/docs/source-app/core_api/lightning_app/dynamic_work_content.rst
@@ -0,0 +1,202 @@
+***************************************
+What Dynamic LightningWork does for you
+***************************************
+
+Dynamic LightningWork (Work) changes the resources your application uses while the application is running (aka at runtime).
+
+For example, imagine you want to create a research notebook app for your team. You want every member to be able to create multiple `JupyterLab `_.
+
+----
+
+Dynamic Work with Jupyter Notebooks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this example, we are dynamically creating ``JupyterLabWork`` every time a user clicks the **Create Jupyter Notebook** button.
+
+In order to do that, we are iterating over the list of ``jupyter_config_requests`` infinitely.
+
+.. code-block:: python
+
+ import lightning as L
+
+
+ class JupyterLabManager(L.LightningFlow):
+
+ """This flow manages the users notebooks running within works.""""
+
+ def __init__(self):
+ super().__init__()
+ self.jupyter_works = L.structures.Dict()
+ self.jupyter_config_requests = []
+
+ def run(self):
+ for idx, jupyter_config in enumerate(self.jupyter_config_requests):
+
+ # The Jupyter Config has this form is:
+ # {"use_gpu": False/True, "token": None, "username": ..., "stop": False}
+
+ # Step 1: Check if JupyterWork already exists for this username
+ username = jupyter_config["username"]
+ if username not in self.jupyter_works:
+ jupyter_config["ready"] = False
+
+ # Set the hardware selected by the user: GPU or CPU.
+ cloud_compute = L.CloudCompute("gpu" if jupyter_config["use_gpu"] else "cpu-small")
+
+ # Step 2: Create new JupyterWork dynamically !
+ self.jupyter_works[username] = JupyterLabWork(cloud_compute=cloud_compute)
+
+ # Step 3: Run the JupyterWork
+ self.jupyter_works[username].run()
+
+ # Step 4: Store the notebook token in the associated config.
+ # We are using this to know when the notebook is ready
+ # and display the stop button on the UI.
+ if self.jupyter_works[username].token:
+ jupyter_config["token"] = self.jupyter_works[username].token
+
+ # Step 5: Stop the work if the user requested it.
+ if jupyter_config['stop']:
+ self.jupyter_works[username].stop()
+ self.jupyter_config_requests.pop(idx)
+
+ def configure_layout(self):
+ return L.app.frontend.StreamlitFrontend(render_fn=render_fn)
+
+----
+
+Dynamic Works with StreamLit UI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Continuing from the Jupyter Notebook example, in the UI, we receive the **state** of the Jupyter Manager and the state can be modified directly from the UI.
+
+.. code-block:: python
+
+ import streamlit as st
+
+
+ def render_fn(state):
+
+ # Step 1: Enable users to select their notebooks and create them
+ column_1, column_2, column_3 = st.columns(3)
+ with column_1:
+ create_jupyter = st.button("Create Jupyter Notebook")
+ with column_2:
+ username = st.text_input('Enter your username', "tchaton")
+ assert username
+ with column_3:
+ use_gpu = st.checkbox('Use GPU')
+
+ # Step 2: If a user clicked the button, add an element to the list of configs
+ # Note: state.jupyter_config_requests = ... will sent the state update to the component.
+ if create_jupyter:
+ new_config = [{"use_gpu": use_gpu, "token": None, "username": username, "stop": False}]
+ state.jupyter_config_requests = state.jupyter_config_requests + new_config
+
+ # Step 3: List of running notebooks.
+ for idx, config in enumerate(state.jupyter_config_requests):
+ column_1, column_2, column_3 = st.columns(3)
+ with column_1:
+ if not idx:
+ st.write(f"Idx")
+ st.write(f"{idx}")
+ with column_2:
+ if not idx:
+ st.write(f"Use GPU")
+ st.write(config['use_gpu'])
+ with column_3:
+ if not idx:
+ st.write(f"Stop")
+ if config["token"]:
+ should_stop = st.button("Stop this notebook")
+
+ # Step 4: Change stop if the user clicked the button
+ if should_stop:
+ config["stop"] = should_stop
+ state.jupyter_config_requests = state.jupyter_config_requests
diff --git a/docs/source-app/core_api/lightning_app/lightning_app.rst b/docs/source-app/core_api/lightning_app/lightning_app.rst
index 5415f0d9dc..497dde20d2 100644
--- a/docs/source-app/core_api/lightning_app/lightning_app.rst
+++ b/docs/source-app/core_api/lightning_app/lightning_app.rst
@@ -7,7 +7,6 @@ LightningApp
############
-The :class:`~lightning_app.core.app.LightningApp` runs a tree of one or more components that interact to create end-to-end applications. There are two kinds of components: :class:`~lightning_app.core.flow.LightningFlow` and :class:`~lightning_app.core.work.LightningWork`. This modular design enables you to reuse components created by other users.
-
.. autoclass:: lightning_app.core.app.LightningApp
+ :exclude-members: _run, connect, get_component_by_name, maybe_apply_changes, set_state
:noindex:
diff --git a/docs/source-app/core_api/lightning_flow.rst b/docs/source-app/core_api/lightning_flow.rst
index 6776bfefcb..a6ee8b2eca 100644
--- a/docs/source-app/core_api/lightning_flow.rst
+++ b/docs/source-app/core_api/lightning_flow.rst
@@ -4,8 +4,5 @@
LightningFlow
#############
-The :class:`~lightning_app.core.flow.LightningFlow` component coordinates long-running tasks :class:`~lightning_app.core.work.LightningWork` and runs its children :class:`~lightning_app.core.flow.LightningFlow` components.
-
-
.. autoclass:: lightning_app.core.flow.LightningFlow
- :noindex:
+ :exclude-members: _attach_backend, _exit, _is_state_attribute, set_state
diff --git a/docs/source-app/core_api/lightning_work/compute.rst b/docs/source-app/core_api/lightning_work/compute.rst
index f41ca08380..89313c4878 100644
--- a/docs/source-app/core_api/lightning_work/compute.rst
+++ b/docs/source-app/core_api/lightning_work/compute.rst
@@ -8,103 +8,8 @@ Customize your Cloud Compute
**Audience:** Users who want to select the hardware to run in the cloud.
-**Level:** Basic
+**Level:** Intermediate
----
-***************************************
-How can I customize my Work resources ?
-***************************************
-
-In the cloud, you can simply configure which machine to run on by passing
-a :class:`~lightning_app.utilities.packaging.cloud_compute.CloudCompute` to your work ``__init__`` method:
-
-.. code-block:: python
-
- import lightning_app as la
-
- # Run on a free, shared CPU machine. This is the default for every LightningWork.
- MyCustomWork(cloud_compute=lapp.CloudCompute())
-
- # Run on a dedicated, medium-size CPU machine (see specs below)
- MyCustomWork(cloud_compute=lapp.CloudCompute("cpu-medium"))
-
- # Run on cheap GPU machine with a single GPU (see specs below)
- MyCustomWork(cloud_compute=lapp.CloudCompute("gpu"))
-
- # Run on a fast multi-GPU machine (see specs below)
- MyCustomWork(cloud_compute=lapp.CloudCompute("gpu-fast-multi"))
-
-
-Here is the full list of supported machine names:
-
-.. list-table:: Hardware by Accelerator Type
- :widths: 25 25 25 25
- :header-rows: 1
-
- * - Name
- - # of CPUs
- - GPUs
- - Memory
- * - default
- - 2
- - 0
- - 3 GB
- * - cpu-small
- - 2
- - 0
- - 8 GB
- * - cpu-medium
- - 8
- - 0
- - 32 GB
- * - gpu
- - 4
- - 1 (T4, 16 GB)
- - 16 GB
- * - gpu-fast
- - 8
- - 1 (V100, 16 GB)
- - 61 GB
- * - gpu-fast-multi
- - 32
- - 4 (V100 16 GB)
- - 244 GB
-
-The up-to-date prices for these instances can be found `here `_.
-
-
-*******************************************
-How can I run on spot/preemptible machine ?
-*******************************************
-
-Most cloud provider offers ``preemptible`` (synonym of ``spot``) machine which are usually discounted up to 90 %. Those machines are cheaper but the cloud provider can retrieve them at any time.
-
-.. code-block:: python
-
- import lightning_app as la
-
- # Run on a single CPU
- MyCustomWork(cloud_compute=lapp.CloudCompute("gpu", preemptible=True))
-
-
-***********************************
-How can I stop my work when idle ?
-***********************************
-
-By providing **idle_timeout=X Seconds**, the work is automatically stopped **X seconds** after doing nothing.
-
-.. code-block:: python
-
- import lightning_app as la
-
- # Run on a single CPU and turn down immediately when idle.
- MyCustomWork(cloud_compute=lapp.CloudCompute("gpu", idle_timeout=0))
-
-
-#############
-CloudCompute
-#############
-
-.. autoclass:: lightning_app.utilities.packaging.cloud_compute.CloudCompute
- :noindex:
+.. include:: compute_content.rst
diff --git a/docs/source-app/core_api/lightning_work/compute_content.rst b/docs/source-app/core_api/lightning_work/compute_content.rst
new file mode 100644
index 0000000000..68853c949e
--- /dev/null
+++ b/docs/source-app/core_api/lightning_work/compute_content.rst
@@ -0,0 +1,100 @@
+
+***************************
+Customize my Work resources
+***************************
+
+In the cloud, you can simply configure which machine to run on by passing
+a :class:`~lightning_app.utilities.packaging.cloud_compute.CloudCompute` to your work ``__init__`` method:
+
+.. code-block:: python
+
+ import lightning as L
+
+ # Run on a free, shared CPU machine. This is the default for every LightningWork.
+ MyCustomWork(cloud_compute=L.CloudCompute())
+
+ # Run on a dedicated, medium-size CPU machine (see specs below)
+ MyCustomWork(cloud_compute=L.CloudCompute("cpu-medium"))
+
+ # Run on cheap GPU machine with a single GPU (see specs below)
+ MyCustomWork(cloud_compute=L.CloudCompute("gpu"))
+
+ # Run on a fast multi-GPU machine (see specs below)
+ MyCustomWork(cloud_compute=L.CloudCompute("gpu-fast-multi"))
+
+
+Here is the full list of supported machine names:
+
+.. list-table:: Hardware by Accelerator Type
+ :widths: 25 25 25 25
+ :header-rows: 1
+
+ * - Name
+ - # of CPUs
+ - GPUs
+ - Memory
+ * - default
+ - 2
+ - 0
+ - 3 GB
+ * - cpu-small
+ - 2
+ - 0
+ - 8 GB
+ * - cpu-medium
+ - 8
+ - 0
+ - 32 GB
+ * - gpu
+ - 4
+ - 1 (T4, 16 GB)
+ - 16 GB
+ * - gpu-fast
+ - 8
+ - 1 (V100, 16 GB)
+ - 61 GB
+ * - gpu-fast-multi
+ - 32
+ - 4 (V100 16 GB)
+ - 244 GB
+
+The up-to-date prices for these instances can be found `here `_.
+
+----
+
+*******************************
+Run on spot/preemptible machine
+*******************************
+
+Most cloud provider offers ``preemptible`` (synonym of ``spot``) machines that are usually discounted by up to 90 %. Those machines are cheaper but the cloud provider can retrieve them at any time and might take longer to be ready.
+
+.. code-block:: python
+
+ import lightning as L
+
+ # Run on a single CPU
+ MyCustomWork(cloud_compute=L.CloudCompute("gpu", preemptible=True))
+
+----
+
+**********************
+Stop my work when idle
+**********************
+
+By providing **idle_timeout=X Seconds**, the work is automatically stopped **X seconds** after doing nothing.
+
+.. code-block:: python
+
+ import lightning as L
+
+ # Run on a single CPU and turn down immediately when idle.
+ MyCustomWork(cloud_compute=L.CloudCompute("gpu", idle_timeout=0))
+
+----
+
+************
+CloudCompute
+************
+
+.. autoclass:: lightning_app.utilities.packaging.cloud_compute.CloudCompute
+ :noindex:
diff --git a/docs/source-app/core_api/lightning_work/handling_app_exception.rst b/docs/source-app/core_api/lightning_work/handling_app_exception.rst
index 60f432e817..20c9b618d9 100644
--- a/docs/source-app/core_api/lightning_work/handling_app_exception.rst
+++ b/docs/source-app/core_api/lightning_work/handling_app_exception.rst
@@ -1,83 +1,13 @@
:orphan:
-########################
-Handling App Exceptions
-########################
+###############################
+Handle Lightning App exceptions
+###############################
-**Audience:** Users who want to know how to implement app where errors are handled.
+**Audience:** Users who want to make Lightning Apps more robust to potential issues.
**Level:** Advanced
----
-*************************************************
-Why should I care about handling app exceptions ?
-*************************************************
-
-Imagine you are creating an application where your team can launch model training by providing their own Github Repo any time they want.
-
-As the application admin, you don't want the application to go down if their code has a bug and breaks.
-
-Instead, you would like the work to capture the exception and surface this to the users on failures.
-
-****************************************
-How can I configure exception handling ?
-****************************************
-
-
-The LightningWork accepts an argument **raise_exception** which is **True** by default. This aligns with Python default behaviors.
-
-However, for the user case stated above, we want to capture the work exceptions. This is done by providing ``raise_exception=False`` to the work ``__init__`` method.
-
-.. code-block:: python
-
- MyCustomWork(raise_exception=False) # <== HERE: The exception is captured.
-
- # Default behavior
- MyCustomWork(raise_exception=True) # <== HERE: The exception is raised within the flow and terminates the app
-
-
-And you can customize this behavior by overriding the ``on_exception`` hook to the Lightning Work.
-
-.. code-block:: python
-
- import lightning as L
-
-
- class MyCustomWork(L.LightningWork):
- def on_exception(self, exception: Exception):
- # do something when an exception is triggered.
- pass
-
-
-*******************
-Application Example
-*******************
-
-This is the pseudo-code for the application described above.
-
-.. code-block:: python
-
- import lightning_app as lapp
-
-
- class RootFlow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.user_jobs = lapp.structures.Dict()
- self.requested_jobs = []
-
- def run(self):
- for request in self.requested_jobs:
- job_id = request["id"]
- if job_id not in self.user_jobs:
- # Note: The `GithubRepoLauncher` doesn't exist yet.
- self.user_jobs[job_id] = GithubRepoLauncher(
- **request,
- raise_exception=False, # <== HERE: The exception is captured.
- )
- self.user_jobs[job_id].run()
-
- if self.user_jobs[job_id].status.stage == "failed" and "printed" not in request:
- print(self.user_jobs[job_id].status) # <== HERE: Print the user exception.
- request["printed"] = True
+.. include:: handling_app_exception_content.rst
diff --git a/docs/source-app/core_api/lightning_work/handling_app_exception_content.rst b/docs/source-app/core_api/lightning_work/handling_app_exception_content.rst
new file mode 100644
index 0000000000..4840cf5fdf
--- /dev/null
+++ b/docs/source-app/core_api/lightning_work/handling_app_exception_content.rst
@@ -0,0 +1,74 @@
+
+***************************************************
+What handling Lightning App exceptions does for you
+***************************************************
+
+Imagine you are creating a Lightning App (App) where your team can launch model training by providing their own Github Repo any time they want.
+
+As the App admin, you don't want the App to go down if their code has a bug and breaks.
+
+Instead, you would like the LightningWork (Work) to capture the exception and present the issue to users.
+
+----
+
+****************************
+Configure exception handling
+****************************
+
+The LightningWork (Work) accepts an argument **raise_exception** which is **True** by default. This aligns with Python default behaviors.
+
+However, for the user case stated in the previous section, we want to capture the Work exceptions. This is done by providing ``raise_exception=False`` to the work ``__init__`` method.
+
+.. code-block:: python
+
+ import lightning as L
+
+ MyCustomWork(raise_exception=False) # <== HERE: The exception is captured.
+
+ # Default behavior
+ MyCustomWork(raise_exception=True) # <== HERE: The exception is raised within the flow and terminates the app
+
+
+And you can customize this behavior by overriding the ``on_exception`` hook to the Work.
+
+.. code-block:: python
+
+ import lightning as L
+
+ class MyCustomWork(L.LightningWork):
+
+ def on_exception(self, exception: Exception):
+ # do something when an exception is triggered.
+
+----
+
+**************************
+Exception handling example
+**************************
+
+This is the pseudo-code for the application described above.
+
+.. code-block:: python
+
+ import lightning as L
+
+ class RootFlow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.user_jobs = L.structures.Dict()
+ self.requested_jobs = []
+
+ def run(self):
+ for request in self.requested_jobs:
+ job_id = request["id"]
+ if job_id not in self.user_jobs:
+ # Note: The `GithubRepoLauncher` doesn't exist yet.
+ self.user_jobs[job_id] = GithubRepoLauncher(
+ **request,
+ raise_exception=False, # <== HERE: The exception is captured.
+ )
+ self.user_jobs[job_id].run()
+
+ if self.user_jobs[job_id].status.stage == "failed" and "printed" not in request:
+ print(self.user_jobs[job_id].status) # <== HERE: Print the user exception.
+ request["printed"] = True
diff --git a/docs/source-app/core_api/lightning_work/lightning_work.rst b/docs/source-app/core_api/lightning_work/lightning_work.rst
index 8a1d3593d6..f4f490dd1f 100644
--- a/docs/source-app/core_api/lightning_work/lightning_work.rst
+++ b/docs/source-app/core_api/lightning_work/lightning_work.rst
@@ -6,7 +6,6 @@
LightningWork
#############
-The :class:`~lightning_app.core.work.LightningWork` component is a building block optimized for long-running jobs or integrating third-party services. LightningWork can be used for training large models, downloading a dataset, or any long-lasting operation.
-
.. autoclass:: lightning_app.core.work.LightningWork
+ :exclude-members: _aggregate_status_timeout, _is_state_attribute, _is_state_attribute, set_state
:noindex:
diff --git a/docs/source-app/core_api/lightning_work/payload.rst b/docs/source-app/core_api/lightning_work/payload.rst
index 5d6ab1f20d..b23bf7ca32 100644
--- a/docs/source-app/core_api/lightning_work/payload.rst
+++ b/docs/source-app/core_api/lightning_work/payload.rst
@@ -1,87 +1,15 @@
:orphan:
-#############################
-Sharing Objects between Works
-#############################
+######################################
+Sharing Objects between LightningWorks
+######################################
-**Audience:** Users who want to know how to transfer python objects between their works.
+**Audience:** Users who want to know how to transfer Python objects between their LightningWorks.
**Level:** Advanced
-**Prerequisite**: Know about the pandas library and read the :ref:`access_app_state` guide.
+**Prerequisite**: Reach Level 16+, know about the `pandas DataFrames `_ and read and read the `Access app state guide <../../access_app_state.html>`_.
----
-************************************
-When do I need to transfer objects ?
-************************************
-
-Imagine your application is processing some data using `pandas DaFrame `_ and you want to pass those data to another work. This is when and what the **Payload API** is meant for.
-
-
-*************************************
-How can I use the Lightning Payload ?
-*************************************
-
-The Payload enables non JSON-serializable attribute objects to be part of your work state and be communicated to other works.
-
-Here is an example how to use it:
-
-.. code-block:: python
-
- import lightning_app as la
- import pandas as pd
-
-
- class SourceWork(lapp.LightningWork):
- def __init__(self):
- super().__init__()
- self.df = None
-
- def run(self):
- # do some processing
-
- df = pd.DataFrame(data={"col1": [1, 2], "col2": [3, 4]})
-
- # The object you care about needs to be wrapped into a Payload object.
- self.df = lapp.storage.Payload(df)
-
- # You can access the original object from the payload using its value property.
- print("src", self.df.value)
- # src col1 col2
- # 0 1 3
- # 1 2 4
-
-Once the Payload object is attached to your work state, it can be passed to another work via the flow as follows:
-
-.. code-block:: python
-
- import lightning_app as la
- import pandas as pd
-
-
- class DestinationWork(lapp.LightningWork):
- def run(self, df: lapp.storage.Payload):
- # You can access the original object from the payload using its value property.
- print("dst", df.value)
- # dst col1 col2
- # 0 1 3
- # 1 2 4
-
-
- class Flow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.src = SourceWork()
- self.dst = DestinationWork()
-
- def run(self):
- self.src.run()
- # The pandas DataFrame created by the ``SourceWork``
- # is passed to the ``DestinationWork``.
- # Internally, Lightning pickles and un-pickle the python object,
- # so you receive a copy of the original object.
- self.dst.run(df=self.src.df)
-
-
- app = lapp.LightningApp(Flow())
+.. include:: payload_content.rst
diff --git a/docs/source-app/core_api/lightning_work/payload_content.rst b/docs/source-app/core_api/lightning_work/payload_content.rst
new file mode 100644
index 0000000000..780f3985e3
--- /dev/null
+++ b/docs/source-app/core_api/lightning_work/payload_content.rst
@@ -0,0 +1,75 @@
+
+**************************************
+What transferring objects does for you
+**************************************
+
+Imagine your application is processing some data using `pandas DaFrame `_ and you want to pass that data to another LightningWork (Work). This is what the **Payload API** is meant for.
+
+----
+
+*************************
+Use the Lightning Payload
+*************************
+
+The Payload enables non JSON-serializable attribute objects to be part of your Work's state and to be communicated to other Works.
+
+Here is an example:
+
+.. code-block:: python
+
+ import lightning as L
+ import pandas as pd
+
+
+ class SourceWork(L.LightningWork):
+ def __init__(self):
+ super().__init__()
+ self.df = None
+
+ def run(self):
+ # do some processing
+
+ df = pd.DataFrame(data={"col1": [1, 2], "col2": [3, 4]})
+
+ # The object you care about needs to be wrapped into a Payload object.
+ self.df = L.storage.Payload(df)
+
+ # You can access the original object from the payload using its value property.
+ print("src", self.df.value)
+ # src col1 col2
+ # 0 1 3
+ # 1 2 4
+
+Once the Payload object is attached to your Work's state, it can be passed to another work using the LightningFlow (Flow) as follows:
+
+.. code-block:: python
+
+ import lightning as L
+ import pandas as pd
+
+
+ class DestinationWork(L.LightningWork):
+ def run(self, df: L.storage.Payload):
+ # You can access the original object from the payload using its value property.
+ print("dst", df.value)
+ # dst col1 col2
+ # 0 1 3
+ # 1 2 4
+
+
+ class Flow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.src = SourceWork()
+ self.dst = DestinationWork()
+
+ def run(self):
+ self.src.run()
+ # The pandas DataFrame created by the ``SourceWork``
+ # is passed to the ``DestinationWork``.
+ # Internally, Lightning pickles and un-pickle the python object,
+ # so you receive a copy of the original object.
+ self.dst.run(df=self.src.df)
+
+
+ app = L.LightningApp(Flow())
diff --git a/docs/source-app/core_api/lightning_work/status.rst b/docs/source-app/core_api/lightning_work/status.rst
index ff7322b6c9..af3a27ac40 100644
--- a/docs/source-app/core_api/lightning_work/status.rst
+++ b/docs/source-app/core_api/lightning_work/status.rst
@@ -1,9 +1,8 @@
:orphan:
-
-#####################
-Lightning Work Status
-#####################
+####################
+LightningWork Status
+####################
**Audience:** Users who want to understand ``LightningWork`` under the hood.
@@ -11,199 +10,4 @@ Lightning Work Status
----
-*******************
-What are statuses ?
-*******************
-
-Statuses indicates transition points in the life of a Lightning Work and contain metadata.
-
-The different stages are:
-
-.. code-block:: python
-
- class WorkStageStatus:
- NOT_STARTED = "not_started"
- STOPPED = "stopped"
- PENDING = "pending"
- RUNNING = "running"
- SUCCEEDED = "succeeded"
- FAILED = "failed"
-
-And a single status is as follows:
-
-.. code-block:: python
-
- @dataclass
- class WorkStatus:
- stage: WorkStageStatus
- timestamp: float
- reason: Optional[str] = None
- message: Optional[str] = None
- count: int = 1
-
-
-On creation, the work's status flags all evaluate to ``False`` (in particular ``has_started``) and when calling ``work.run`` in your flow,
-the work transition from ``is_pending`` to ``is_running`` and then to ``has_succeeded`` if everything when well or ``has_failed`` otherwise.
-
-.. code-block:: python
-
- from time import sleep
- import lightning_app as la
-
-
- class Work(lapp.LightningWork):
- def run(self, value: int):
- sleep(1)
- if value == 0:
- return
- raise Exception(f"The provided value was {value}")
-
-
- class Flow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.work = Work(raise_exception=False)
- self.counter = 0
-
- def run(self):
- if not self.work.has_started:
- print("NOT STARTED")
-
- elif self.work.is_pending:
- print("PENDING")
-
- elif self.work.is_running:
- print("RUNNING")
-
- elif self.work.has_succeeded:
- print("SUCCESS")
-
- elif self.work.has_failed:
- print("FAILED")
-
- elif self.work.has_stopped:
- print("STOPPED")
- self._exit()
-
- print(self.work.status)
- self.work.run(self.counter)
- self.counter += 1
-
-
- app = lapp.LightningApp(Flow())
-
-Run this app as follows:
-
-.. code-block:: bash
-
- lightning run app test.py > app_log.txt
-
-And here is the expected output inside ``app_log.txt`` and as expected,
-we are observing the following transition ``has_started``, ``is_pending``, ``is_running``, ``has_succeeded``, ``is_running`` and ``has_failed``
-
-.. code-block:: console
-
- NOT STARTED
- WorkStatus(stage='not_started', timestamp=1653498225.18468, reason=None, message=None, count=1)
- PENDING
- WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
- PENDING
- WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
- PENDING
- ...
- PENDING
- WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
- PENDING
- WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
- RUNNING
- WorkStatus(stage='running', timestamp=1653498228.825194, reason=None, message=None, count=1)
- ...
- SUCCESS
- WorkStatus(stage='succeeded', timestamp=1653498229.831793, reason=None, message=None, count=1)
- SUCCESS
- WorkStatus(stage='succeeded', timestamp=1653498229.831793, reason=None, message=None, count=1)
- SUCCESS
- WorkStatus(stage='succeeded', timestamp=1653498229.831793, reason=None, message=None, count=1)
- RUNNING
- WorkStatus(stage='running', timestamp=1653498229.846451, reason=None, message=None, count=1)
- RUNNING
- ...
- WorkStatus(stage='running', timestamp=1653498229.846451, reason=None, message=None, count=1)
- RUNNING
- WorkStatus(stage='running', timestamp=1653498229.846451, reason=None, message=None, count=1)
- FAILED
- WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
- FAILED
- WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
- FAILED
- WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
- FAILED
- WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
- ...
-
-In order to access all statuses, simply do:
-
-.. code-block:: python
-
- from time import sleep
- import lightning_app as la
-
-
- class Work(lapp.LightningWork):
- def run(self, value: int):
- sleep(1)
- if value == 0:
- return
- raise Exception(f"The provided value was {value}")
-
-
- class Flow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.work = Work(raise_exception=False)
- self.counter = 0
-
- def run(self):
- print(self.statuses)
- self.work.run(self.counter)
- self.counter += 1
-
-
- app = lapp.LightningApp(Flow())
-
-
-Run this app as follows:
-
-.. code-block:: bash
-
- lightning run app test.py > app_log.txt
-
-And here is the expected output inside ``app_log.txt``:
-
-
-.. code-block:: console
-
- # First execution with value = 0
-
- []
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1)]
- ...
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
- ...
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1), WorkStatus(stage='succeeded', timestamp=1653498627.191053, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1), WorkStatus(stage='succeeded', timestamp=1653498627.191053, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1), WorkStatus(stage='succeeded', timestamp=1653498627.191053, reason=None, message=None, count=1)]
-
- # Second execution with value = 1
-
- [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1)]
- ...
- [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1)]
- [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='failed', timestamp=1653498628.210164, reason='user_exception', message='The provided value was 1', count=1)]
- [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='failed', timestamp=1653498628.210164, reason='user_exception', message='The provided value was 1', count=1)]
+.. include:: status_content.rst
diff --git a/docs/source-app/core_api/lightning_work/status_content.rst b/docs/source-app/core_api/lightning_work/status_content.rst
new file mode 100644
index 0000000000..7ee8b65ac8
--- /dev/null
+++ b/docs/source-app/core_api/lightning_work/status_content.rst
@@ -0,0 +1,197 @@
+
+*************************************
+Everything about LightningWork Status
+*************************************
+
+Statuses indicate transition points in the life of a LightningWork (Work) and contain metadata.
+
+The different stages are:
+
+.. code-block:: python
+
+ class WorkStageStatus:
+ NOT_STARTED = "not_started"
+ STOPPED = "stopped"
+ PENDING = "pending"
+ RUNNING = "running"
+ SUCCEEDED = "succeeded"
+ FAILED = "failed"
+
+And a single status is as follows:
+
+.. code-block:: python
+
+ @dataclass
+ class WorkStatus:
+ stage: WorkStageStatus
+ timestamp: float
+ reason: Optional[str] = None
+ message: Optional[str] = None
+ count: int = 1
+
+
+On creation, the Work's status flags all evaluate to ``False`` (in particular ``has_started``) and when calling ``work.run`` in your Lightning Flow (Flow),
+the Work transitions from ``is_pending`` to ``is_running`` and then to ``has_succeeded`` if everything went well or ``has_failed`` otherwise.
+
+.. code-block:: python
+
+ from time import sleep
+ import lightning as L
+
+
+ class Work(L.LightningWork):
+ def run(self, value: int):
+ sleep(1)
+ if value == 0:
+ return
+ raise Exception(f"The provided value was {value}")
+
+
+ class Flow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.work = Work(raise_exception=False)
+ self.counter = 0
+
+ def run(self):
+ if not self.work.has_started:
+ print("NOT STARTED")
+
+ elif self.work.is_pending:
+ print("PENDING")
+
+ elif self.work.is_running:
+ print("RUNNING")
+
+ elif self.work.has_succeeded:
+ print("SUCCESS")
+
+ elif self.work.has_failed:
+ print("FAILED")
+
+ elif self.work.has_stopped:
+ print("STOPPED")
+ self._exit()
+
+ print(self.work.status)
+ self.work.run(self.counter)
+ self.counter += 1
+
+
+ app = L.LightningApp(Flow())
+
+Run this app as follows:
+
+.. code-block:: bash
+
+ lightning run app test.py > app_log.txt
+
+And here is the expected output inside ``app_log.txt`` and as expected,
+we are observing the following transition ``has_started``, ``is_pending``, ``is_running``, ``has_succeeded``, ``is_running`` and ``has_failed``
+
+.. code-block:: console
+
+ NOT STARTED
+ WorkStatus(stage='not_started', timestamp=1653498225.18468, reason=None, message=None, count=1)
+ PENDING
+ WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
+ PENDING
+ WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
+ PENDING
+ ...
+ PENDING
+ WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
+ PENDING
+ WorkStatus(stage='pending', timestamp=1653498225.217413, reason=None, message=None, count=1)
+ RUNNING
+ WorkStatus(stage='running', timestamp=1653498228.825194, reason=None, message=None, count=1)
+ ...
+ SUCCESS
+ WorkStatus(stage='succeeded', timestamp=1653498229.831793, reason=None, message=None, count=1)
+ SUCCESS
+ WorkStatus(stage='succeeded', timestamp=1653498229.831793, reason=None, message=None, count=1)
+ SUCCESS
+ WorkStatus(stage='succeeded', timestamp=1653498229.831793, reason=None, message=None, count=1)
+ RUNNING
+ WorkStatus(stage='running', timestamp=1653498229.846451, reason=None, message=None, count=1)
+ RUNNING
+ ...
+ WorkStatus(stage='running', timestamp=1653498229.846451, reason=None, message=None, count=1)
+ RUNNING
+ WorkStatus(stage='running', timestamp=1653498229.846451, reason=None, message=None, count=1)
+ FAILED
+ WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
+ FAILED
+ WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
+ FAILED
+ WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
+ FAILED
+ WorkStatus(stage='failed', timestamp=1653498230.852565, reason='user_exception', message='The provided value was 1', count=1)
+ ...
+
+In order to access all statuses:
+
+.. code-block:: python
+
+ from time import sleep
+ import lightning as L
+
+
+ class Work(L.LightningWork):
+ def run(self, value: int):
+ sleep(1)
+ if value == 0:
+ return
+ raise Exception(f"The provided value was {value}")
+
+
+ class Flow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.work = Work(raise_exception=False)
+ self.counter = 0
+
+ def run(self):
+ print(self.statuses)
+ self.work.run(self.counter)
+ self.counter += 1
+
+
+ app = L.LightningApp(Flow())
+
+
+Run this app as follows:
+
+.. code-block:: bash
+
+ lightning run app test.py > app_log.txt
+
+And here is the expected output inside ``app_log.txt``:
+
+
+.. code-block:: console
+
+ # First execution with value = 0
+
+ []
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1)]
+ ...
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
+ ...
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1), WorkStatus(stage='succeeded', timestamp=1653498627.191053, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1), WorkStatus(stage='succeeded', timestamp=1653498627.191053, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498622.252016, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498626.185683, reason=None, message=None, count=1), WorkStatus(stage='succeeded', timestamp=1653498627.191053, reason=None, message=None, count=1)]
+
+ # Second execution with value = 1
+
+ [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1)]
+ ...
+ [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='failed', timestamp=1653498628.210164, reason='user_exception', message='The provided value was 1', count=1)]
+ [WorkStatus(stage='pending', timestamp=1653498627.204636, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='running', timestamp=1653498627.205509, reason=None, message=None, count=1), WorkStatus(stage='failed', timestamp=1653498628.210164, reason='user_exception', message='The provided value was 1', count=1)]
diff --git a/docs/source-app/examples/dag/dag.rst b/docs/source-app/examples/dag/dag.rst
index f9b304b736..8b1d71dd24 100644
--- a/docs/source-app/examples/dag/dag.rst
+++ b/docs/source-app/examples/dag/dag.rst
@@ -2,6 +2,8 @@
Build a Directed Acyclic Graph (DAG)
####################################
+.. _dag_example:
+
**Audience:** Users coming from MLOps to Lightning Apps, looking for more flexibility.
A typical ML training workflow can be implemented with a simple DAG.
@@ -10,10 +12,10 @@ Below is a pseudo-code using the lightning framework that uses a LightningFlow t
.. code-block:: python
- import lightning_app as la
+ import lightning as L
+ class DAGFlow(L.LightningFlow):
- class DAGFlow(lapp.LightningFlow):
def __init__(self):
super().__init__()
self.processor = DataProcessorWork(...)
@@ -29,21 +31,19 @@ Below is a pseudo-code to run several works in parallel using a built-in :class:
.. code-block:: python
- import lightning_app as la
+ import lightning as L
+ class DAGFlow(L.LightningFlow):
- class DAGFlow(lapp.LightningFlow):
def __init__(self):
super().__init__()
...
- self.train_works = lapp.structures.Dict(
- **{
- "1": TrainingWork(..., parallel=True),
- "2": TrainingWork(..., parallel=True),
- "3": TrainingWork(..., parallel=True),
- # ...
- }
- )
+ self.train_works = L.structures.Dict(**{
+ "1": TrainingWork(..., parallel=True),
+ "2": TrainingWork(..., parallel=True),
+ "3": TrainingWork(..., parallel=True),
+ ...
+ })
...
def run(self):
@@ -59,13 +59,12 @@ Below is a pseudo-code to run several works in parallel using a built-in :class:
self.serve_work.run(...)
+----
**********
-Next steps
+Next Steps
**********
-Depending on your use case, you might want to check one of these out next.
-
.. raw:: html
diff --git a/docs/source-app/examples/dag/dag_from_scratch.rst b/docs/source-app/examples/dag/dag_from_scratch.rst
index 7c68c8ea87..cde4695332 100644
--- a/docs/source-app/examples/dag/dag_from_scratch.rst
+++ b/docs/source-app/examples/dag/dag_from_scratch.rst
@@ -15,7 +15,9 @@ In this example, you will learn how to create a simple DAG which:
and learn how to schedule this entire process.
-Find the complete example `here `_.
+Find the complete example `here `_.
+
+----
**************************
Step 1: Implement your DAG
@@ -33,19 +35,20 @@ First, let's define the component we need:
* Processing is responsible to execute a ``processing.py`` script.
* A collection of model work to train all models in parallel.
-.. literalinclude:: ../../../../examples/dag/app.py
+.. literalinclude:: ../../../examples/app_dag/app.py
:lines: 55-79
And its run method executes the steps described above.
Additionally, ``work.stop`` is used to reduce cost when running in the cloud.
-.. literalinclude:: ../../../../examples/dag/app.py
+.. literalinclude:: ../../../examples/app_dag/app.py
:lines: 81-108
+----
*****************************
Step 2: Define the scheduling
*****************************
-.. literalinclude:: ../../../../examples/dag/app.py
+.. literalinclude:: ../../../examples/app_dag/app.py
:lines: 109-137
diff --git a/docs/source-app/examples/data_explore_app.rst b/docs/source-app/examples/data_explore_app.rst
index f66b3c2cb1..cd7011a10e 100644
--- a/docs/source-app/examples/data_explore_app.rst
+++ b/docs/source-app/examples/data_explore_app.rst
@@ -1,3 +1,5 @@
+:orphan:
+
##########################
Build a Data Exploring App
##########################
diff --git a/docs/source-app/examples/etl_app.rst b/docs/source-app/examples/etl_app.rst
index 4cb581e399..5b494e943e 100644
--- a/docs/source-app/examples/etl_app.rst
+++ b/docs/source-app/examples/etl_app.rst
@@ -1,3 +1,5 @@
+:orphan:
+
###############
Build a ETL App
###############
diff --git a/docs/source-app/examples/file_server/app.py b/docs/source-app/examples/file_server/app.py
new file mode 100644
index 0000000000..5de9f3720a
--- /dev/null
+++ b/docs/source-app/examples/file_server/app.py
@@ -0,0 +1,232 @@
+import json
+import os
+import tarfile
+import uuid
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+import lightning as L
+from lightning.app.storage import Drive
+
+
+class FileServer(L.LightningWork):
+ def __init__(self, drive: Drive, base_dir: str = "file_server", chunk_size=10240, **kwargs):
+ """This component uploads, downloads files to your application.
+
+ Arguments:
+ drive: The drive can share data inside your application.
+ base_dir: The local directory where the data will be stored.
+ chunk_size: The quantity of bytes to download/upload at once.
+ """
+ super().__init__(
+ cloud_build_config=L.BuildConfig(["flask, flask-cors"]),
+ parallel=True,
+ **kwargs,
+ )
+ # 1: Attach the arguments to the state.
+ self.drive = drive
+ self.base_dir = base_dir
+ self.chunk_size = chunk_size
+
+ # 2: Create a folder to store the data.
+ os.makedirs(self.base_dir, exist_ok=True)
+
+ # 3: Keep a reference to the uploaded filenames.
+ self.uploaded_files = dict()
+
+ def get_filepath(self, path: str) -> str:
+ """Returns file path stored on the file server."""
+ return os.path.join(self.base_dir, path)
+
+ def get_random_filename(self) -> str:
+ """Returns a random hash for the file name."""
+ return uuid.uuid4().hex
+
+ def upload_file(self, file):
+ """Upload a file while tracking its progress."""
+ # 1: Track metadata about the file
+ filename = file.filename
+ uploaded_file = self.get_random_filename()
+ meta_file = uploaded_file + ".meta"
+ self.uploaded_files[filename] = {"progress": (0, None), "done": False}
+
+ # 2: Create a stream and write bytes of
+ # the file to the disk under `uploaded_file` path.
+ with open(self.get_filepath(uploaded_file), "wb") as out_file:
+ content = file.read(self.chunk_size)
+ while content:
+ # 2.1 Write the file bytes
+ size = out_file.write(content)
+
+ # 2.2 Update the progress metadata
+ self.uploaded_files[filename]["progress"] = (
+ self.uploaded_files[filename]["progress"][0] + size,
+ None,
+ )
+ # 4: Read next chunk of data
+ content = file.read(self.chunk_size)
+
+ # 3: Update metadata that the file has been uploaded.
+ full_size = self.uploaded_files[filename]["progress"][0]
+ self.drive.put(self.get_filepath(uploaded_file))
+ self.uploaded_files[filename] = {
+ "progress": (full_size, full_size),
+ "done": True,
+ "uploaded_file": uploaded_file,
+ }
+
+ # 4: Write down the metadata about the file to the disk
+ meta = {
+ "original_path": filename,
+ "display_name": os.path.splitext(filename)[0],
+ "size": full_size,
+ "drive_path": uploaded_file,
+ }
+ with open(self.get_filepath(meta_file), "wt") as f:
+ json.dump(meta, f)
+
+ # 5: Put the file to the drive.
+ # It means other components can access get or list them.
+ self.drive.put(self.get_filepath(meta_file))
+ return meta
+
+ def list_files(self, file_path: str):
+ # 1: Get the local file path of the file server.
+ file_path = self.get_filepath(file_path)
+
+ # 2: If the file exists in the drive, transfer it locally.
+ if not os.path.exists(file_path):
+ self.drive.get(file_path)
+
+ if os.path.isdir(file_path):
+ result = set()
+ for _, _, f in os.walk(file_path):
+ for file in f:
+ if not file.endswith(".meta"):
+ for filename, meta in self.uploaded_files.items():
+ if meta["uploaded_file"] == file:
+ result.add(filename)
+ return {"asset_names": [v for v in result]}
+
+ # 3: If the filepath is a tar or zip file, list their contents
+ if zipfile.is_zipfile(file_path):
+ with zipfile.ZipFile(file_path, "r") as zf:
+ result = zf.namelist()
+ elif tarfile.is_tarfile(file_path):
+ with tarfile.TarFile(file_path, "r") as tf:
+ result = tf.getnames()
+ else:
+ raise ValueError("Cannot open archive file!")
+
+ # 4: Returns the matching files.
+ return {"asset_names": result}
+
+ def run(self):
+ # 1: Imports flask requirements.
+ from flask import Flask, request
+ from flask_cors import CORS
+
+ # 2: Create a flask app
+ flask_app = Flask(__name__)
+ CORS(flask_app)
+
+ # 3: Define the upload file endpoint
+ @flask_app.post("/upload_file/")
+ def upload_file():
+ """Upload a file directly as form data."""
+ f = request.files["file"]
+ return self.upload_file(f)
+
+ @flask_app.get("/")
+ def list_files():
+ return self.list_files(str(Path(self.base_dir).resolve()))
+
+ # 5: Start the flask app while providing the `host` and `port`.
+ flask_app.run(host=self.host, port=self.port, load_dotenv=False)
+
+ def alive(self):
+ """Hack: Returns whether the server is alive."""
+ return self.url != ""
+
+
+import requests
+
+from lightning import LightningWork
+
+
+class TestFileServer(LightningWork):
+ def __init__(self, drive: Drive):
+ super().__init__(cache_calls=True)
+ self.drive = drive
+
+ def run(self, file_server_url: str, first=True):
+ if first:
+ with open("test.txt", "w") as f:
+ f.write("Some text.")
+
+ response = requests.post(file_server_url + "/upload_file/", files={"file": open("test.txt", "rb")})
+ assert response.status_code == 200
+ else:
+ response = requests.get(file_server_url)
+ assert response.status_code == 200
+ assert response.json() == {"asset_names": ["test.txt"]}
+
+
+from lightning import LightningApp, LightningFlow
+
+
+class Flow(LightningFlow):
+ def __init__(self):
+ super().__init__()
+ # 1: Create a drive to share data between works
+ self.drive = Drive("lit://file_server")
+ # 2: Create the filer server
+ self.file_server = FileServer(self.drive)
+ # 3: Create the file ser
+ self.test_file_server = TestFileServer(self.drive)
+
+ def run(self):
+ # 1: Start the file server.
+ self.file_server.run()
+
+ # 2: Trigger the test file server work when ready.
+ if self.file_server.alive():
+ # 3 Execute the test file server work.
+ self.test_file_server.run(self.file_server.url)
+ self.test_file_server.run(self.file_server.url, first=False)
+
+ # 4 When both execution are successful, exit the app.
+ if self.test_file_server.num_successes == 2:
+ self._exit()
+
+ def configure_layout(self):
+ # Expose the file_server component
+ # in the UI using its `/` endpoint.
+ return {"name": "File Server", "content": self.file_server}
+
+
+from lightning.app.runners import MultiProcessRuntime
+
+
+def test_file_server():
+ app = LightningApp(Flow())
+ MultiProcessRuntime(app).dispatch()
+
+
+from lightning.app.testing.testing import run_app_in_cloud
+
+
+def test_file_server_in_cloud():
+ # You need to provide the directory containing the app file.
+ app_dir = "docs/source-app/examples/file_server"
+ with run_app_in_cloud(app_dir) as (admin_page, view_page, get_logs_fn):
+ """# 1. `admin_page` and `view_page` are playwright Page Objects.
+
+ # Check out https://playwright.dev/python/ doc to learn more.
+ # You can click the UI and trigger actions.
+
+ # 2. By calling logs = get_logs_fn(),
+ # you get all the logs currently on the admin page.
+ """
diff --git a/docs/source-app/examples/file_server/file_server.rst b/docs/source-app/examples/file_server/file_server.rst
new file mode 100644
index 0000000000..430333a875
--- /dev/null
+++ b/docs/source-app/examples/file_server/file_server.rst
@@ -0,0 +1,12 @@
+
+.. _fileserver_example:
+
+###################
+Build a File Server
+###################
+
+**Prerequisite**: Reach :ref:`level 16+ ` and read the `Drive article `_.
+
+----
+
+.. include:: file_server_content.rst
diff --git a/docs/source-app/examples/file_server/file_server_content.rst b/docs/source-app/examples/file_server/file_server_content.rst
new file mode 100644
index 0000000000..26603e04f8
--- /dev/null
+++ b/docs/source-app/examples/file_server/file_server_content.rst
@@ -0,0 +1,82 @@
+*********
+Objective
+*********
+
+Create a simple application where users can upload files and list the uploaded files.
+
+----
+
+*****************
+Final Application
+*****************
+
+Here is a recording of the final application built in this example tested with pytest.
+
+.. raw:: html
+
+
+
+----
+
+*************
+System Design
+*************
+
+In order to create such application, we need to build two components and an application:
+
+* A **File Server Component** that gives you the ability to download or list files shared with your application. This is particularly useful when you want to trigger an ML job but your users need to provide their own data or if the user wants to download the trained checkpoints.
+
+* A **Test File Server** Component to interact with the file server.
+
+* An application putting everything together and its associated pytest tests.
+
+----
+
+********
+Tutorial
+********
+
+Let's dive in on how to create such application and component:
+
+.. raw:: html
+
+ ` and read the docstring of of :class:`~lightning_app.components.python.tracer.TracerPythonScript` component.
+
+----
+
+.. include:: github_repo_runner_content.rst
diff --git a/docs/source-app/examples/github_repo_runner/github_repo_runner_content.rst b/docs/source-app/examples/github_repo_runner/github_repo_runner_content.rst
new file mode 100644
index 0000000000..335b21ce7f
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/github_repo_runner_content.rst
@@ -0,0 +1,98 @@
+
+*********
+Objective
+*********
+
+Create a simple application where users can enter information in a UI to run a given PyTorch Lightning Script from a given Github Repo with optionally some extra python requirements and arguments.
+
+Furthermore, the users should be able to monitor their training progress in real-time, view the logs, and get the best-monitored metric and associated checkpoint for their models.
+
+----
+
+*****************
+Final Application
+*****************
+
+Here is a recording of the final application built in this example. The example is around 200 lines in total and should give you a great foundation to build your own Lightning App.
+
+.. raw:: html
+
+
+
+----
+
+*************
+System Design
+*************
+
+In order to create such application, we need to build several components:
+
+* A GithubRepoRunner Component that clones a repo, runs a specific script with provided arguments and collect logs.
+
+* A PyTorch Lightning GithubRepoRunner Component that augments the GithubRepoRunner component to track PyTorch Lightning Trainer.
+
+* A UI for the users to provide to trigger dynamically a new execution.
+
+* A Flow to dynamically create GithubRepoRunner once a user submits information from the UI.
+
+Let's dive in on how to create such a component.
+
+----
+
+********
+Tutorial
+********
+
+.. raw:: html
+
+ `_, etc.
+
+It is possible and recommended to search the hyperparameter space for the best validation score.
+
+An HPO search consists of:
+
+* an objective method
+* a defined parameter space
+* a method for searching or sampling candidates
+
+A naive method for sampling candidates is grid search, which exhaustively considers all
+hyperparameter combinations from a user-specified grid.
+
+Fortunately, HPO is an active area of research, and many methods have been developed to
+optimize the time required to get strong candidates.
+
+In the following tutorial, you will learn how to use Lightning together with `Optuna `_
+for our application.
+
+----
+
+********
+Examples
+********
+
+.. raw:: html
+
+ `_ on `lightning.ai `_.
+
+.. code-block:: bash
+
+ lightning install app lightning/hpo
+
+*********************
+Lightning HPO Example
+*********************
+
+In this tutorial, we are going to convert `Optuna Efficient Optimization Algorithms `_ into a Lightning App.
+
+The Optuna example optimizes the value (example: learning-rate) of a ``SGDClassifier`` from ``sklearn`` trained over the `Iris Dataset `_.
+
+.. literalinclude:: ./optuna_reference.py
+ :language: python
+
+
+As you can see, several trials were pruned (stopped) before they finished all of the iterations.
+
+.. code-block:: console
+
+ A new study created in memory with name: no-name-4423c12c-22e1-4eaf-ba60-caf0020403c6
+ Trial 0 finished with value: 0.07894736842105265 and parameters: {'alpha': 0.00020629773477269024}. Best is trial 0 with value: 0.07894736842105265.
+ Trial 1 finished with value: 0.368421052631579 and parameters: {'alpha': 0.0005250149151047217}. Best is trial 0 with value: 0.07894736842105265.
+ Trial 2 finished with value: 0.052631578947368474 and parameters: {'alpha': 5.9086862655635784e-05}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 3 finished with value: 0.3421052631578947 and parameters: {'alpha': 0.07177263583415294}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 4 finished with value: 0.23684210526315785 and parameters: {'alpha': 1.7451874636151302e-05}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 5 pruned.
+ Trial 6 finished with value: 0.10526315789473684 and parameters: {'alpha': 1.4943994864178649e-05}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 7 pruned.
+ Trial 8 pruned.
+ Trial 9 pruned.
+ Trial 10 pruned.
+ Trial 11 pruned.
+ Trial 12 pruned.
+ Trial 13 pruned.
+ Trial 14 pruned.
+ Trial 15 pruned.
+ Trial 16 finished with value: 0.07894736842105265 and parameters: {'alpha': 0.006166329613687364}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 17 pruned.
+ Trial 18 pruned.
+ Trial 19 pruned.
+
+The example above has been re-organized in order to run as Lightning App.
+
+.. literalinclude:: ./lightning_hpo_target.py
+ :language: python
+
+Now, your code can run at scale in the cloud, if needed, and it has a simple neat UI.
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/lightning_hpo_optimizer.png
+ :alt: Lightning App UI
+ :width: 100 %
+
+As you can see, several trials were pruned (stopped) before they finished all of the iterations. Same as when using pure optuna.
+
+.. code-block:: console
+
+ A new study created in memory with name: no-name-a93d848e-a225-4df3-a9c3-5f86680e295d
+ Trial 0 finished with value: 0.23684210526315785 and parameters: {'alpha': 0.006779437004523296}. Best is trial 0 with value: 0.23684210526315785.
+ Trial 1 finished with value: 0.07894736842105265 and parameters: {'alpha': 0.008936151407006062}. Best is trial 1 with value: 0.07894736842105265.
+ Trial 2 finished with value: 0.052631578947368474 and parameters: {'alpha': 0.0035836511240528008}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 3 finished with value: 0.052631578947368474 and parameters: {'alpha': 0.0005393218926409795}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 4 finished with value: 0.1578947368421053 and parameters: {'alpha': 6.572557493358585e-05}. Best is trial 2 with value: 0.052631578947368474.
+ Trial 5 finished with value: 0.02631578947368418 and parameters: {'alpha': 0.0013953760106345603}. Best is trial 5 with value: 0.02631578947368418.
+ Trail 6 pruned.
+ Trail 7 pruned.
+ Trail 8 pruned.
+ Trail 9 pruned.
+ Trial 10 finished with value: 0.07894736842105265 and parameters: {'alpha': 0.00555435554783454}. Best is trial 5 with value: 0.02631578947368418.
+ Trail 11 pruned.
+ Trial 12 finished with value: 0.052631578947368474 and parameters: {'alpha': 0.025624276147153992}. Best is trial 5 with value: 0.02631578947368418.
+ Trial 13 finished with value: 0.07894736842105265 and parameters: {'alpha': 0.014613957457075546}. Best is trial 5 with value: 0.02631578947368418.
+ Trail 14 pruned.
+ Trail 15 pruned.
+ Trail 16 pruned.
+ Trial 17 finished with value: 0.052631578947368474 and parameters: {'alpha': 0.01028208215647372}. Best is trial 5 with value: 0.02631578947368418.
+ Trail 18 pruned.
+ Trail 19 pruned.
diff --git a/docs/source-app/examples/hpo/lightning_hpo_target.py b/docs/source-app/examples/hpo/lightning_hpo_target.py
new file mode 100644
index 0000000000..779f992554
--- /dev/null
+++ b/docs/source-app/examples/hpo/lightning_hpo_target.py
@@ -0,0 +1,53 @@
+import optuna
+from lightning_hpo import BaseObjective, Optimizer
+from optuna.distributions import LogUniformDistribution
+from sklearn import datasets
+from sklearn.linear_model import SGDClassifier
+from sklearn.model_selection import train_test_split
+
+from lightning import LightningApp, LightningFlow
+
+
+class Objective(BaseObjective):
+ def run(self, params):
+ # WARNING: Don't forget to assign `params` to self,
+ # so they get tracked in the state.
+ self.params = params
+
+ iris = datasets.load_iris()
+ classes = list(set(iris.target))
+ train_x, valid_x, train_y, valid_y = train_test_split(iris.data, iris.target, test_size=0.25, random_state=0)
+
+ clf = SGDClassifier(alpha=params["alpha"])
+
+ for step in range(100):
+ clf.partial_fit(train_x, train_y, classes=classes)
+ intermediate_value = 1.0 - clf.score(valid_x, valid_y)
+
+ # WARNING: Assign to reports,
+ # so the state is instantly sent to the flow.
+ self.reports = self.reports + [[intermediate_value, step]]
+
+ self.best_model_score = 1.0 - clf.score(valid_x, valid_y)
+
+ def distributions(self):
+ return {"alpha": LogUniformDistribution(1e-5, 1e-1)}
+
+
+class RootFlow(LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.optimizer = Optimizer(
+ objective_cls=Objective,
+ n_trials=20,
+ study=optuna.create_study(pruner=optuna.pruners.MedianPruner()),
+ )
+
+ def run(self):
+ self.optimizer.run()
+
+ def configure_layout(self):
+ return {"name": "HyperPlot", "content": self.optimizer.hi_plot}
+
+
+app = LightningApp(RootFlow())
diff --git a/docs/source-app/tutorials/hpo/objective.py b/docs/source-app/examples/hpo/objective.py
similarity index 55%
rename from docs/source-app/tutorials/hpo/objective.py
rename to docs/source-app/examples/hpo/objective.py
index 7e83551a14..d20232fb10 100644
--- a/docs/source-app/tutorials/hpo/objective.py
+++ b/docs/source-app/examples/hpo/objective.py
@@ -1,12 +1,11 @@
import numpy as np
-from lightning_app import LightningWork
+import lightning as L
-class ObjectiveWork(LightningWork):
+class ObjectiveWork(L.LightningWork):
def __init__(self):
super().__init__(parallel=True)
- self.has_started = False
self.metric = None
self.trial_id = None
self.params = None
@@ -14,8 +13,9 @@ class ObjectiveWork(LightningWork):
def run(self, trial_id, **params):
self.trial_id = trial_id
- self.params = params # Received suggested `backbone` and `learning_rate`
- self.has_started = True
- # Emulate metric computation would be computed once a script has been completed.
+ # Received suggested `backbone` and `learning_rate`
+ self.params = params
+ # Emulate metric computation would be
+ # computed once a script has been completed.
# In reality, this would excute a user defined script.
self.metric = np.random.uniform(0, 100)
diff --git a/docs/source-app/examples/hpo/optuna_reference.py b/docs/source-app/examples/hpo/optuna_reference.py
new file mode 100644
index 0000000000..46f76c8662
--- /dev/null
+++ b/docs/source-app/examples/hpo/optuna_reference.py
@@ -0,0 +1,36 @@
+import logging
+import sys
+
+import optuna
+from sklearn import datasets
+from sklearn.linear_model import SGDClassifier
+from sklearn.model_selection import train_test_split
+
+
+def objective(trial):
+ iris = datasets.load_iris()
+ classes = list(set(iris.target))
+ train_x, valid_x, train_y, valid_y = train_test_split(iris.data, iris.target, test_size=0.25, random_state=0)
+
+ alpha = trial.suggest_float("alpha", 1e-5, 1e-1, log=True)
+ clf = SGDClassifier(alpha=alpha)
+
+ for step in range(100):
+ clf.partial_fit(train_x, train_y, classes=classes)
+
+ # Report intermediate objective value.
+ intermediate_value = 1.0 - clf.score(valid_x, valid_y)
+ trial.report(intermediate_value, step)
+
+ # Handle pruning based on the intermediate value.
+ if trial.should_prune():
+ raise optuna.TrialPruned()
+
+ return 1.0 - clf.score(valid_x, valid_y)
+
+
+# Add stream handler of stdout to show the messages
+logger = optuna.logging.get_logger("optuna")
+logger.addHandler(logging.StreamHandler(sys.stdout))
+study = optuna.create_study(pruner=optuna.pruners.MedianPruner())
+study.optimize(objective, n_trials=20)
diff --git a/docs/source-app/examples/model_deploy_app.rst b/docs/source-app/examples/model_deploy_app.rst
deleted file mode 100644
index f4f564d773..0000000000
--- a/docs/source-app/examples/model_deploy_app.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-############################
-Build a Model Deployment App
-############################
diff --git a/docs/source-app/examples/model_server_app/app.py b/docs/source-app/examples/model_server_app/app.py
new file mode 100644
index 0000000000..9985014b11
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/app.py
@@ -0,0 +1,34 @@
+from locust_component import Locust
+from model_server import MLServer
+from train import TrainModel
+
+from lightning import LightningApp, LightningFlow
+
+
+class TrainAndServe(LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.train_model = TrainModel()
+ self.model_server = MLServer(
+ name="mnist-svm",
+ implementation="mlserver_sklearn.SKLearnModel",
+ workers=8,
+ )
+ self.performance_tester = Locust(num_users=100)
+
+ def run(self):
+ self.train_model.run()
+ self.model_server.run(self.train_model.best_model_path)
+ if self.model_server.alive():
+ # The performance tester needs the model server to be up
+ # and running to be started, so the URL is added in the UI.
+ self.performance_tester.run(self.model_server.url)
+
+ def configure_layout(self):
+ return [
+ {"name": "Server", "content": self.model_server.url + "/docs"},
+ {"name": "Server Testing", "content": self.performance_tester},
+ ]
+
+
+app = LightningApp(TrainAndServe())
diff --git a/docs/source-app/examples/model_server_app/load_testing.rst b/docs/source-app/examples/model_server_app/load_testing.rst
new file mode 100644
index 0000000000..97345dec4c
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/load_testing.rst
@@ -0,0 +1,57 @@
+:orphan:
+
+***********************************
+3. Build the Load Testing Component
+***********************************
+
+Now, we are going to create a component to test the performance of your model server.
+
+We are going to use a python performance testing tool called `Locust `_.
+
+.. literalinclude:: ./locust_component.py
+
+
+Finally, once the component is done, we need to crate a ``locustfile.py`` file which defines the format of the request to send to your model server.
+
+The endpoint to hit has the following format: ``/v2/models/{MODEL_NAME}/versions/{VERSION}/infer``.
+
+.. literalinclude:: ./locustfile.py
+
+
+----
+
+.. raw:: html
+
+ `_ which aims to provide an easy way to start serving your machine learning models through a REST and gRPC interface,
+fully compliant with KFServing's V2 Dataplane spec.
+
+.. literalinclude:: ./model_server.py
+
+----
+
+.. raw:: html
+
+ `.
+
+----
+
+.. include:: model_server_app_content.rst
diff --git a/docs/source-app/examples/model_server_app/model_server_app_content.rst b/docs/source-app/examples/model_server_app/model_server_app_content.rst
new file mode 100644
index 0000000000..8675de939a
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/model_server_app_content.rst
@@ -0,0 +1,84 @@
+
+*********
+Objective
+*********
+
+Create a simple application that trains and serves a `Sklearn `_
+
+----
+
+*****************
+Final Application
+*****************
+
+Here is a gif of the final application built in this example.
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/ml_server_2.gif
+
+----
+
+*************
+System Design
+*************
+
+In order to create such application, we need to build several components:
+
+* A Model Train Component that trains a model and provides its trained weights
+
+* A Model Server Component that serves as an API endpoint for the model generated by the **Model Train Component**.
+
+* A Load Testing Component that tests the model server works as expected. This could be used to CI/CD the performance of newly generated models (left to the users).
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/model_server_app_2.png
+
+Let's dive into the tutorial.
+
+----
+
+********
+Tutorial
+********
+
+.. raw:: html
+
+
+ +Congrats, you have finished the **Build a Model Server** example ! + +---- + +****************** +Find more examples +****************** + +.. raw:: html + +`_ model on the digits dataset (classification).
+
+Once the model is trained, it is saved and a reference :class:`~lightning_app.storage.path.Path` with ``best_model_path`` state attribute.
+
+.. literalinclude:: ./train.py
+
+----
+
+.. raw:: html
+
+ `_.
+
+.. literalinclude:: ../code_samples/convert_pl_to_app/train.py
+
+Add the following to the ``requirements.txt`` file.
+
+.. literalinclude:: ../code_samples/convert_pl_to_app/requirements.py
+
+Simply run the following commands in your terminal to install the requirements and train the model.
+
+.. code-block:: bash
+
+ pip install -r requirements.txt
+ python train.py
+
+Get through `PyTorch Lightning Introduction `_ to learn more.
+
+----
+
+**********
+Next Steps
+**********
+
+.. raw:: html
+
+
+`_.
-
-############################
-Lightning Apps in 15 minutes
-############################
-
-**Required background:** Basic Python familiarity.
-
-**Goal:** In this guide, we'll walk you through the 4 key steps to build your first Lightning app.
-
-----
-
-The app we build in this guide trains and deploys a model.
-
-..
- (|qs_app|).
-
- .. |qs_app| raw:: html
-
- see the app live here
-
-
-A Lightning app is **Organized Python**, it enables AI researchers and ML engineers to build complex AI workflows without any of the **cloud** boilerplate.
-
-With Lightning apps your favorite components can work together on any machine at any scale. Here's an illustration:
+Here is a recording of this App running locally and in the cloud with the same behavior.
.. raw:: html
-
+
+ +
+
-| +In the steps below, we are going to show you how to build this application. -Lightning Apps are: - -- cloud agnostic -- fault-tolerant -- production ready -- locally debuggable -- and much more - -.. join_slack:: - :align: left - :margin: 20 - - ----- - -******************* -Who can build apps? -******************* -Anyone who knows Python can build a Lightning app, even without ML experience. +Here are `the entire App's code`_ and `its commented components. `_
----
@@ -65,20 +25,21 @@ Anyone who knows Python can build a Lightning app, even without ML experience.
Step 1: Install Lightning
*************************
-First, you'll need to install Lightning (make sure you use Python 3.8+).
+If you are using a :ref:`virtual environment`, don't forget to activate it before running commands.
+You must do so in every new shell.
-.. code:: bash
+.. tip:: We highly recommend using virtual environments.
- python -m pip install -U lightning
+.. code:: python
-(pip and conda install coming soon)
+ pip install lightning
----
-********************************
-Step 2: Install Train Deploy App
-********************************
-The first Lightning app we'll explore is an app to train and deploy a machine learning model.
+****************************************
+Step 2: Install the *Train and Demo* App
+****************************************
+The first Lightning App we'll explore is an App to train and demo a machine learning model.
..
[|qs_code|], [|qs_live_app|].
@@ -89,70 +50,65 @@ The first Lightning app we'll explore is an app to train and deploy a machine le
.. |qs_code| raw:: html
- code
+ code
-Install this app by typing:
+Install this App by typing:
.. code-block:: bash
lightning install app lightning/quick-start
-Verify the app was succesfully installed:
+Verify the App was succesfully installed:
.. code-block:: bash
cd lightning-quick-start
- ls
----
***************************
-Step 3: Run the app locally
+Step 3: Run the App locally
***************************
-Run the app locally with the ``run`` command
+
+Run the app locally with the ``run`` command 🤯
.. code:: bash
lightning run app app.py
-🤯
-
----
********************************
-Step 4: Run the app on the cloud
+Step 4: Run the App in the cloud
********************************
-Add the ``--cloud`` argument to run on the `Lightning.AI cloud
+
diff --git a/docs/source-app/examples/file_server/file_server_step_1.rst b/docs/source-app/examples/file_server/file_server_step_1.rst
new file mode 100644
index 0000000000..782e553e9f
--- /dev/null
+++ b/docs/source-app/examples/file_server/file_server_step_1.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+*********************************************
+1. Implement the FileServer general structure
+*********************************************
+
+Let's dive in on how to create such a component with the code below.
+
+.. literalinclude:: ./app.py
+ :lines: 1-44, 132-158
+ :emphasize-lines: 16, 51-
diff --git a/docs/source-app/examples/file_server/file_server_step_2.rst b/docs/source-app/examples/file_server/file_server_step_2.rst
new file mode 100644
index 0000000000..668b01b177
--- /dev/null
+++ b/docs/source-app/examples/file_server/file_server_step_2.rst
@@ -0,0 +1,37 @@
+:orphan:
+
+**********************************************************
+2. Implement the File Server upload and list_files methods
+**********************************************************
+
+Let's dive in on how to implement such methods.
+
+***************************
+Implement the upload method
+***************************
+
+In this method, we are creating a stream between the uploaded file and the uploaded file stored on the file server disk.
+
+Once the file is uploaded, we are putting the file into the :class:`~lightning_app.storage.drive.Drive`, so it becomes persistent and accessible to all components.
+
+.. literalinclude:: ./app.py
+ :lines: 13, 52-100
+ :emphasize-lines: 49
+
+*******************************
+Implement the fist_files method
+*******************************
+
+First, in this method, we get the file in the file server filesystem, if available in the Drive. Once done, we list the the files under the provided paths and return the results.
+
+.. literalinclude:: ./app.py
+ :lines: 13, 101-131
+ :emphasize-lines: 9
+
+
+*******************
+Implement utilities
+*******************
+
+.. literalinclude:: ./app.py
+ :lines: 13, 46-51
diff --git a/docs/source-app/examples/file_server/file_server_step_3.rst b/docs/source-app/examples/file_server/file_server_step_3.rst
new file mode 100644
index 0000000000..97b524a978
--- /dev/null
+++ b/docs/source-app/examples/file_server/file_server_step_3.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+********************************************
+3. Implement a File Server Testing Component
+********************************************
+
+Let's dive in on how to implement a testing component for a server.
+
+This component needs to test two things:
+
+* The **/upload_file/** endpoint by creating a file and sending its content to it.
+
+* The **/** endpoint listing files, by validating the that previously uploaded file is present in the response.
+
+.. literalinclude:: ./app.py
+ :lines: 161-183
diff --git a/docs/source-app/examples/file_server/file_server_step_4.rst b/docs/source-app/examples/file_server/file_server_step_4.rst
new file mode 100644
index 0000000000..06d9e051dc
--- /dev/null
+++ b/docs/source-app/examples/file_server/file_server_step_4.rst
@@ -0,0 +1,86 @@
+:orphan:
+
+************************************************************
+4. Implement tests for the File Server component with pytest
+************************************************************
+
+Let's create a simple Lightning App (App) with our **File Server** and the **File Server Test** components.
+
+Once the File Server is up and running, we'll execute the **test_file_server** LightningWork and when both calls are successful, we exit the App using ``self._exit``.
+
+.. literalinclude:: ./app.py
+ :lines: 186-216
+
+
+Simply create a ``test.py`` file with the following code and run ``pytest tests.py``
+
+.. literalinclude:: ./app.py
+ :lines: 218-222
+
+To test the App in the cloud, create a ``cloud_test.py`` file with the following code and run ``pytest cloud_test.py``. Under the hood, we are using the end-to-end testing `playwright
+
+.. displayitem::
+ :header: 1. Implement the File Server general structure
+ :description: Put together the shape of the component
+ :col_css: col-md-4
+ :button_link: file_server_step_1.html
+ :height: 180
+ :tag: Basic
+
+.. displayitem::
+ :header: 2. Implement the File Server upload and list files methods
+ :description: Add the core functionalities to the component
+ :col_css: col-md-4
+ :button_link: file_server_step_2.html
+ :height: 180
+ :tag: Basic
+
+.. displayitem::
+ :header: 3. Implement a File Server Testing Component
+ :description: Create a component to test the file server
+ :col_css: col-md-4
+ :button_link: file_server_step_3.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 4. Implement tests for the File Server component with pytest
+ :description: Create an app to validate the upload and list files endpoints
+ :col_css: col-md-4
+ :button_link: file_server_step_4.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/github_repo_runner/.lightning b/docs/source-app/examples/github_repo_runner/.lightning
new file mode 100644
index 0000000000..4bae28430e
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/.lightning
@@ -0,0 +1 @@
+name: github_repo_runner
diff --git a/docs/source-app/examples/github_repo_runner/app.py b/docs/source-app/examples/github_repo_runner/app.py
new file mode 100644
index 0000000000..a020b69c02
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/app.py
@@ -0,0 +1,299 @@
+import io
+import os
+import subprocess
+import sys
+from copy import deepcopy
+from functools import partial
+from subprocess import Popen
+from typing import Any, Dict, List, Optional
+
+from lightning import BuildConfig, CloudCompute, LightningApp, LightningFlow
+from lightning.app import structures
+from lightning.app.components.python import TracerPythonScript
+from lightning.app.frontend import StreamlitFrontend
+from lightning.app.storage.path import Path
+from lightning.app.utilities.state import AppState
+
+
+class GithubRepoRunner(TracerPythonScript):
+ def __init__(
+ self,
+ id: str,
+ github_repo: str,
+ script_path: str,
+ script_args: List[str],
+ requirements: List[str],
+ cloud_compute: Optional[CloudCompute] = None,
+ **kwargs: Any,
+ ):
+ """The GithubRepoRunner Component clones a repo, runs a specific script with provided arguments and collect
+ logs.
+
+ Arguments:
+ id: Identified of the component.
+ github_repo: The Github Repo URL to clone.
+ script_path: The path to the script to execute.
+ script_args: The arguments to be provided to the script.
+ requirements: The python requirements tp run the script.
+ cloud_compute: The object to select the cloud instance.
+ """
+ super().__init__(
+ script_path=script_path,
+ script_args=script_args,
+ cloud_compute=cloud_compute,
+ cloud_build_config=BuildConfig(requirements=requirements),
+ **kwargs,
+ )
+ self.id = id
+ self.github_repo = github_repo
+ self.logs = []
+
+ def run(self, *args, **kwargs):
+ # 1. Hack: Patch stdout so we can capture the logs.
+ string_io = io.StringIO()
+ sys.stdout = string_io
+
+ # 2: Use git command line to clone the repo.
+ repo_name = self.github_repo.split("/")[-1].replace(".git", "")
+ cwd = os.path.dirname(__file__)
+ subprocess.Popen(f"git clone {self.github_repo}", cwd=cwd, shell=True).wait()
+
+ # 3: Execute the parent run method of the TracerPythonScript class.
+ os.chdir(os.path.join(cwd, repo_name))
+ super().run(*args, **kwargs)
+
+ # 4: Get all the collected logs and add them to the state.
+ # This isn't optimal as heavy, but works for this demo purpose.
+ self.logs = string_io.getvalue()
+ string_io.close()
+
+ def configure_layout(self):
+ return {"name": self.id, "content": self}
+
+
+class PyTorchLightningGithubRepoRunner(GithubRepoRunner):
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+ self.best_model_path = None
+ self.best_model_score = None
+
+ def configure_tracer(self):
+ from pytorch_lightning import Trainer
+ from pytorch_lightning.callbacks import Callback
+
+ tracer = super().configure_tracer()
+
+ class TensorboardServerLauncher(Callback):
+ def __init__(self, work):
+ # The provided `work` is the
+ # current ``PyTorchLightningScript`` work.
+ self.w = work
+
+ def on_train_start(self, trainer, *_):
+ # Add `host` and `port` for tensorboard to work in the cloud.
+ cmd = f"tensorboard --logdir='{trainer.logger.log_dir}'"
+ server_args = f"--host {self.w.host} --port {self.w.port}"
+ Popen(cmd + " " + server_args, shell=True)
+
+ def trainer_pre_fn(self, *args, work=None, **kwargs):
+ # Intercept Trainer __init__ call
+ # and inject a ``TensorboardServerLauncher`` component.
+ kwargs["callbacks"].append(TensorboardServerLauncher(work))
+ return {}, args, kwargs
+
+ # 5. Patch the `__init__` method of the Trainer
+ # to inject our callback with a reference to the work.
+ tracer.add_traced(Trainer, "__init__", pre_fn=partial(trainer_pre_fn, work=self))
+ return tracer
+
+ def on_after_run(self, end_script_globals):
+ import torch
+
+ # 1. Once the script has finished to execute,
+ # we can collect its globals and access any objects.
+ trainer = end_script_globals["cli"].trainer
+ checkpoint_callback = trainer.checkpoint_callback
+ lightning_module = trainer.lightning_module
+
+ # 2. From the checkpoint_callback,
+ # we are accessing the best model weights
+ checkpoint = torch.load(checkpoint_callback.best_model_path)
+
+ # 3. Load the best weights and torchscript the model.
+ lightning_module.load_state_dict(checkpoint["state_dict"])
+ lightning_module.to_torchscript(f"{self.name}.pt")
+
+ # 4. Use lightning.app.storage.Pathto create a reference to the
+ # torch scripted model. In the cloud with multiple machines,
+ # by simply passing this reference to another work,
+ # it triggers automatically a file transfer.
+ self.best_model_path = Path(f"{self.name}.pt")
+
+ # 5. Keep track of the metrics.
+ self.best_model_score = float(checkpoint_callback.best_model_score)
+
+
+class KerasGithubRepoRunner(GithubRepoRunner):
+ """Left to the users to implement."""
+
+
+class TensorflowGithubRepoRunner(GithubRepoRunner):
+ """Left to the users to implement."""
+
+
+GITHUB_REPO_RUNNERS = {
+ "PyTorch Lightning": PyTorchLightningGithubRepoRunner,
+ "Keras": KerasGithubRepoRunner,
+ "Tensorflow": TensorflowGithubRepoRunner,
+}
+
+
+class Flow(LightningFlow):
+ def __init__(self):
+ super().__init__()
+ # 1: Keep track of the requests within the state
+ self.requests = []
+ # 2: Create a dictionary of components.
+ self.ws = structures.Dict()
+
+ def run(self):
+ # Iterate continuously over all requests
+ for request_id, request in enumerate(self.requests):
+ self._handle_request(request_id, deepcopy(request))
+
+ def _handle_request(self, request_id: int, request: Dict):
+ # 1: Create a name and find selected framework
+ name = f"w_{request_id}"
+ ml_framework = request["train"].pop("ml_framework")
+
+ # 2: If the component hasn't been created yet, create it.
+ if name not in self.ws:
+ work_cls = GITHUB_REPO_RUNNERS[ml_framework]
+ work = work_cls(id=request["id"], **request["train"])
+ self.ws[name] = work
+
+ # 3: Run the component
+ self.ws[name].run()
+
+ # 4: Once the component has finished,
+ # add metadata to the original request for the UI.
+ if self.ws[name].best_model_path:
+ request = self.requests[request_id]
+ request["best_model_score"] = self.ws[name].best_model_score
+ request["best_model_path"] = self.ws[name].best_model_path
+
+ def configure_layout(self):
+ # Create a StreamLit UI for the user to run his Github Repo.
+ return StreamlitFrontend(render_fn=render_fn)
+
+
+def page_1__create_new_run(state):
+ import streamlit as st
+
+ st.markdown("# Create a new Run 🎈")
+
+ # 1: Collect arguments from the users
+ id = st.text_input("Name your run", value="my_first_run")
+ github_repo = st.text_input(
+ "Enter a Github Repo URL", value="https://github.com/Lightning-AI/lightning-quick-start.git"
+ )
+
+ default_script_args = "--trainer.max_epochs=5 --trainer.limit_train_batches=4 --trainer.limit_val_batches=4 --trainer.callbacks=ModelCheckpoint --trainer.callbacks.monitor=val_acc"
+ default_requirements = "torchvision, pytorch_lightning, jsonargparse[signatures]"
+
+ script_path = st.text_input("Enter your script to run", value="train_script.py")
+ script_args = st.text_input("Enter your base script arguments", value=default_script_args)
+ requirements = st.text_input("Enter your requirements", value=default_requirements)
+ ml_framework = st.radio("Select your ML Training Frameworks", options=["PyTorch Lightning", "Keras", "Tensorflow"])
+
+ if ml_framework not in ("PyTorch Lightning"):
+ st.write(f"{ml_framework} isn't supported yet.")
+ return
+
+ clicked = st.button("Submit")
+
+ # 2: If clicked, create a new request.
+ if clicked:
+ new_request = {
+ "id": id,
+ "train": {
+ "github_repo": github_repo,
+ "script_path": script_path,
+ "script_args": script_args.split(" "),
+ "requirements": requirements.split(" "),
+ "ml_framework": ml_framework,
+ },
+ }
+ # 3: IMPORTANT: Add a new request to the state in-place.
+ # The flow receives the UI request and dynamically create
+ # and run the associated work from the request information.
+ state.requests = state.requests + [new_request]
+
+
+def page_2__view_run_lists(state):
+ import streamlit as st
+
+ st.markdown("# Run Lists 🎈")
+ # 1: Iterate through all the requests in the state.
+ for i, r in enumerate(state.requests):
+ i = str(i)
+ # 2: Display information such as request, logs, work state, model score.
+ work = state._state["structures"]["ws"]["works"][f"w_{i}"]
+ with st.expander(f"Expand to view Run {i}", expanded=False):
+ if st.checkbox(f"Expand to view your configuration", key=i):
+ st.json(r)
+ if st.checkbox(f"Expand to view logs", key=i):
+ st.code(body=work["vars"]["logs"])
+ if st.checkbox(f"Expand to view your work state", key=i):
+ work["vars"].pop("logs")
+ st.json(work)
+ best_model_score = r.get("best_model_score", None)
+ if best_model_score:
+ if st.checkbox(f"Expand to view your run performance", key=i):
+ st.json({"best_model_score": best_model_score, "best_model_path": r.get("best_model_path")})
+
+
+def page_3__view_app_state(state):
+ import streamlit as st
+
+ st.markdown("# App State 🎈")
+ st.write(state._state)
+
+
+def render_fn(state: AppState):
+ import streamlit as st
+
+ page_names_to_funcs = {
+ "Create a new Run": partial(page_1__create_new_run, state=state),
+ "View your Runs": partial(page_2__view_run_lists, state=state),
+ "View the App state": partial(page_3__view_app_state, state=state),
+ }
+ selected_page = st.sidebar.selectbox("Select a page", page_names_to_funcs.keys())
+ page_names_to_funcs[selected_page]()
+
+
+class RootFlow(LightningFlow):
+ def __init__(self):
+ super().__init__()
+ # Create the flow
+ self.flow = Flow()
+
+ def run(self):
+ # Run the flow
+ self.flow.run()
+
+ def configure_layout(self):
+ # 1: Add the main StreamLit UI
+ selection_tab = [
+ {
+ "name": "Run your Github Repo",
+ "content": self.flow,
+ }
+ ]
+ # 2: Add a new tab whenever a new work is dynamically created
+ run_tabs = [e.configure_layout() for e in self.flow.ws.values()]
+ # 3: Returns the list of tabs.
+ return selection_tab + run_tabs
+
+
+app = LightningApp(RootFlow())
diff --git a/docs/source-app/examples/github_repo_runner/github_repo_runner.rst b/docs/source-app/examples/github_repo_runner/github_repo_runner.rst
new file mode 100644
index 0000000000..affb115b74
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/github_repo_runner.rst
@@ -0,0 +1,13 @@
+.. _github_repo_script_runner_example:
+
+#################################
+Build a Github Repo Script Runner
+#################################
+
+**Audience:** Users that want to create interactive applications which runs Github Repo in the cloud at any scale for multiple users.
+
+**Prerequisite**: Reach :ref:`level 16+
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: Build a DAG
+ :description: Create a dag pipeline
+ :col_css: col-md-4
+ :button_link: ../dag/dag.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a Github Repo Script Runner
+ :description: Run any script on github in the cloud
+ :col_css: col-md-4
+ :button_link: ../github_repo_runner/github_repo_runner.html
+ :height: 150
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: Build a HPO Sweeper
+ :description: Train multiple models with different parameters
+ :col_css: col-md-4
+ :button_link: ../hpo/hpo.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a Model Server
+ :description: Serve multiple models with different parameters
+ :col_css: col-md-4
+ :button_link: ../model_server/model_server.html
+ :height: 150
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/github_repo_runner/github_repo_runner_step_1.rst b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_1.rst
new file mode 100644
index 0000000000..3a683501fa
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_1.rst
@@ -0,0 +1,62 @@
+:orphan:
+
+*******************************************
+1. Implement the GithubRepoRunner Component
+*******************************************
+
+The GithubRepoRunner Component clones a repo, runs a specific script with provided arguments and collect logs.
+
+Let's dive in on how to create such a component with the code below.
+
+.. literalinclude:: ./app.py
+ :lines: -72
+
+----
+
+********
+Tutorial
+********
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: 1. Implement the GithubRepoRunner Component
+ :description: Clone and execute script from a GitHub Repo.
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_1.html
+ :height: 180
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 2. Implement the PyTorch Lightning GithubRepoRunner Component
+ :description: Automate PyTorch Lightning execution
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_2.html
+ :height: 180
+ :tag: Advanced
+
+.. displayitem::
+ :header: 3. Implement the Flow to manage user requests
+ :description: Dynamically create GithubRepoRunner
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_3.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 4. Implement the UI with StreamLit
+ :description: Several pages application
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_4.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 5. Putting everything together
+ :description:
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_5.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/github_repo_runner/github_repo_runner_step_2.rst b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_2.rst
new file mode 100644
index 0000000000..c0825fa8ea
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_2.rst
@@ -0,0 +1,68 @@
+:orphan:
+
+*************************************************************
+2. Implement the PyTorch Lightning GithubRepoRunner Component
+*************************************************************
+
+The PyTorch Lightning GithubRepoRunner Component subclasses the GithubRepoRunner but tailors the execution experience to PyTorch Lightning.
+
+As a matter of fact, this component adds two primary tailored features for PyTorch Lightning users:
+
+* It injects dynamically a custom callback ``TensorboardServerLauncher`` in the PyTorch Lightning Trainer to start a tensorboard server so it can be exposed in Lightning App UI.
+
+* Once the script has run, the ``on_after_run`` hook of the :class:`~lightning_app.components.python.tracer.TracerPythonScript` is invoked with the script globals, meaning we can collect anything we need. In particular, we are reloading the best model, torch scripting it, and storing its path in the state alongside the best metric score.
+
+Let's dive in on how to create such a component with the code below.
+
+.. literalinclude:: ./app.py
+ :lines: 75-136
+
+----
+
+********
+Tutorial
+********
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: 2. Implement the PyTorch Lightning GithubRepoRunner Component
+ :description: Automate PyTorch Lightning execution
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_2.html
+ :height: 180
+ :tag: Advanced
+
+.. displayitem::
+ :header: 3. Implement the Flow to manage user requests
+ :description: Dynamically create GithubRepoRunner
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_3.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 4. Implement the UI with StreamLit
+ :description: Several pages application
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_4.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 5. Putting everything together
+ :description:
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_5.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/github_repo_runner/github_repo_runner_step_3.rst b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_3.rst
new file mode 100644
index 0000000000..fc1b3116be
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_3.rst
@@ -0,0 +1,62 @@
+:orphan:
+
+*********************************************
+3. Implement the Flow to manage user requests
+*********************************************
+
+In step 1 and 2, we have implemented ``GithubRepoRunner`` and ``PyTorchLightningGithubRepoRunner`` components.
+
+Now, we are going to create a component to dynamically handle user requests.
+Let's dive in on how to create such a component with the code below.
+
+.. literalinclude:: ./app.py
+ :lines: 138-187
+
+----
+
+********
+Tutorial
+********
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: 1. Implement the GithubRepoRunner Component
+ :description: Clone and execute script from a GitHub Repo.
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_1.html
+ :height: 180
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 3. Implement the Flow to manage user requests
+ :description: Dynamically create GithubRepoRunner
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_3.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 4. Implement the UI with StreamLit
+ :description: Several pages application
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_4.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 5. Putting everything together
+ :description:
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_5.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/github_repo_runner/github_repo_runner_step_4.rst b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_4.rst
new file mode 100644
index 0000000000..2716adbaf8
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_4.rst
@@ -0,0 +1,93 @@
+:orphan:
+
+**********************************
+4. Implement the UI with StreamLit
+**********************************
+
+In step 3, we have implemented a flow that dynamically creates a Work when a new request is added to the requests list.
+
+From the UI, we create 3 pages with `StreamLit
+
+.. displayitem::
+ :header: 1. Implement the GithubRepoRunner Component
+ :description: Clone and execute script from a GitHub Repo.
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_1.html
+ :height: 180
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 2. Implement the PyTorch Lightning GithubRepoRunner Component
+ :description: Automate PyTorch Lightning execution
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_2.html
+ :height: 180
+ :tag: Advanced
+
+.. displayitem::
+ :header: 4. Implement the UI with StreamLit
+ :description: Several pages application
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_4.html
+ :height: 180
+ :tag: Intermediate
+
+
+.. displayitem::
+ :header: 5. Putting everything together
+ :description:
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_5.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/github_repo_runner/github_repo_runner_step_5.rst b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_5.rst
new file mode 100644
index 0000000000..bdad952332
--- /dev/null
+++ b/docs/source-app/examples/github_repo_runner/github_repo_runner_step_5.rst
@@ -0,0 +1,77 @@
+:orphan:
+
+******************************
+5. Putting everything together
+******************************
+
+Let's dive in on how to create such a component with the code below.
+
+.. literalinclude:: ./app.py
+ :lines: 277-
+
+
+*******************
+Run the application
+*******************
+
+Clone the lightning repo and run the following command:
+
+.. code-block:: bash
+
+ lightning run app docs/source-app/examples/github_repo_runner/app.py
+
+Add **--cloud** to run this application in the cloud.
+
+.. code-block:: bash
+
+ lightning run app docs/source-app/examples/github_repo_runner/app.py --cloud
+
+----
+
+******************
+Find more examples
+******************
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: 1. Implement the GithubRepoRunner Component
+ :description: Clone and execute script from a GitHub Repo.
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_1.html
+ :height: 180
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 2. Implement the PyTorch Lightning GithubRepoRunner Component
+ :description: Automate PyTorch Lightning execution
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_2.html
+ :height: 180
+ :tag: Advanced
+
+.. displayitem::
+ :header: 3. Implement the Flow to manage user requests
+ :description: Dynamically create GithubRepoRunner
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_3.html
+ :height: 180
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 5. Putting everything together
+ :description:
+ :col_css: col-md-4
+ :button_link: github_repo_runner_step_5.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/hands_on_example.rst b/docs/source-app/examples/hands_on_example.rst
new file mode 100644
index 0000000000..57fa1e5ff1
--- /dev/null
+++ b/docs/source-app/examples/hands_on_example.rst
@@ -0,0 +1,50 @@
+:orphan:
+
+#################
+Hands-on Examples
+#################
+
+.. raw:: html
+
+
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: Build a DAG
+ :description: Create a dag pipeline
+ :col_css: col-md-4
+ :button_link: ../dag/dag.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a File Server
+ :description: Train multiple models with different parameters
+ :col_css: col-md-4
+ :button_link: ../file_server/file_server.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a HPO Sweeper
+ :description: Train multiple models with different parameters
+ :col_css: col-md-4
+ :button_link: ../hpo/hpo.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a Model Server
+ :description: Serve multiple models with different parameters
+ :col_css: col-md-4
+ :button_link: ../model_server/model_server.html
+ :height: 150
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/hpo/build_from_scratch.rst b/docs/source-app/examples/hpo/build_from_scratch.rst
new file mode 100644
index 0000000000..cade8b7f6e
--- /dev/null
+++ b/docs/source-app/examples/hpo/build_from_scratch.rst
@@ -0,0 +1,41 @@
+:orphan:
+
+#######################################
+Implement an HPO component from scratch
+#######################################
+
+**Audience:** Users who want to understand how to implement sweep training from scratch.
+
+**Prereqs:** Finish Intermediate Level.
+
+----
+
+********
+Examples
+********
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: Build a DAG
+ :description: Learn how to orchestrate workflows
+ :col_css: col-md-6
+ :button_link: dag/dag.html
+ :height: 180
+
+.. displayitem::
+ :header: Build a File Server
+ :description: Learn how to upload and download files
+ :col_css: col-md-6
+ :button_link: file_server/file_server.html
+ :height: 180
+
+.. displayitem::
+ :header: Build a Github Repo Script Runner
+ :description: Learn how to configure dynamic execution from the UI
+ :col_css: col-md-6
+ :button_link: github_repo_runner/github_repo_runner.html
+ :height: 180
+
+.. displayitem::
+ :header: Build a HPO Sweeper
+ :description: Learn how to scale your training
+ :col_css: col-md-6
+ :button_link: hpo/hpo.html
+ :height: 180
+
+.. displayitem::
+ :header: Build a Model Server
+ :description: Learn how to server your models
+ :col_css: col-md-6
+ :button_link: model_server_app_content.html
+ :height: 180
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/tutorials/hpo/hpo.py b/docs/source-app/examples/hpo/hpo.py
similarity index 70%
rename from docs/source-app/tutorials/hpo/hpo.py
rename to docs/source-app/examples/hpo/hpo.py
index 69bccf67ac..fd05cc2e32 100644
--- a/docs/source-app/tutorials/hpo/hpo.py
+++ b/docs/source-app/examples/hpo/hpo.py
@@ -1,5 +1,6 @@
import optuna
from objective import ObjectiveWork
+from optuna.distributions import CategoricalDistribution, LogUniformDistribution
TOTAL_TRIALS = 6
SIMULTANEOUS_TRIALS = 2
@@ -8,14 +9,16 @@ DONE = False
STUDY = optuna.create_study()
DISTRIBUTIONS = {
- "backbone": optuna.distributions.CategoricalDistribution(["resnet18", "resnet34"]),
- "learning_rate": optuna.distributions.LogUniformDistribution(0.0001, 0.1),
+ "backbone": CategoricalDistribution(["resnet18", "resnet34"]),
+ "learning_rate": LogUniformDistribution(0.0001, 0.1),
}
TRIALS = [ObjectiveWork() for _ in range(TOTAL_TRIALS)]
-while not DONE: # Lightning Infinite Loop
+# Lightning Infinite Loop
+while not DONE:
- if NUM_TRIALS > TOTAL_TRIALS: # Finish the Hyperparameter Optimization
+ # Finish the Hyperparameter Optimization
+ if NUM_TRIALS >= TOTAL_TRIALS:
DONE = True
continue
@@ -28,10 +31,12 @@ while not DONE: # Lightning Infinite Loop
# If a work has already started, it won't be started again.
if not objective_work.has_started:
- trial = STUDY.ask(DISTRIBUTIONS) # Sample a new trial from the distributions
- objective_work.run(trial_id=trial._trial_id, **trial.params) # Run the work
+ # Sample a new trial from the distributions
+ trial = STUDY.ask(DISTRIBUTIONS)
+ # Run the work
+ objective_work.run(trial_id=trial._trial_id, **trial.params)
- # With Lighting, the `objective_work` will run asynchronously
+ # With Lightning, the `objective_work` will run asynchronously
# and the metric will be prodcued after X amount of time.
# The Lightning Infinite Loop would have run a very large number of times by then.
if objective_work.metric and not objective_work.has_told_study:
diff --git a/docs/source-app/examples/hpo/hpo.rst b/docs/source-app/examples/hpo/hpo.rst
new file mode 100644
index 0000000000..2849a62653
--- /dev/null
+++ b/docs/source-app/examples/hpo/hpo.rst
@@ -0,0 +1,80 @@
+.. hpo:
+.. _hpo_example:
+
+
+#######################################################
+Build a Lightning Hyperparameter Optimization (HPO) App
+#######################################################
+
+*******************
+A bit of background
+*******************
+
+Traditionally, developing machine learning (ML) products requires choosing among a large space of
+hyperparameters while creating and training the ML models. Hyperparameter optimization
+(HPO) aims to find a well-performing hyperparameter configuration for a given ML model
+on a dataset at hand, including the ML model,
+its hyperparameters, and other data processing steps.
+
+HPOs free the human expert from a tedious and error-prone, manual hyperparameter tuning process.
+
+As an example, in the famous `scikit-learn
+
+.. displayitem::
+ :header: Step 1: Implement an HPO component with the Lightning Works.
+ :description: Learn how it works under the hood
+ :col_css: col-md-4
+ :button_link: hpo_wo.html
+ :height: 180
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Step 2: Add the flow to your HPO component
+ :description: Learn how it works under the hood
+ :col_css: col-md-4
+ :button_link: hpo_wi.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/hpo/hpo_wi.rst b/docs/source-app/examples/hpo/hpo_wi.rst
new file mode 100644
index 0000000000..17dd971e9e
--- /dev/null
+++ b/docs/source-app/examples/hpo/hpo_wi.rst
@@ -0,0 +1,57 @@
+:orphan:
+
+##########################################
+Step 2: Add the flow to your HPO component
+##########################################
+
+**Audience:** Users who want to understand how to implement HPO training from scratch with Lightning.
+
+**Prereqs:** Level 17+
+
+----
+
+Thanks to the simplified version, you should have a good grasp on how to implement HPO with Optuna.
+
+As the :class:`~lightning_app.core.app.LightningApp` handles the Infinite Loop,
+it has been removed from within the run method of the HPORootFlow.
+
+However, the ``run`` method code is the same as the one defined above.
+
+.. literalinclude:: ../../../examples/app_hpo/app_wo_ui.py
+ :language: python
+
+The ``ObjectiveWork`` is sub-classing
+the built-in :class:`~lightning_app.components.python.TracerPythonScript`
+which enables launching scripts and more.
+
+.. literalinclude:: ../../../examples/app_hpo/objective.py
+ :language: python
+
+Finally, let's add the ``HiPlotFlow`` component to visualize our hyperparameter optimization.
+
+The metric and sampled parameters are added to the ``self.hi_plot.data`` list, enabling
+updates to the dashboard in near-realtime.
+
+.. literalinclude:: ../../../examples/app_hpo/app_wi_ui.py
+ :diff: ../../../examples/app_hpo/app_wo_ui.py
+
+Here is the associated code with the ``HiPlotFlow`` component.
+
+In the ``render_fn`` method, the state of the ``HiPlotFlow`` is passed.
+The ``state.data`` is accessed as it contains the metric and sampled parameters.
+
+.. literalinclude:: ../../../examples/app_hpo/hyperplot.py
+
+Run the HPO application with the following command:
+
+.. code-block:: console
+
+ $ lightning run app examples/app_hpo/app_wi_ui.py
+ INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+ {0: ..., 1: ..., ..., 5: ...}
+
+Here is what the UI looks like when launched:
+
+.. image:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/hpo_ui_2.gif
+ :width: 100 %
+ :alt: Alternative text
diff --git a/docs/source-app/examples/hpo/hpo_wo.rst b/docs/source-app/examples/hpo/hpo_wo.rst
new file mode 100644
index 0000000000..6a13ff253d
--- /dev/null
+++ b/docs/source-app/examples/hpo/hpo_wo.rst
@@ -0,0 +1,57 @@
+:orphan:
+
+###########################################################
+Step 1: Implement an HPO component with the Lightning Works
+###########################################################
+
+**Audience:** Users who want to understand how to implement HPO training from scratch.
+
+**Prereqs:** Level 17+
+
+----
+
+In the example below, we are emulating the Lightning Infinite Loop.
+
+We are assuming we have already defined an ``ObjectiveWork`` component which is responsible to run the objective method and track the metric through its state.
+
+.. literalinclude:: ./hpo.py
+ :language: python
+
+We are running ``TOTAL_TRIALS`` trials by series of ``SIMULTANEOUS_TRIALS`` trials.
+When starting, ``TOTAL_TRIALS`` ``ObjectiveWork`` are created.
+
+The entire code runs within an infinite loop as it would within Lightning.
+
+When iterating through the Works, if the current ``objective_work`` hasn't started,
+some new parameters are sampled from the Optuna Study with our custom distributions
+and then passed to run method of the ``objective_work``.
+
+The condition ``not objective_work.has_started`` will be ``False`` once ``objective_work.run()`` starts.
+
+Also, the second condition ``objective_work.has_told_study`` will be ``True`` when the metric
+is defined within the state of the Work and has been shared with the study.
+
+Finally, once the current ``SIMULTANEOUS_TRIALS`` have both registered their
+metric to the Optuna Study, simply increment ``NUM_TRIALS`` by ``SIMULTANEOUS_TRIALS`` to launch the next trials.
+
+Below, you can find the simplified version of the ``ObjectiveWork`` where the metric is randomly sampled using NumPy.
+
+In a realistic use case, the Work executes some user-defined code.
+
+.. literalinclude:: ./objective.py
+ :language: python
+
+Here are the logs produced when running the application above:
+
+.. code-block:: console
+
+ $ python docs/source-app/tutorials/hpo/hpo.py
+ INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+ # After you have clicked `run` on the UI.
+ [I 2022-03-01 12:32:50,050] A new study created in memory with name: ...
+ {0: 13.994859806481264, 1: 59.866743330127825, ..., 5: 94.65919769609225}
+
+The following animation shows how this application works in the cloud:
+
+.. image:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/hpo.gif
+ :alt: Animation showing how to HPO works UI in a distributed manner.
diff --git a/docs/source-app/examples/hpo/lightning_hpo.rst b/docs/source-app/examples/hpo/lightning_hpo.rst
new file mode 100644
index 0000000000..b1e2f11d39
--- /dev/null
+++ b/docs/source-app/examples/hpo/lightning_hpo.rst
@@ -0,0 +1,99 @@
+:orphan:
+
+################################
+Re-use an existing HPO component
+################################
+
+**Audience:** Users who want to easily get started with HPO training.
+
+**Prereqs:** Level 8+
+
+----
+
+*********************
+Install Lightning HPO
+*********************
+
+Lightning HPO provides a Pythonic implementation for Scalable Hyperparameter Tuning
+and relies on Optuna for providing state-of-the-art sampling hyper-parameters algorithms and efficient trial pruning strategies.
+
+Find the `Lightning Sweeper App
+
+.. displayitem::
+ :header: Re-use an existing HPO component
+ :description: Learn how to use Lightning HPO with your app.
+ :col_css: col-md-4
+ :button_link: lightning_hpo.html
+ :height: 180
+ :tag: Basic
+
+.. displayitem::
+ :header: Implement an HPO component from scratch
+ :description: Learn how it works under the hood
+ :col_css: col-md-4
+ :button_link: build_from_scratch.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/model_server_app/locust_component.py b/docs/source-app/examples/model_server_app/locust_component.py
new file mode 100644
index 0000000000..70b342facb
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/locust_component.py
@@ -0,0 +1,43 @@
+import os
+import subprocess
+
+from lightning import LightningWork
+from lightning.app.utilities.packaging.build_config import BuildConfig
+
+
+class Locust(LightningWork):
+ def __init__(self, num_users: int = 100):
+ """This component checks the performance of a server. The server url is passed to its run method.
+
+ Arguments:
+ num_users: Number of users emulated by Locust
+ """
+ # Note: Using the default port 8089 of Locust.
+ super().__init__(
+ port=8089,
+ parallel=True,
+ cloud_build_config=BuildConfig(requirements=["locust"]),
+ )
+ self.num_users = num_users
+
+ def run(self, load_tested_url: str):
+ # 1: Create the locust command line.
+ cmd = " ".join(
+ [
+ "locust",
+ "--master-host",
+ str(self.host),
+ "--master-port",
+ str(self.port),
+ "--host",
+ str(load_tested_url),
+ "-u",
+ str(self.num_users),
+ ]
+ )
+ # 2: Create another process with locust
+ process = subprocess.Popen(cmd, cwd=os.path.dirname(__file__), shell=True)
+
+ # 3: Wait for the process to finish. As locust is a server,
+ # this waits infinitely or if killed.
+ process.wait()
diff --git a/docs/source-app/examples/model_server_app/locustfile.py b/docs/source-app/examples/model_server_app/locustfile.py
new file mode 100644
index 0000000000..198d6de6cb
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/locustfile.py
@@ -0,0 +1,41 @@
+from locust import FastHttpUser, task
+from sklearn import datasets
+from sklearn.model_selection import train_test_split
+
+
+class HelloWorldUser(FastHttpUser):
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+ self._prepare_inference_request()
+
+ @task
+ def predict(self):
+ self.client.post(
+ "/v2/models/mnist-svm/versions/v0.0.1/infer",
+ json=self.inference_request,
+ )
+
+ def _prepare_inference_request(self):
+ # The digits dataset
+ digits = datasets.load_digits()
+
+ # To apply a classifier on this data,
+ # we need to flatten the image, to
+ # turn the data in a (samples, feature) matrix:
+ n_samples = len(digits.images)
+ data = digits.images.reshape((n_samples, -1))
+
+ # Split data into train and test subsets
+ _, X_test, _, _ = train_test_split(data, digits.target, test_size=0.5, shuffle=False)
+
+ x_0 = X_test[0:1]
+ self.inference_request = {
+ "inputs": [
+ {
+ "name": "predict",
+ "shape": x_0.shape,
+ "datatype": "FP32",
+ "data": x_0.tolist(),
+ }
+ ]
+ }
diff --git a/docs/source-app/examples/model_server_app/model_server.py b/docs/source-app/examples/model_server_app/model_server.py
new file mode 100644
index 0000000000..1b914b0194
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/model_server.py
@@ -0,0 +1,90 @@
+import json
+import subprocess
+
+from lightning import LightningWork
+from lightning.app.storage import Path
+from lightning.app.utilities.packaging.build_config import BuildConfig
+
+# ML_SERVER_URL = https://github.com/SeldonIO/MLServer
+
+
+class MLServer(LightningWork):
+
+ """This components uses SeldonIO MLServer library.
+
+ The model endpoint: /v2/models/{MODEL_NAME}/versions/{VERSION}/infer.
+
+ Arguments:
+ name: The name of the model for the endpoint.
+ implementation: The model loader class.
+ Example: "mlserver_sklearn.SKLearnModel".
+ Learn more here: $ML_SERVER_URL/tree/master/runtimes
+ workers: Number of server worker.
+ """
+
+ def __init__(
+ self,
+ name: str,
+ implementation: str,
+ workers: int = 1,
+ **kwargs,
+ ):
+ super().__init__(
+ parallel=True,
+ cloud_build_config=BuildConfig(
+ requirements=["mlserver", "mlserver-sklearn"],
+ ),
+ **kwargs,
+ )
+ # 1: Collect the config's.
+ self.settings = {
+ "debug": True,
+ "parallel_workers": workers,
+ }
+ self.model_settings = {
+ "name": name,
+ "implementation": implementation,
+ }
+ # 2: Keep track of latest version
+ self.version = 1
+
+ def run(self, model_path: Path):
+ """The model is downloaded when the run method is invoked.
+
+ Arguments:
+ model_path: The path to the trained model.
+ """
+ # 1: Use the host and port at runtime so it works in the cloud.
+ # $ML_SERVER_URL/blob/master/mlserver/settings.py#L50
+ if self.version == 1:
+ # TODO: Reload the next version model of the model.
+
+ self.settings.update({"host": self.host, "http_port": self.port})
+
+ with open("settings.json", "w") as f:
+ json.dump(self.settings, f)
+
+ # 2. Store the model-settings
+ # $ML_SERVER_URL/blob/master/mlserver/settings.py#L120
+ self.model_settings["parameters"] = {
+ "version": f"v0.0.{self.version}",
+ "uri": str(model_path.absolute()),
+ }
+ with open("model-settings.json", "w") as f:
+ json.dump(self.model_settings, f)
+
+ # 3. Launch the Model Server
+ subprocess.Popen("mlserver start .", shell=True)
+
+ # 4. Increment the version for the next time run is called.
+ self.version += 1
+
+ else:
+ # TODO: Load the next model and unload the previous one.
+ pass
+
+ def alive(self):
+ # Current hack, when the url is available,
+ # the server is up and running.
+ # This would be cleaned out and automated.
+ return self.url != ""
diff --git a/docs/source-app/examples/model_server_app/model_server.rst b/docs/source-app/examples/model_server_app/model_server.rst
new file mode 100644
index 0000000000..b1daa00d42
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/model_server.rst
@@ -0,0 +1,48 @@
+:orphan:
+
+***********************************
+2. Build the Model Server Component
+***********************************
+
+In the code below, we use `MLServer
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: 1. Build a Train Component
+ :description: Train a model and store its checkpoints with SKlearn
+ :col_css: col-md-4
+ :button_link: train.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 2. Build a Model Server Component
+ :description: Use MLServer to server your models
+ :col_css: col-md-4
+ :button_link: model_server.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 4. Putting everything together.
+ :description: Ensemble the components together and run the app
+ :col_css: col-md-4
+ :button_link: putting_everything_together.html
+ :height: 150
+ :tag: basic
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/model_server_app/model_server_app.rst b/docs/source-app/examples/model_server_app/model_server_app.rst
new file mode 100644
index 0000000000..09d3619929
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/model_server_app.rst
@@ -0,0 +1,15 @@
+:orphan:
+
+.. _model_server_example:
+
+####################
+Build a Model Server
+####################
+
+**Audience:** Users who want to serve their trained models.
+
+**Prerequisite**: Reach :ref:`level 16+
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: 1. Build a Train Component
+ :description: Train a model and store its checkpoints with SKlearn
+ :col_css: col-md-4
+ :button_link: train.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 3. Build a Load Testing Component
+ :description: Use Locust to test your model servers
+ :col_css: col-md-4
+ :button_link: load_testing.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 4. Putting everything together.
+ :description: Ensemble the components together and run the app
+ :col_css: col-md-4
+ :button_link: putting_everything_together.html
+ :height: 150
+ :tag: basic
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/model_server_app/putting_everything_together.rst b/docs/source-app/examples/model_server_app/putting_everything_together.rst
new file mode 100644
index 0000000000..c11a5289d3
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/putting_everything_together.rst
@@ -0,0 +1,80 @@
+:orphan:
+
+******************************
+4. Putting everything together
+******************************
+
+In the code below, we put together the **TrainWork**, the **MLServer** and the **Locust** components in an ``app.py`` file.
+
+.. literalinclude:: ./app.py
+
+
+***********
+Run the App
+***********
+
+To run the app, simply open a terminal and execute this command:
+
+.. code-block:: bash
+
+ lightning run app docs/source-app/examples/model_deploy_app/app.py
+
+Here is a gif of the UI.
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/ml_server_2.gif
+
+.. raw:: html
+
+
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: 1. Build a Train Component
+ :description: Train a model and store its checkpoints with SKlearn
+ :col_css: col-md-4
+ :button_link: train.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 2. Build a Model Server Component
+ :description: Use MLServer to server your models
+ :col_css: col-md-4
+ :button_link: model_server.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 3. Build a Load Testing Component
+ :description: Use Locust to test your model servers
+ :col_css: col-md-4
+ :button_link: load_testing.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 4. Putting everything together.
+ :description: Ensemble the components together and run the app
+ :col_css: col-md-4
+ :button_link: putting_everything_together.html
+ :height: 150
+ :tag: basic
+
+.. raw:: html
+
+
+ + +Congrats, you have finished the **Build a Model Server** example ! + +---- + +****************** +Find more examples +****************** + +.. raw:: html + +
+
diff --git a/docs/source-app/examples/model_server_app/train.py b/docs/source-app/examples/model_server_app/train.py
new file mode 100644
index 0000000000..f3342b9f24
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/train.py
@@ -0,0 +1,42 @@
+import joblib
+from sklearn import datasets, svm
+from sklearn.model_selection import train_test_split
+
+from lightning import LightningWork
+from lightning.app.storage import Path
+
+
+class TrainModel(LightningWork):
+
+ """This component trains a Sklearn SVC model on digits dataset."""
+
+ def __init__(self):
+ super().__init__()
+ # 1: Add element to the state.
+ self.best_model_path = None
+
+ def run(self):
+ # 2: Load the Digits
+ digits = datasets.load_digits()
+
+ # 3: To apply a classifier on this data,
+ # we need to flatten the image, to
+ # turn the data in a (samples, feature) matrix:
+ n_samples = len(digits.images)
+ data = digits.images.reshape((n_samples, -1))
+
+ # 4: Create a classifier: a support vector classifier
+ classifier = svm.SVC(gamma=0.001)
+
+ # 5: Split data into train and test subsets
+ X_train, _, y_train, _ = train_test_split(data, digits.target, test_size=0.5, shuffle=False)
+
+ # 6: We learn the digits on the first half of the digits
+ classifier.fit(X_train, y_train)
+
+ # 7: Save the Sklearn model with `joblib`.
+ model_file_name = "mnist-svm.joblib"
+ joblib.dump(classifier, model_file_name)
+
+ # 8: Keep a reference the the generated model.
+ self.best_model_path = Path("mnist-svm.joblib")
diff --git a/docs/source-app/examples/model_server_app/train.rst b/docs/source-app/examples/model_server_app/train.rst
new file mode 100644
index 0000000000..4e828872f4
--- /dev/null
+++ b/docs/source-app/examples/model_server_app/train.rst
@@ -0,0 +1,49 @@
+:orphan:
+
+****************************
+1. Build the Train Component
+****************************
+
+In the code below, we create a work which trains a simple `SVC
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: Build a DAG
+ :description: Create a dag pipeline
+ :col_css: col-md-4
+ :button_link: ../dag/dag.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a File Server
+ :description: Train multiple models with different parameters
+ :col_css: col-md-4
+ :button_link: ../file_server/file_server.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a Github Repo Script Runner
+ :description: Run code from the internet in the cloud
+ :col_css: col-md-4
+ :button_link: ../github_repo_runner/github_repo_runner.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Build a HPO Sweeper
+ :description: Train multiple models with different parameters
+ :col_css: col-md-4
+ :button_link: ../hpo/hpo.html
+ :height: 150
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/examples/research_demo_app.rst b/docs/source-app/examples/research_demo_app.rst
index cb74ebcf3d..90276f9b95 100644
--- a/docs/source-app/examples/research_demo_app.rst
+++ b/docs/source-app/examples/research_demo_app.rst
@@ -1,3 +1,5 @@
+:orphan:
+
#########################
Build a Research Demo App
#########################
diff --git a/docs/source-app/get_started/add_an_interactive_demo.rst b/docs/source-app/get_started/add_an_interactive_demo.rst
new file mode 100644
index 0000000000..98e6c3fd8a
--- /dev/null
+++ b/docs/source-app/get_started/add_an_interactive_demo.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+#######################
+Add an Interactive Demo
+#######################
+
+.. _add_an_interactive_Demo:
+
+**Required background:** Basic Python familiarity and complete the :ref:`install` guide.
+
+**Goal:** We'll walk you through the 4 key steps to run a Lightning App that trains and demos a model.
+
+.. join_slack::
+ :align: left
+
+----
+
+.. include:: go_beyond_training_content.rst
diff --git a/docs/source-app/get_started/build_model.rst b/docs/source-app/get_started/build_model.rst
new file mode 100644
index 0000000000..34e7b26bc3
--- /dev/null
+++ b/docs/source-app/get_started/build_model.rst
@@ -0,0 +1,76 @@
+:orphan:
+
+.. _build_model:
+
+#######################
+Build and Train a Model
+#######################
+
+**Required background:** Basic Python familiarity and complete the :ref:`install` guide.
+
+**Goal:** We'll walk you through the creation of a model using PyTorch Lightning.
+
+.. join_slack::
+ :align: left
+
+----
+
+*********************************
+A simple PyTorch Lightning script
+*********************************
+
+Let's assume you already have a folder with those two files.
+
+.. code-block:: bash
+
+ pl_project/
+ train.py # your own script to train your models
+ requirements.txt # your python requirements.
+
+If you don't, simply create a ``pl_project`` folder with those two files and add the following `PyTorch Lightning
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: 2. Build a Model Server Component
+ :description: Use MLServer to server your models
+ :col_css: col-md-4
+ :button_link: model_server.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 3. Build a Load Testing Component
+ :description: Use Locust to test your model servers
+ :col_css: col-md-4
+ :button_link: load_testing.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: 4. Putting everything together.
+ :description: Ensemble the components together and run the app
+ :col_css: col-md-4
+ :button_link: putting_everything_together.html
+ :height: 150
+ :tag: basic
+
+.. raw:: html
+
+
+ +
+
diff --git a/docs/source-app/get_started/go_beyond_training.rst b/docs/source-app/get_started/go_beyond_training.rst
new file mode 100644
index 0000000000..eade993e59
--- /dev/null
+++ b/docs/source-app/get_started/go_beyond_training.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+################################
+Start from an ML system template
+################################
+
+.. _go_beyond_training:
+
+**Required background:** Basic Python familiarity and complete the :ref:`install` guide.
+
+**Goal:** We'll walk you through the 4 key steps to run a Lightning App that trains and demos a model.
+
+.. join_slack::
+ :align: left
+
+----
+
+.. include:: go_beyond_training_content.rst
diff --git a/docs/source-app/pages/lightning_apps_intro.rst b/docs/source-app/get_started/go_beyond_training_content.rst
similarity index 64%
rename from docs/source-app/pages/lightning_apps_intro.rst
rename to docs/source-app/get_started/go_beyond_training_content.rst
index ba3c962f16..a471e91d85 100644
--- a/docs/source-app/pages/lightning_apps_intro.rst
+++ b/docs/source-app/get_started/go_beyond_training_content.rst
@@ -1,63 +1,23 @@
-.. toctree::
- :maxdepth: 1
- :hidden:
+************************************************
+The *Train & Demo PyTorch Lightning* Application
+************************************************
- ../workflows/extend_app
- ../workflows/build_lightning_component/index
- ../glossary/lightning_app_overview/index
- ../workflows/run_on_private_cloud
+Find the *Train & Demo PyTorch Lightning* application in the `Lightning.ai App Gallery
+
+.. displayitem::
+ :header: Evolve a Model into an ML System
+ :description: Develop an App to train a model in the cloud
+ :col_css: col-md-6
+ :button_link: training_with_apps.html
+ :height: 180
+
+.. displayitem::
+ :header: Start from a Template ML System
+ :description: Learn about Apps, from a template.
+ :col_css: col-md-6
+ :button_link: go_beyond_training.html
+ :height: 180
+
+.. raw:: html
+
+
+ + +
+
-| +In the steps below, we are going to show you how to build this application. -Lightning Apps are: - -- cloud agnostic -- fault-tolerant -- production ready -- locally debuggable -- and much more - -.. join_slack:: - :align: left - :margin: 20 - - ----- - -******************* -Who can build apps? -******************* -Anyone who knows Python can build a Lightning app, even without ML experience. +Here are `the entire App's code
.. displayitem::
- :header: Add components to your app
- :description: Expand your app by adding components.
+ :header: Add components to your App
+ :description: Expand your App by adding components.
:col_css: col-md-4
:button_link: ../workflows/extend_app.html
:height: 180
@@ -437,22 +380,22 @@ Depending on your use case, you might want to check one of these out next.
:height: 180
.. displayitem::
- :header: Explore more apps
+ :header: Explore more Apps
:description: Explore more apps for inspiration.
:col_css: col-md-4
:button_link: https://lightning.ai/apps
:height: 180
.. displayitem::
- :header: How it works under the hood
+ :header: Under the hood
:description: Explore how it works under the hood.
:col_css: col-md-4
- :button_link: core_api/lightning_app/index.html
+ :button_link: ../core_api/lightning_app/index.html
:height: 180
-.. displayitem::workflo
+.. displayitem::
:header: Run on your private cloud
- :description: Run lightning apps on your private VPC or on-prem.
+ :description: Run Lightning Apps on your private VPC or on-prem.
:button_link: ../workflows/run_on_private_cloud.html
:col_css: col-md-4
:height: 180
diff --git a/docs/source-app/get_started/jumpstart_from_app_gallery.rst b/docs/source-app/get_started/jumpstart_from_app_gallery.rst
new file mode 100644
index 0000000000..998fce9a93
--- /dev/null
+++ b/docs/source-app/get_started/jumpstart_from_app_gallery.rst
@@ -0,0 +1,123 @@
+:orphan:
+
+#####################################
+Start from Ready-to-Run Template Apps
+#####################################
+
+.. _jumpstart_from_app_gallery:
+
+Anyone can build Apps for their own use cases and promote them on the `App Gallery `_.
+
+In return, you can benefit from the work of others and get started faster by re-using a ready-to-run App close to your own use case.
+
+.. join_slack::
+ :align: left
+
+----
+
+*************
+User Workflow
+*************
+
+#. Visit the `App Gallery `_ and look for an App close to your own use case.
+
+ .. raw:: html
+
+
+ +#. If **Launch** is available, it means the App is live and ready to be used! Take it for a spin. + + .. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/launch_button.png + :alt: Launch Button on lightning.ai + :width: 100 % + +#. By clicking **Clone & Run**, a copy of the App is added to your account and an instance starts running. + + .. raw:: html + +
+ + +#. If you found an App that matches what you need, move to **step 5**! Otherwise, go back to **step 1**. + + .. raw:: html + +
+ +#. Copy the installation command (optionally from the clipboard on the right). + + .. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/install_command.png + :alt: Install command on lightning.ai + :width: 100 % + +#. Copy the command to your local terminal. + + .. code-block:: bash + + lightning install app lightning/hackernews-app + +#. Go through the installation steps. + + .. raw:: html + +
+ + +#. Run the App locally. + + .. code-block:: bash + + cd LAI-Hackernews-App + lightning run app app.py + + .. raw:: html + +
+ + +#. Open the code with your favorite IDE, modify it, and run it back in the cloud. + + .. raw:: html + +
+ +
+ +---- + +********** +Next Steps +********** + +.. raw:: html + +
diff --git a/docs/source-app/get_started/jumpstart_from_component_gallery.rst b/docs/source-app/get_started/jumpstart_from_component_gallery.rst new file mode 100644 index 0000000000..5d0a0e434a --- /dev/null +++ b/docs/source-app/get_started/jumpstart_from_component_gallery.rst @@ -0,0 +1,155 @@ +:orphan: + +######################################## +Add Component made by others to your App +######################################## + +.. _jumpstart_from_component_gallery: + +Anyone can build components for their own use case and promote them on the `Component Gallery`_.
+
+In return, you can benefit from the work of others and add new functionalities to your Apps with minimal effort.
+
+.. join_slack::
+ :align: left
+
+----
+
+*************
+User Workflow
+*************
+
+#. Visit the `Component Gallery `_ and look for a Component close to something you want to do.
+
+ .. raw:: html
+
+
+ +#. Check out the code for inspiration or simply install the component from PyPi and use it. + +---- + +************* +Success Story +************* + +The default `Train and Demo Application`_ trains a PyTorch Lightning
+model and then starts a demo with `Gradio `_
+from browsing the `Component Gallery `_ and decided to give it a spin after checking the associated
+`Github Repository `_.
+
+Once ``lightning_hpo`` installed, they improved the default App by easily adding HPO support to their project.
+
+Here is the resulting App. It is almost the same code, but it's way more powerful now!
+
+This is the power of `lightning.ai
diff --git a/docs/source-app/get_started/lightning_apps_intro.rst b/docs/source-app/get_started/lightning_apps_intro.rst new file mode 100644 index 0000000000..bcbc9d8dbf --- /dev/null +++ b/docs/source-app/get_started/lightning_apps_intro.rst @@ -0,0 +1,14 @@ +############################ +Lightning Apps in 15 minutes +############################ + +**Required background:** Basic Python familiarity. + +**Goal:** Guide you to develop your first Lightning App or use an existing App from the `Apps Gallery`_.
+
+.. join_slack::
+ :align: left
+
+----
+
+.. include:: go_beyond_training_content.rst
diff --git a/docs/source-app/get_started/training_with_apps.rst b/docs/source-app/get_started/training_with_apps.rst
new file mode 100644
index 0000000000..a7061cae56
--- /dev/null
+++ b/docs/source-app/get_started/training_with_apps.rst
@@ -0,0 +1,136 @@
+:orphan:
+
+################################
+Evolve a model into an ML system
+################################
+
+.. _convert_pl_to_app:
+
+**Required background:** Basic Python familiarity and complete the :ref:`build_model` guide.
+
+**Goal:** We'll walk you through the two key steps to build your first Lightning App from your existing Pytorch Lightning scripts.
+
+.. join_slack::
+ :align: left
+
+----
+
+*******************
+Training and beyond
+*******************
+
+With `PyTorch Lightning `_, we abstracted distributed training and hardware, by organizing PyTorch code.
+With `Lightning Apps `_, we unified the local and cloud experience while abstracting infrastructure.
+
+By using `PyTorch Lightning `_ and `Lightning Apps `_
+together, a completely new world of possibilities emerges.
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/pl_to_app_4.png
+ :alt: From PyTorch Lightning to Lightning App
+ :width: 100 %
+
+----
+
+******************************************
+1. Write an App to run the train.py script
+******************************************
+
+This article continues where the :ref:`build_model` guide finished.
+
+Create an additional file ``app.py`` in the ``pl_project`` folder as follows:
+
+.. code-block:: bash
+
+ pl_project/
+ app.py
+ train.py
+ requirements.txt
+
+Inside the ``app.py`` file, add the following code.
+
+.. literalinclude:: ../code_samples/convert_pl_to_app/app.py
+
+This App runs the Pytorch Lightning script contained in the ``train.py`` file using the powerful :class:`~lightning_app.components.python.tracer.TracerPythonScript` component. This is really worth checking out!
+
+----
+
+************************************************
+2. Run the train.py file locally or in the cloud
+************************************************
+
+First, go to the ``pl_folder`` folder from the local terminal and install the requirements.
+
+.. code-block:: bash
+
+ cd pl_folder
+ pip install -r requirements.txt
+
+To run your app, copy the following command to your local terminal:
+
+.. code-block:: bash
+
+ lightning run app app.py
+
+Simply add ``--cloud`` to run this application in the cloud with a GPU machine 🤯
+
+.. code-block:: bash
+
+ lightning run app app.py --cloud
+
+
+Congratulations! Now, you know how to run a `PyTorch Lightning `_ script with Lightning Apps.
+
+Lightning Apps can make your ML system way more powerful, keep reading to learn how.
+
+----
+
+**********
+Next Steps
+**********
+
+.. raw:: html
+
+ `_ created:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/example_app.py
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/example_app.py
and the App.tsx file also created by `lightning init react-ui `_:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/ui/src/App.tsx
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/ui/src/App.tsx
----
@@ -31,13 +31,13 @@ To change the Lightning app from the React app, use `updateLightningState`.
In this example, when you press **Start printing** in the React UI, it toggles
the `react_ui.vars.should_print`:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/ui/src/App.tsx
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/ui/src/App.tsx
:emphasize-lines: 20, 21, 23
By changing that variable in the Lightning app state, it sets **react_ui.should_print** to True, which enables the
Lightning app to print:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/example_app.py
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/example_app.py
:emphasize-lines: 10, 22
----
@@ -49,10 +49,10 @@ To change the React app from the Lightning app, use the values from the `lightni
In this example, when the `react_ui.counter`` increaes in the Lightning app:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/example_app.py
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/example_app.py
:emphasize-lines: 18, 24
The React UI updates the text on the screen to reflect the count
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/ui/src/App.tsx
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/ui/src/App.tsx
:emphasize-lines: 15
diff --git a/docs/source-app/workflows/add_web_ui/react/connect_react_and_lightning.rst b/docs/source-app/workflows/add_web_ui/react/connect_react_and_lightning.rst
index 7b4b67583e..c1c0c5e201 100644
--- a/docs/source-app/workflows/add_web_ui/react/connect_react_and_lightning.rst
+++ b/docs/source-app/workflows/add_web_ui/react/connect_react_and_lightning.rst
@@ -15,11 +15,11 @@ Example code
To illustrate how to connect a React app and a lightning App, we'll be using the `example_app.py` file
which `lightning init react-ui `_ created:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/example_app.py
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/example_app.py
and the App.tsx file also created by `lightning init react-ui `_:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/ui/src/App.tsx
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/ui/src/App.tsx
----
@@ -28,7 +28,7 @@ Connect the component to the react UI
*************************************
The first step is to connect the dist folder of the react app using `StaticWebFrontend`:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/example_app.py
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/example_app.py
:emphasize-lines: 13
the dist folder must contain an index.html file which is generated by the compilating command `yarn build` which
@@ -42,7 +42,7 @@ Connect component to the root flow
Next, connect your component to the root flow. Display the react app on the tab of your choice
using `configure_layout`:
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/example_app.py
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/example_app.py
:emphasize-lines: 19, 27
----
@@ -59,7 +59,7 @@ At this point, the React app will render in the Lightning app. Test it out!
However, to make powerful React+Lightning apps, you must also connect the Lightning App state to the react app.
These lines enable two-way communication between the react app and the Lightning app.
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/ui/src/App.tsx
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/ui/src/App.tsx
:emphasize-lines: 10, 13
----
@@ -69,7 +69,7 @@ Component vs App
****************
Notice that in this guide, we connected a single react app to a single component.
-.. literalinclude:: ../../../../../lightning_app/cli/react-ui-template/example_app.py
+.. literalinclude:: ../../../../../src/lightning_app/cli/react-ui-template/example_app.py
:emphasize-lines: 6-13
You can use this single react app for the FULL Lightning app, or you can specify a React app for EACH component.
@@ -77,20 +77,20 @@ You can use this single react app for the FULL Lightning app, or you can specify
.. code:: python
:emphasize-lines: 5, 9, 18-20
- import lightning_app as la
+ import lightning as L
- class ComponentA(lapp.LightningFlow):
+ class ComponentA(L.LightningFlow):
def configure_layout(self):
- return lapp.frontend.StaticWebFrontend(Path(__file__).parent / "react_app_1/dist")
+ return L.frontend.StaticWebFrontend(Path(__file__).parent / "react_app_1/dist")
- class ComponentB(lapp.LightningFlow):
+ class ComponentB(L.LightningFlow):
def configure_layout(self):
- return lapp.frontend.StaticWebFrontend(Path(__file__).parent / "react_app_2/dist")
+ return L.frontend.StaticWebFrontend(Path(__file__).parent / "react_app_2/dist")
- class HelloLitReact(lapp.LightningFlow):
+ class HelloLitReact(L.LightningFlow):
def __init__(self):
super().__init__()
self.react_app_1 = ComponentA()
@@ -102,6 +102,6 @@ You can use this single react app for the FULL Lightning app, or you can specify
return tab_1, tab_2
- app = lapp.LightningApp(HelloLitReact())
+ app = L.LightningApp(HelloLitReact())
This is a powerful idea that allows each Lightning component to have a self-contained web UI.
diff --git a/docs/source-app/workflows/add_web_ui/react/index.rst b/docs/source-app/workflows/add_web_ui/react/index.rst
index 1a0463e105..ba0f8d97d6 100644
--- a/docs/source-app/workflows/add_web_ui/react/index.rst
+++ b/docs/source-app/workflows/add_web_ui/react/index.rst
@@ -1,3 +1,5 @@
+:orphan:
+
.. toctree::
:maxdepth: 1
:hidden:
diff --git a/docs/source-app/workflows/add_web_ui/streamlit/basic.rst b/docs/source-app/workflows/add_web_ui/streamlit/basic.rst
index 920bd8d84a..464b558032 100644
--- a/docs/source-app/workflows/add_web_ui/streamlit/basic.rst
+++ b/docs/source-app/workflows/add_web_ui/streamlit/basic.rst
@@ -38,20 +38,17 @@ First **create a file named app.py** with the app content:
.. code:: python
# app.py
- import lightning_app as la
+ import lightning as L
import streamlit as st
-
def your_streamlit_app(lightning_app_state):
- st.write("hello world")
+ st.write('hello world')
-
- class LitStreamlit(lapp.LightningFlow):
+ class LitStreamlit(L.LightningFlow):
def configure_layout(self):
- return lapp.frontend.StreamlitFrontend(render_fn=your_streamlit_app)
+ return L.frontend.StreamlitFrontend(render_fn=your_streamlit_app)
-
- class LitApp(lapp.LightningFlow):
+ class LitApp(L.LightningFlow):
def __init__(self):
super().__init__()
self.lit_streamlit = LitStreamlit()
@@ -60,8 +57,7 @@ First **create a file named app.py** with the app content:
tab1 = {"name": "home", "content": self.lit_streamlit}
return tab1
-
- app = lapp.LightningApp(LitApp())
+ app = L.LightningApp(LitApp())
add "streamlit" to a requirements.txt file:
@@ -78,13 +74,13 @@ Run the app
***********
Run the app locally to see it!
-.. code:: bash
+.. code:: python
lightning run app app.py
Now run it on the cloud as well:
-.. code:: bash
+.. code:: python
lightning run app app.py --cloud
@@ -105,9 +101,8 @@ First, find the streamlit app you want to integrate. In this example, that app l
import streamlit as st
-
def your_streamlit_app():
- st.write("hello world")
+ st.write('hello world')
Refer to the `Streamlit documentation `_.
-
-Once you find the app you want, press "Get" to see it running on the cloud, then download the code
-and change what you want!
-
-----
-
-******************
-Build from scratch
-******************
-If you didn't find an app similar to the one you need, simply create a file named **app.py** with these contents:
-
-.. code:: bash
-
- import lightning_app as la
-
- class WordComponent(lapp.LightningWork):
- def __init__(self, word):
- super().__init__()
- self.word = word
- def run(self):
- print(self.word)
-
-
- class LitApp(lapp.LightningFlow):
- def __init__(self) -> None:
- super().__init__()
- self.hello = WordComponent('hello')
- self.world = WordComponent('world')
-
- def run(self):
- print('this is a simple Lightning app, make a better app!')
- self.hello.run()
- self.world.run()
-
- app = lapp.LightningApp(LitApp())
-
-----
-
-Run the app
-^^^^^^^^^^^
-Run the app locally:
-
-.. code:: bash
-
- lightning run app app.py
-
-Run the app on the cloud:
-
-.. code:: bash
-
- lightning run app app.py --cloud
-
-----
-
-*********************
-Build from a template
-*********************
-If you didn't find an app similar to the one you need (in the `Lightning App gallery `_), another option is to start from a template.
-The lightning CLI can generate a template with built-in testing that can be easily published to the
-Lightning app gallery.
-
-Generate it with our template generator:
-
-.. code:: bash
-
- lightning init app your-app-name
-
-You'll see a print-out like this:
-
-.. code:: bash
-
- ➜ lightning init app your-app-name
-
- /Users/Your/Current/dir/your-app-name
- INFO: laying out app template at /Users/Your/Current/dir/your-app-name
- INFO:
- Lightning app template created!
- /Users/Your/Current/dir/your-app-name
-
- run your app with:
- lightning run app your-app-name/your_app_name/app.py
-
- run it on the cloud to share with your collaborators:
- lightning run app your-app-name/your_app_name/app.py --cloud
-
-----
-
-Modify the template
-^^^^^^^^^^^^^^^^^^^
-The command above generates an app file like this:
-
-.. code:: python
-
- from your_app_name import ComponentA, ComponentB
-
- import lightning_app as la
-
-
- class LitApp(lapp.LightningFlow):
- def __init__(self) -> None:
- super().__init__()
- self.component_a = ComponentA()
- self.component_b = ComponentB()
-
- def run(self):
- self.component_a.run()
- self.component_b.run()
-
-
- app = lapp.LightningApp(LitApp())
-
-Now you can add your own components as you wish!
+.. include:: from_scratch_content.rst
diff --git a/docs/source-app/workflows/build_lightning_app/from_scratch_content.rst b/docs/source-app/workflows/build_lightning_app/from_scratch_content.rst
new file mode 100644
index 0000000000..91e7fea93e
--- /dev/null
+++ b/docs/source-app/workflows/build_lightning_app/from_scratch_content.rst
@@ -0,0 +1,121 @@
+
+**************
+WAIT!
+**************
+Before you build a Lightning App from scratch, see if you can find an app that is similar to what you need
+in the `Lightning App Gallery `_.
+
+Once you find the Lightning App you want, press "Clone & Run" to see it running on the cloud, then download the code
+and change what you want!
+
+----
+
+******************
+Build from scratch
+******************
+If you didn't find a Lightning App similar to the one you need, simply create a file named **app.py** with these contents:
+
+.. code:: python
+
+ import lightning as L
+
+
+ class WordComponent(L.LightningWork):
+ def __init__(self, word):
+ super().__init__()
+ self.word = word
+
+ def run(self):
+ print(self.word)
+
+
+ class LitApp(L.LightningFlow):
+ def __init__(self) -> None:
+ super().__init__()
+ self.hello = WordComponent("hello")
+ self.world = WordComponent("world")
+
+ def run(self):
+ print("This is a simple Lightning app, make a better app!")
+ self.hello.run()
+ self.world.run()
+
+
+ app = L.LightningApp(LitApp())
+
+----
+
+Run the Lightning App
+^^^^^^^^^^^^^^^^^^^^^
+Run the Lightning App locally:
+
+.. code:: bash
+
+ lightning run app app.py
+
+Run the Lightning App on the cloud:
+
+.. code:: bash
+
+ lightning run app app.py --cloud
+
+----
+
+*************************************
+Build a Lightning App from a template
+*************************************
+If you didn't find an Lightning App similar to the one you need (in the `Lightning App gallery `_), another option is to start from a template.
+The Lightning CLI can generate a template with built-in testing that can be easily published to the
+Lightning App Gallery.
+
+Generate a Lightning App with our template generator:
+
+.. code:: bash
+
+ lightning init app your-app-name
+
+You'll see a print-out like this:
+
+.. code:: bash
+
+ ➜ lightning init app your-app-name
+
+ /Users/Your/Current/dir/your-app-name
+ INFO: laying out app template at /Users/Your/Current/dir/your-app-name
+ INFO:
+ Lightning app template created!
+ /Users/Your/Current/dir/your-app-name
+
+ run your app with:
+ lightning run app your-app-name/your_app_name/app.py
+
+ run it on the cloud to share with your collaborators:
+ lightning run app your-app-name/your_app_name/app.py --cloud
+
+----
+
+Modify the Lightning App template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The command above generates a Lightning App file like this:
+
+.. code:: python
+
+ from your_app_name import ComponentA, ComponentB
+
+ import lightning as L
+
+
+ class LitApp(L.LightningFlow):
+ def __init__(self) -> None:
+ super().__init__()
+ self.component_a = ComponentA()
+ self.component_b = ComponentB()
+
+ def run(self):
+ self.component_a.run()
+ self.component_b.run()
+
+
+ app = L.LightningApp(LitApp())
+
+Now you can add your own components as you wish!
diff --git a/docs/source-app/workflows/build_lightning_component/basic.rst b/docs/source-app/workflows/build_lightning_component/basic.rst
index 37099a3a6f..b72b9147e2 100644
--- a/docs/source-app/workflows/build_lightning_component/basic.rst
+++ b/docs/source-app/workflows/build_lightning_component/basic.rst
@@ -1,205 +1,8 @@
-###################################
-Build a Lightning component (basic)
-###################################
+###########################
+Build a Lightning component
+###########################
**Audience:** Users who want to build a Lightning component.
----
-*******************************
-Why should I build a component?
-*******************************
-Lightning Components break up complex systems into modular components. The first obvious benefit is that components
-can be reused across other apps. This means you can build once, test it and forget it.
-
-As a researcher it also means that your code can be taken to production without needing a team of engineers to help
-productionize it.
-
-As a machine learning engineer, it means that your cloud system is:
-
-- fault tolerant
-- cloud agnostic
-- testable (unlike YAML/CI/CD code)
-- version controlled
-- enables cross-functional collaboration
-
-----
-
-**************
-Fork and build
-**************
-Before you build a Lightning component from scratch, see if you can find a component that is similar to what you need
-in the `Lightning component Gallery `_.
-
-Once you find the component you want, download the code and change what you want!
-
-----
-
-****************************
-Decide between Flow and Work
-****************************
-
-.. raw:: html
-
- 
-
-There are two types of components in Lightning, LightningFlow and LightningWork.
-
-Use a **LightningFlow** component for any programming logic that runs in less than 1 second.
-
-.. code:: python
-
- for i in range(10):
- print(f"{i}: this kind of code belongs in a LightningFlow")
-
-Use a **LightningWork** component for any programming logic that takes more than 1 second or requires its own hardware.
-
-.. code:: python
-
- from time import sleep
-
- for i in range(100000):
- sleep(2.0)
- print(f"{i} LightningWork: work that is long running or may never end (like a server)")
-
-----
-
-******************
-Build from scratch
-******************
-The first option is if you want to build from scratch
-
-----
-
-Option A: Build a LightningFlow
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To implement a LightningFlow, simply subclass ``LightningFlow`` and define the run method:
-
-.. code:: python
- :emphasize-lines: 5
-
- # app.py
- import lightning_app as la
-
-
- class LitFlow(lapp.LightningFlow):
- def run(self):
- for i in range(10):
- print(f"{i}: this kind of code belongs in a LightningFlow")
-
-
- app = lapp.LightningApp(LitFlow())
-
-run the app
-
-.. code:: bash
-
- lightning run app app.py
-
-----
-
-Option B: build a LightningWork
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Only implement a LightningWork if this particular piece of code:
-
-- takes more than 1 second to execute
-- or requires its own set of cloud resources
-- or both
-
-To implement a LightningWork, simply subclass ``LightningWork`` and define the run method:
-
-.. code:: python
- :emphasize-lines: 6
-
- # app.py
- from time import sleep
- import lightning_app as la
-
-
- class LitWork(lapp.LightningWork):
- def run(self):
- for i in range(100000):
- sleep(2.0)
- print(f"{i} LightningWork: work that is long running or may never end (like a server)")
-
-A LightningWork must always be attached to a LightningFlow and explicitely asked to ``run()``:
-
-.. code:: python
- :emphasize-lines: 13, 16
-
- from time import sleep
- import lightning_app as la
-
-
- class LitWork(lapp.LightningWork):
- def run(self):
- for i in range(100000):
- sleep(2.0)
- print(f"{i} LightningWork: work that is long running or may never end (like a server)")
-
-
- class LitFlow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.lit_work = LitWork()
-
- def run(self):
- self.lit_work.run()
-
-
- app = lapp.LightningApp(LitFlow())
-
-run the app
-
-.. code:: bash
-
- lightning run app app.py
-
-----
-
-*********************
-Build from a template
-*********************
-If you'd prefer a component template with built-in testing that can be easily published to the
-Lightning component gallery, generate it with our template generator:
-
-.. code:: bash
-
- lightning init component your-component-name
-
-You'll see a print-out like this:
-
-.. code:: bash
-
- ➜ lightning init component your-component-name
- INFO: laying out component template at /Users/williamfalcon/Developer/opensource/_/lightning/scratch/hello-world
- INFO:
- ⚡ Lightning component template created! ⚡
- /Users/williamfalcon/Developer/opensource/_/lightning/scratch/hello-world
-
- ...
-
-----
-
-Modify the component template
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The command above generates a component file like this:
-
-.. code:: python
-
- import lightning_app as la
-
-
- class TemplateComponent(lapp.LightningWork):
- def __init__(self) -> None:
- super().__init__()
- self.value = 0
-
- def run(self):
- self.value += 1
- print("welcome to your work component")
- print("this is running inside a work")
-
-Now you can modify the component as you wish!
+.. include:: from_scratch_component_content.rst
diff --git a/docs/source-app/workflows/build_lightning_component/from_scratch_component_content.rst b/docs/source-app/workflows/build_lightning_component/from_scratch_component_content.rst
new file mode 100644
index 0000000000..002816b074
--- /dev/null
+++ b/docs/source-app/workflows/build_lightning_component/from_scratch_component_content.rst
@@ -0,0 +1,200 @@
+*******************************
+LightningFlow vs. LightningWork
+*******************************
+
+.. _flow_vs_work:
+
+.. raw:: html
+
+
+
+There are two types of components in Lightning, **LightningFlow** and **LightningWork**.
+
+Use a **LightningFlow** component for any programming logic that runs in less than 1 second.
+
+.. code:: python
+
+ for i in range(10):
+ print(f"{i}: this kind of code belongs in a LightningFlow")
+
+Use a **LightningWork** component for any programming logic that takes more than 1 second or requires its own hardware.
+
+.. code:: python
+
+ from time import sleep
+
+ for i in range(100000):
+ sleep(2.0)
+ print(f"{i} LightningWork: work that is long running or may never end (like a server)")
+
+----
+
+************************************************
+What building a Lightning component does for you
+************************************************
+Lightning Components break up complex systems into modular components. The first obvious benefit is that components
+can be reused across other apps. This means you can build once, test it and forget it.
+
+As a researcher it also means that your code can be taken to production without needing a team of engineers to help
+productionize it.
+
+As a machine learning engineer, it means that your cloud system is:
+
+- fault tolerant
+- cloud agnostic
+- testable (unlike YAML/CI/CD code)
+- version controlled
+- enables cross-functional collaboration
+
+----
+
+**************
+WAIT!
+**************
+Before you build a Lightning component from scratch, see if you can find a component that is similar to what you need
+in the `Lightning component Gallery `_.
+
+Once you find the component you want, download the code and change what you want!
+
+----
+
+*****************************************
+Build a Lighitning component from scratch
+*****************************************
+If you didn't find a Lightning component similar to the one you need, you can build one from scratch.
+
+----
+
+Build a LightningFlow
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To implement a LightningFlow, simply subclass ``LightningFlow`` and define the run method:
+
+.. code:: python
+ :emphasize-lines: 5
+
+ # app.py
+ import lightning as L
+
+
+ class LitFlow(L.LightningFlow):
+ def run(self):
+ for i in range(10):
+ print(f"{i}: this kind of code belongs in a LightningFlow")
+
+
+ app = L.LightningApp(LitFlow())
+
+run the app
+
+.. code:: bash
+
+ lightning run app app.py
+
+----
+
+Build a LightningWork
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Only implement a LightningWork if this particular piece of code:
+
+- takes more than 1 second to execute
+- requires its own set of cloud resources
+- or both
+
+To implement a LightningWork, simply subclass ``LightningWork`` and define the run method:
+
+.. code:: python
+ :emphasize-lines: 6
+
+ # app.py
+ from time import sleep
+ import lightning as L
+
+
+ class LitWork(L.LightningWork):
+ def run(self):
+ for i in range(100000):
+ sleep(2.0)
+ print(f"{i} LightningWork: work that is long running or may never end (like a server)")
+
+A LightningWork must always be attached to a LightningFlow and explicitely asked to ``run()``:
+
+.. code:: python
+ :emphasize-lines: 13, 16
+
+ from time import sleep
+ import lightning as L
+
+
+ class LitWork(L.LightningWork):
+ def run(self):
+ for i in range(100000):
+ sleep(2.0)
+ print(f"{i} LightningWork: work that is long running or may never end (like a server)")
+
+
+ class LitFlow(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.lit_work = LitWork()
+
+ def run(self):
+ self.lit_work.run()
+
+
+ app = L.LightningApp(LitFlow())
+
+run the app
+
+.. code:: bash
+
+ lightning run app app.py
+
+----
+
+*******************************************
+Build a Lightning component from a template
+*******************************************
+If you'd prefer a component template with built-in testing that can be easily published to the
+Lightning component gallery, generate it with our template generator:
+
+.. code:: bash
+
+ lightning init component your-component-name
+
+You'll see a print-out like this:
+
+.. code:: bash
+
+ ➜ lightning init component your-component-name
+ INFO: laying out component template at /Users/williamfalcon/Developer/opensource/_/lightning/scratch/hello-world
+ INFO:
+ ⚡ Lightning component template created! ⚡
+ /Users/williamfalcon/Developer/opensource/_/lightning/scratch/hello-world
+
+ ...
+
+----
+
+Modify the component template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The command above generates a component file like this:
+
+.. code:: python
+
+ import lightning as L
+
+
+ class TemplateComponent(L.LightningWork):
+ def __init__(self) -> None:
+ super().__init__()
+ self.value = 0
+
+ def run(self):
+ self.value += 1
+ print("welcome to your work component")
+ print("this is running inside a work")
+
+Now you can modify the component as you wish!
diff --git a/docs/source-app/workflows/build_lightning_component/index_content.rst b/docs/source-app/workflows/build_lightning_component/index_content.rst
index 54dcad4d89..00b4e99ad1 100644
--- a/docs/source-app/workflows/build_lightning_component/index_content.rst
+++ b/docs/source-app/workflows/build_lightning_component/index_content.rst
@@ -28,7 +28,7 @@ Basics
+ +#. If **Launch** is available, it means the App is live and ready to be used! Take it for a spin. + + .. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/launch_button.png + :alt: Launch Button on lightning.ai + :width: 100 % + +#. By clicking **Clone & Run**, a copy of the App is added to your account and an instance starts running. + + .. raw:: html + +
+ + +#. If you found an App that matches what you need, move to **step 5**! Otherwise, go back to **step 1**. + + .. raw:: html + +
+ +#. Copy the installation command (optionally from the clipboard on the right). + + .. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/install_command.png + :alt: Install command on lightning.ai + :width: 100 % + +#. Copy the command to your local terminal. + + .. code-block:: bash + + lightning install app lightning/hackernews-app + +#. Go through the installation steps. + + .. raw:: html + +
+ + +#. Run the App locally. + + .. code-block:: bash + + cd LAI-Hackernews-App + lightning run app app.py + + .. raw:: html + +
+ + +#. Open the code with your favorite IDE, modify it, and run it back in the cloud. + + .. raw:: html + +
+ +
+ +---- + +********** +Next Steps +********** + +.. raw:: html + +
+
+
+
+.. displayitem::
+ :header: Add Component made by others to your App
+ :description: Add more functionality to your projects
+ :col_css: col-md-6
+ :button_link: jumpstart_from_component_gallery.html
+ :height: 180
+
+.. displayitem::
+ :header: Level-up your skills with Lightning Apps
+ :description: From Basic to Advanced Skills
+ :col_css: col-md-6
+ :button_link: ../levels/basic/index.html
+ :height: 180
+
+.. raw:: html
+
+
+ diff --git a/docs/source-app/get_started/jumpstart_from_component_gallery.rst b/docs/source-app/get_started/jumpstart_from_component_gallery.rst new file mode 100644 index 0000000000..5d0a0e434a --- /dev/null +++ b/docs/source-app/get_started/jumpstart_from_component_gallery.rst @@ -0,0 +1,155 @@ +:orphan: + +######################################## +Add Component made by others to your App +######################################## + +.. _jumpstart_from_component_gallery: + +Anyone can build components for their own use case and promote them on the `Component Gallery
+ +#. Check out the code for inspiration or simply install the component from PyPi and use it. + +---- + +************* +Success Story +************* + +The default `Train and Demo Application
+
+
+
+.. displayitem::
+ :header: Start from Ready-to-Run Template Apps
+ :description: Jump-start your projects development
+ :col_css: col-md-6
+ :button_link: jumpstart_from_app_gallery.html
+ :height: 180
+
+.. displayitem::
+ :header: Level-up your skills with Lightning Apps
+ :description: From Basic to Advanced Skills
+ :col_css: col-md-6
+ :button_link: ../levels/basic/index.html
+ :height: 180
+
+.. raw:: html
+
+
+ diff --git a/docs/source-app/get_started/lightning_apps_intro.rst b/docs/source-app/get_started/lightning_apps_intro.rst new file mode 100644 index 0000000000..bcbc9d8dbf --- /dev/null +++ b/docs/source-app/get_started/lightning_apps_intro.rst @@ -0,0 +1,14 @@ +############################ +Lightning Apps in 15 minutes +############################ + +**Required background:** Basic Python familiarity. + +**Goal:** Guide you to develop your first Lightning App or use an existing App from the `Apps Gallery
+
"
+ self.wfile.write(html)
- class LitServer(lapp.LightningWork):
+ class LitServer(L.LightningWork):
def run(self):
httpd = socketserver.TCPServer((self.host, self.port), PlainServer)
httpd.serve_forever()
- class Root(lapp.LightningFlow):
+ class Root(L.LightningFlow):
def __init__(self):
super().__init__()
self.lit_server = LitServer(parallel=True)
@@ -100,7 +104,7 @@ In this case, we render the ``LitServer`` output in the ``home`` tab of the appl
return tab1
- app = lapp.LightningApp(Root())
+ app = L.LightningApp(Root())
We use the ``parallel=True`` argument of ``LightningWork`` to run the server in parallel
while the rest of the Lightning App runs everything else.
diff --git a/docs/source-app/workflows/add_server/flask_basic.rst b/docs/source-app/workflows/add_server/flask_basic.rst
index dff64e12ca..38ca282346 100644
--- a/docs/source-app/workflows/add_server/flask_basic.rst
+++ b/docs/source-app/workflows/add_server/flask_basic.rst
@@ -20,6 +20,7 @@ Add Flask to a component
First, define your flask app as you normally would without Lightning:
.. code:: python
+ :emphasize-lines: 9
from flask import Flask
@@ -36,13 +37,13 @@ First, define your flask app as you normally would without Lightning:
To enable the server inside the component, start the Flask server in the run method and use the ``self.host`` and ``self.port`` properties:
.. code:: python
- :emphasize-lines: 11
+ :emphasize-lines: 12
- import lightning_app as la
+ import lightning as L
from flask import Flask
- class LitFlask(lapp.LightningWork):
+ class LitFlask(L.LightningWork):
def run(self):
flask_app = Flask(__name__)
@@ -61,13 +62,13 @@ The final step, is to tell the Root component in which tab to render this compon
In this case, we render the ``LitFlask`` output in the ``home`` tab of the application.
.. code:: python
- :emphasize-lines: 16, 22
+ :emphasize-lines: 17, 23
- import lightning_app as la
+ import lightning as L
from flask import Flask
- class LitFlask(lapp.LightningWork):
+ class LitFlask(L.LightningWork):
def run(self):
flask_app = Flask(__name__)
@@ -78,7 +79,7 @@ In this case, we render the ``LitFlask`` output in the ``home`` tab of the appli
flask_app.run(host=self.host, port=self.port)
- class Root(lapp.LightningFlow):
+ class Root(L.LightningFlow):
def __init__(self):
super().__init__()
self.lit_flask = LitFlask(parallel=True)
@@ -91,7 +92,7 @@ In this case, we render the ``LitFlask`` output in the ``home`` tab of the appli
return tab1
- app = lapp.LightningApp(Root())
+ app = L.LightningApp(Root())
We use the ``parallel=True`` argument of ``LightningWork`` to run the server in the background
while the rest of the Lightning App runs everything else.
@@ -103,31 +104,16 @@ Run the app
***********
Start the app to see your new UI!
-.. code:: console
+.. code:: bash
lightning run app app.py
To run the app on the cloud, use the ``--cloud`` argument.
-.. code:: console
+.. code:: bash
lightning run app app.py --cloud
-.. code:: python
-
- from flask import Flask
-
-
- class LitFlask(lapp.LightningWork):
- def run(self):
- flask_app = Flask(__name__)
-
- @flask_app.route("/")
- def hello():
- return "Hello, World!"
-
- flask_app.run(host=self.host, port=self.port)
-
----
********
diff --git a/docs/source-app/workflows/add_web_link.rst b/docs/source-app/workflows/add_web_link.rst
index 4236359ef4..01ffdf62ef 100644
--- a/docs/source-app/workflows/add_web_link.rst
+++ b/docs/source-app/workflows/add_web_link.rst
@@ -18,19 +18,23 @@ and connect the UIs. Create a file named **app.py** with this code:
the app running here
.. code:: python
- :emphasize-lines: 5, 6, 7
+ :emphasize-lines: 7,11
- import lightning_app as la
+ import lightning as L
-
- class LitApp(lapp.LightningFlow):
+ class LitApp(L.LightningFlow):
def configure_layout(self):
- tab_1 = {"name": "TB logs", "content": "https://bit.ly/tb-aasae"}
- tab_2 = {"name": "Paper", "content": "https://arxiv.org/pdf/2107.12329.pdf"}
+ tab_1 = {
+ "name": "Logger",
+ "content": "https://bit.ly/tb-aasae"
+ }
+ tab_2 = {
+ "name": "Paper",
+ "content": "https://arxiv.org/pdf/2107.12329.pdf"
+ }
return tab_1, tab_2
-
- app = lapp.LightningApp(LitApp())
+ app = L.LightningApp(LitApp())
----
@@ -39,12 +43,12 @@ Run the app
***********
Run the app locally to see it!
-.. code:: bash
+.. code:: python
lightning run app app.py
Now run it on the cloud as well:
-.. code:: bash
+.. code:: python
lightning run app app.py --cloud
diff --git a/docs/source-app/workflows/add_web_ui/angular_js_intermediate.rst b/docs/source-app/workflows/add_web_ui/angular_js_intermediate.rst
index 05b1731e4f..095dee362b 100644
--- a/docs/source-app/workflows/add_web_ui/angular_js_intermediate.rst
+++ b/docs/source-app/workflows/add_web_ui/angular_js_intermediate.rst
@@ -1,3 +1,5 @@
+:orphan:
+
###########################################
Add a web UI with Angular.js (intermediate)
###########################################
diff --git a/docs/source-app/workflows/add_web_ui/dash/basic.rst b/docs/source-app/workflows/add_web_ui/dash/basic.rst
index 505a6535c1..4316fc13a1 100644
--- a/docs/source-app/workflows/add_web_ui/dash/basic.rst
+++ b/docs/source-app/workflows/add_web_ui/dash/basic.rst
@@ -39,26 +39,26 @@ First **create a file named app.py** with the app content:
.. code:: bash
- import lightning_app as la
+ import lightning as L
import dash
import plotly.express as px
- class LitDash(lapp.LightningWork):
+ class LitDash(L.LightningWork):
def run(self):
- app = dash.Dash(__name__)
+ dash_app = dash.Dash(__name__)
X = [1, 2, 3, 4, 5, 6]
Y = [2, 4, 8, 16, 32, 64]
fig = px.line(x=X, y=Y)
- app.layout = dash.html.Div(children=[
+ dash_app.layout = dash.html.Div(children=[
dash.html.H1(children='⚡ Hello Dash + Lightning⚡'),
- dash.html.Div(children='''The Dash framework running inside a ⚡ Lightning App'''),
+ dash.html.Div(children='The Dash framework running inside a ⚡ Lightning App'),
dash.dcc.Graph(id='example-graph', figure=fig)
])
- app.run_server(host=self.host, port=self.port)
+ dash_app.run_server(host=self.host, port=self.port)
- class LitApp(lapp.LightningFlow):
+ class LitApp(L.LightningFlow):
def __init__(self):
super().__init__()
self.lit_dash = LitDash(parallel=True)
@@ -70,7 +70,7 @@ First **create a file named app.py** with the app content:
tab1 = {"name": "home", "content": self.lit_dash}
return tab1
- app = lapp.LightningApp(LitApp())
+ app = L.LightningApp(LitApp())
add 'dash' to a requirements.txt file:
@@ -88,13 +88,13 @@ Run the app
***********
Run the app locally to see it!
-.. code:: bash
+.. code:: python
lightning run app app.py
Now run it on the cloud as well:
-.. code:: console
+.. code:: python
lightning run app app.py --cloud
@@ -116,20 +116,18 @@ First, find the dash app you want to integrate. In this example, that app looks
import dash
import plotly.express as px
- app = dash.Dash(__name__)
+ dash_app = dash.Dash(__name__)
X = [1, 2, 3, 4, 5, 6]
Y = [2, 4, 8, 16, 32, 64]
fig = px.line(x=X, y=Y)
- app.layout = dash.html.Div(
- children=[
- dash.html.H1(children="⚡ Hello Dash + Lightning⚡"),
- dash.html.Div(children="""The Dash framework running inside a ⚡ Lightning App"""),
- dash.dcc.Graph(id="example-graph", figure=fig),
- ]
- )
+ dash_app.layout = dash.html.Div(children=[
+ dash.html.H1(children='⚡ Hello Dash + Lightning⚡'),
+ dash.html.Div(children='The Dash framework running inside a ⚡ Lightning App'),
+ dash.dcc.Graph(id='example-graph', figure=fig)
+ ])
- app.run_server(host="0.0.0.0", port=80)
+ dash_app.run_server(host='0.0.0.0', port=80)
This dash app plots a simple line curve along with some HTMlapp.
`Visit the Dash documentation for the full API
+
+.. displayitem::
+ :header: Level-up with Lightning Apps
+ :description: From Basics to Advanced Skills
+ :col_css: col-md-4
+ :button_link: ../levels/basic/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Add an Interactive Demo
+ :description: Add a Gradio Demo once the training is finished
+ :col_css: col-md-4
+ :button_link: add_an_interactive_demo.html
+ :height: 180
+
+.. displayitem::
+ :header: Add Hyper Parameter Optimization
+ :description: Add a HPO to optimize your models
+ :col_css: col-md-4
+ :button_link: ../examples/hpo/hpo.html
+ :height: 180
+
+.. displayitem::
+ :header: Add Model Serving
+ :description: Serve and load testing with MLServer and Locust
+ :col_css: col-md-4
+ :button_link: ../examples/model_server_app/model_server_app.html
+ :height: 180
+
+.. displayitem::
+ :header: Add DAG Orchestration
+ :description: Organize your processing, training and metrics collection
+ :col_css: col-md-4
+ :button_link: ../examples/dag/dag.html
+ :height: 180
+
+.. displayitem::
+ :header: Add Team Collaboration
+ :description: Create an app to run any PyTorch Lightning Script from Github
+ :col_css: col-md-4
+ :button_link: ../examples/github_repo_runner/github_repo_runner.html
+ :height: 180
diff --git a/docs/source-app/get_started/what_app_can_do.rst b/docs/source-app/get_started/what_app_can_do.rst
new file mode 100644
index 0000000000..a2c88a6f85
--- /dev/null
+++ b/docs/source-app/get_started/what_app_can_do.rst
@@ -0,0 +1,196 @@
+:orphan:
+
+############################################
+Discover what Lightning Apps can do in 5 min
+############################################
+
+.. _what_app_can_do:
+
+Lightning Apps can be plenty things, and while a picture is worth a thousand words, videos showing you examples should be worth even more.
+
+.. join_slack::
+ :align: left
+
+----
+
+*****************************
+Flashy - Auto ML App (Public)
+*****************************
+
+Train a model on any image or text dataset without writing any code. Flashy uses `React.js `_ on the App Gallery and the `Flashy codebase. `_ on GitHub.
+
+.. raw:: html
+
+
+
+.. ----
+
+.. ***************************************
+.. NVIDIA Omniverse Sampling App (Private)
+.. ***************************************
+
+.. Use `Nvidia Sampling Omniverse `_ on the App Gallery and the `Research App codebase. `_ on GitHub.
+
+.. raw:: html
+
+
+
+----
+
+************************************************
+ScratchPad - Notebook Manager for Team (Public)
+************************************************
+
+Run multiple Jupyter Notebooks on cloud CPUs or machines with multiple GPUs.
+
+Find the `ScratchPad App `_ on the App Gallery and the `ScratchPad App codebase `_ on GitHub.
+
+.. note:: ScratchPad is `tested end-to-end `_ on every Lightning App commit with `pytest `_ on the App Gallery and the `Lightning HPO Sweeper codebase. `_ on GitHub.
+
+.. raw:: html
+
+
+
+----
+
+***********************
+InVideo Search (Public)
+***********************
+
+This App lets you find anything you're looking for inside a video. The engine is powered by `Open AI CLIP `_ on the App Gallery and the `InVideo Search App codebase. `_ in GitHub.
+
+.. raw:: html
+
+
+
+----
+
+******************************
+AI-powered HackerNews (Public)
+******************************
+
+Save yourself time, and get Hacker News story recommendations, chosen for you specifically. This Lightning App was designed to illustrate a full end-to-end MLOPs workflow aimed at enterprise recommendation systems.
+
+Find the `AI-powered HackerNews App `_ on the App Gallery and the `AI-powered HackerNews App codebase. `_ on GitHub.
+
+.. raw:: html
+
+
+
+----
+
+*********************************************************************
+Lightning Apps can turn ML into scalable systems in days — not months
+*********************************************************************
+
+Use the Lightning framework to develop any ML system: train and deploy a model, create an ETL pipeline,
+or spin up a research demo — using the intuitive principles we pioneered with PyTorch Lightning.
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/apps_logos_2.png
+ :alt: Apps with Logos
+ :width: 100 %
+
+Anyone who knows Python can build a Lightning App, even without machine learning experience.
+
+Lightning Apps are:
+
+- cloud agnostic
+- fault-tolerant, distributed, cost optimized
+- production ready
+- local and cloud debuggable
+- highly reactive & interactive
+- connect multiple UIs together
+- built for team collaboration
+- framework agnostic, use your own stack
+- and much more
+
+.. raw:: html
+
+
+ +
+
+ +********** +Next Steps +********** + +.. raw:: html + +
+
")
+ html = "+ +
+
+ +********** +Next Steps +********** + +.. raw:: html + +
+
+
diff --git a/docs/source-app/glossary/app_tree.rst b/docs/source-app/glossary/app_tree.rst
index 85a0cee21e..9b16acda0a 100644
--- a/docs/source-app/glossary/app_tree.rst
+++ b/docs/source-app/glossary/app_tree.rst
@@ -1,3 +1,5 @@
+.. _app_component_tree:
+
###################
App Component Tree
###################
@@ -6,9 +8,11 @@ App Component Tree
**Level:** Basic
-****************************************
+----
+
+**************************************
What is an Application Component Tree?
-****************************************
+**************************************
Components can be nested to form component trees where the LightningFlows are its branches and LightningWorks are its leaves.
@@ -25,6 +29,8 @@ Here's a basic application with four flows and two works (associated tree struct
A Lightning app runs all flows into a single process. Its flows coordinate the execution of the works each running in their own independent processes.
+----
+
***********************************************
How do I define my application component tree?
***********************************************
@@ -35,22 +41,25 @@ You can attach your components in the **__init__** method of a flow.
.. code-block:: python
- import lightning_app as la
+ import lightning as L
- class RootFlow(lapp.LightningFlow):
+ class RootFlow(L.LightningFlow):
def __init__(self):
super().__init__()
- self.work = Work() # The `Work` component is attached here.
+ # The `Work` component is attached here.
+ self.work = Work()
- self.nested_flow = NestedFlow() # The `NestedFlow` component is attached here.
+ # The `NestedFlow` component is attached here.
+ self.nested_flow = NestedFlow()
Once done, simply add the root flow to a Lightning app as follows:
.. code-block:: python
- app = lapp.LightningApp(RootFlow())
+ app = L.LightningApp(RootFlow())
+----
******************************************
Is my application component tree static?
@@ -62,16 +71,20 @@ You can simply attach your components in the **run** method of a flow using the
.. code-block:: python
- class RootFlow(lapp.LightningFlow):
+ class RootFlow(L.LightningFlow):
def run(self):
if not hasattr(self, "work"):
- setattr(self, "work", Work()) # The `Work` component is attached here.
- getattr(self, "work").run() # Run the `Work` component.
+ # The `Work` component is attached here.
+ setattr(self, "work", Work())
+ # Run the `Work` component.
+ getattr(self, "work").run()
if not hasattr(self, "nested_flow"):
- setattr(self, "nested_flow", NestedFlow()) # The `NestedFlow` component is attached here.
- getattr(self, "wonested_flowrk").run() # Run the `NestedFlow` component.
+ # The `NestedFlow` component is attached here.
+ setattr(self, "nested_flow", NestedFlow())
+ # Run the `NestedFlow` component.
+ getattr(self, "wonested_flowrk").run()
But it is usually more readable to use Lightning built-in :class:`~lightning_app.structures.Dict` or :class:`~lightning_app.structures.List` as follows:
@@ -81,16 +94,18 @@ But it is usually more readable to use Lightning built-in :class:`~lightning_app
from lightning_app.structures import Dict
- class RootFlow(lapp.LightningFlow):
+ class RootFlow(L.LightningFlow):
def __init__(self):
super().__init__()
self.dict = Dict()
def run(self):
if "work" not in self.dict:
- self.dict["work"] = Work() # The `Work` component is attached here.
+ # The `Work` component is attached here.
+ self.dict["work"] = Work()
self.dict["work"].run()
if "nested_flow" not in self.dict:
- self.dict["nested_flow"] = NestedFlow() # The `NestedFlow` component is attached here.
+ # The `NestedFlow` component is attached here.
+ self.dict["nested_flow"] = NestedFlow()
self.dict["nested_flow"].run()
diff --git a/docs/source-app/glossary/build_config/build_config_basic.rst b/docs/source-app/glossary/build_config/build_config_basic.rst
index 7fa87b5e14..c3e3ae8c6f 100644
--- a/docs/source-app/glossary/build_config/build_config_basic.rst
+++ b/docs/source-app/glossary/build_config/build_config_basic.rst
@@ -20,14 +20,14 @@ for more granular control.
.. code-block:: bash
├── app.py
- ├── requirements.txt # Global requirements for the entire app
+ ├── requirements.txt # Global requirements for the entire app
└── works
├── serve
- │ ├── requirements.txt # Requirements specific to the 'serve' work
- │ └── serve.py # Source file for the LightningWork
+ │ ├── requirements.txt # Requirements specific to the 'serve' work
+ │ └── serve.py # Source file for the LightningWork
└── train
- ├── requirements.txt # Requirements specific to the 'train' work
- └── train.py # Source file for the LightningWork
+ ├── requirements.txt # Requirements specific to the 'train' work
+ └── train.py # Source file for the LightningWork
The requirements.txt file must be located in the same directry as the source file of the LightningWork.
When the LightningWork starts up, it will pick up the requirements file if present and install all listed packages.
@@ -46,6 +46,7 @@ Instead of listing the requirements in a file, you can also pass them to the Lig
:class:`~lightning_app.utilities.packaging.build_config.BuildConfig`:
.. code-block:: python
+ :emphasize-lines: 7
from lightning_app import LightningWork, BuildConfig
diff --git a/docs/source-app/glossary/dag.rst b/docs/source-app/glossary/dag.rst
index 6d843ffbd5..ef85d33cf3 100644
--- a/docs/source-app/glossary/dag.rst
+++ b/docs/source-app/glossary/dag.rst
@@ -1,18 +1,8 @@
######################
-Directed acyclic Graph
+Directed Acyclic Graph
######################
**Audience:** Users coming from MLOps to Lightning Apps, looking for more flexibility.
-.. warning:: documentation under development
-
-----
-
-***************************************
-What is a Directed acyclic Graph (DAG)?
-***************************************
-
-.. note:: documentation under development
-
----
*****************************
@@ -29,4 +19,28 @@ Can I Build a DAG with Lightning?
*********************************
Yes!
-DAGs are the (easiest) use-cases to build with Lightning Apps. For example, here's a full app that defines a DAG:
+DAGs are one of the easiest Lightning Apps to build. For example, here's a `full app that defines a DAG <../examples/dag/dag.html>`_.
+
+----
+
+********
+Examples
+********
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: Build & Train a Model
+ :description: Discover PyTorch Lightning and train your first Model.
+ :col_css: col-md-4
+ :button_link: build_model.html
+ :height: 180
+
+.. displayitem::
+ :header: Evolve a Model into an ML System
+ :description: Develop an App to train a model in the cloud
+ :col_css: col-md-4
+ :button_link: training_with_apps.html
+ :height: 180
+
+.. displayitem::
+ :header: Start from an ML system template
+ :description: Learn about Apps, from a template.
+ :col_css: col-md-4
+ :button_link: go_beyond_training.html
+ :height: 180
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/glossary/debug_app.rst b/docs/source-app/glossary/debug_app.rst
index 05c1091404..2d5c0d1990 100644
--- a/docs/source-app/glossary/debug_app.rst
+++ b/docs/source-app/glossary/debug_app.rst
@@ -1 +1,3 @@
+:orphan:
+
.. include:: ../workflows/debug_locally.rst
diff --git a/docs/source-app/glossary/distributed_fe.rst b/docs/source-app/glossary/distributed_fe.rst
index c0483158df..36d64b0143 100644
--- a/docs/source-app/glossary/distributed_fe.rst
+++ b/docs/source-app/glossary/distributed_fe.rst
@@ -1,3 +1,5 @@
+:orphan:
+
#####################
Distributed Front-End
#####################
diff --git a/docs/source-app/glossary/distributed_hardware.rst b/docs/source-app/glossary/distributed_hardware.rst
index 2dd51b3af2..0a64f5f5c0 100644
--- a/docs/source-app/glossary/distributed_hardware.rst
+++ b/docs/source-app/glossary/distributed_hardware.rst
@@ -1,3 +1,5 @@
+:orphan:
+
####################
Distributed Hardware
####################
diff --git a/docs/source-app/glossary/event_loop.rst b/docs/source-app/glossary/event_loop.rst
index eb09e4f34c..2b651267e6 100644
--- a/docs/source-app/glossary/event_loop.rst
+++ b/docs/source-app/glossary/event_loop.rst
@@ -1,11 +1,11 @@
-.. _event_loop:
-
##########
Event loop
##########
-Drawing inspiration from modern web frameworks like `React.js
+
+.. displayitem::
+ :header: Build a DAG
+ :description: Learn how to create a DAG with Lightning
+ :col_css: col-md-4
+ :button_link: ../examples/dag/dag.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
+
+
+----
+
+********
+Examples
+********
+
+
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: App Components Tree
+ :description: Learn how components can be nested to form component trees where the LightningFlows are its branches and LightningWorks are its leaves.
+ :col_css: col-md-6
+ :button_link: app_tree.html
+ :height: 180
+
+.. displayitem::
+ :header: Build Configuration
+ :description: Prepare your requirements, add custom build commands or use docker image
+ :col_css: col-md-6
+ :button_link: build_config/build_config.html
+ :height: 180
+
+.. displayitem::
+ :header: DAG
+ :description: Learn about directed acyclic graph, their properties and usage
+ :col_css: col-md-6
+ :button_link: dag.html
+ :height: 180
+
+.. displayitem::
+ :header: Event Loop
+ :description: Learn how the Infinite Event Loop enables high distributed reactivity by triggering after collecting state changes.
+ :col_css: col-md-6
+ :button_link: event_loop.html
+ :height: 180
+
+.. displayitem::
+ :header: Environment Variables
+ :description: Add secrets such as API keys or access tokens
+ :col_css: col-md-6
+ :button_link: environment_variables.html
+ :height: 180
+
+.. displayitem::
+ :header: Frontend
+ :description: Customize your App View with any framework you want
+ :col_css: col-md-6
+ :button_link: ../workflows/add_web_ui/glossary_front_end.html
+ :height: 180
+
+.. displayitem::
+ :header: Sharing Components
+ :description: Let's create an ecosystem altogether
+ :col_css: col-md-6
+ :button_link: sharing_components.html
+ :height: 180
+
+.. displayitem::
+ :header: Scheduling
+ :description: Orchestrate execution at specific times
+ :col_css: col-md-6
+ :button_link: scheduling.html
+ :height: 180
+
+.. displayitem::
+ :header: Storage
+ :description: Easily share files even across multiple machines
+ :col_css: col-md-6
+ :button_link: storage/storage.html
+ :height: 180
+
+.. displayitem::
+ :header: UI
+ :description: Combine multiple frameworks to create your own UI
+ :col_css: col-md-6
+ :button_link: ../workflows/add_web_ui/glossary_ui.html
+ :height: 180
diff --git a/docs/source-app/glossary/lightning_app_overview/index.rst b/docs/source-app/glossary/lightning_app_overview/index.rst
index 2dae01d9f0..09de273aff 100644
--- a/docs/source-app/glossary/lightning_app_overview/index.rst
+++ b/docs/source-app/glossary/lightning_app_overview/index.rst
@@ -3,6 +3,7 @@
###########################
Lightning Apps Key concepts
###########################
+
**Audience:** Users who want to know how the 🤯 magic works under the hood.
----
diff --git a/docs/source-app/glossary/scheduling.rst b/docs/source-app/glossary/scheduling.rst
index 38f37a152b..5f9bfdea7a 100644
--- a/docs/source-app/glossary/scheduling.rst
+++ b/docs/source-app/glossary/scheduling.rst
@@ -22,22 +22,19 @@ The LightningFlow has a ``schedule`` method which can be used to schedule your c
class MyFlow(LightningFlow):
+
def run(self):
if self.schedule("hourly"):
# run some code once every hour.
- pass
if self.schedule("daily"):
# run some code once day.
- pass
if self.schedule("daily") and anything_else:
# run some code once day if the anything else is also True.
- pass
if self.schedule("2 4 * * mon,fri"):
# defined with cron syntax, run some code at 04:02 on every Monday and Friday.
- pass
Learn more about the cron syntax `here `_
@@ -56,7 +53,6 @@ In the example above, the line ``self.schedule("hourly")`` will return ``True``
from lightning_app import LightningFlow
from lightning_app.core.structures import List
-
class ScheduledDAG(LightningFlow):
def __init__(self):
super().__init__()
@@ -65,10 +61,12 @@ In the example above, the line ``self.schedule("hourly")`` will return ``True``
def run(self):
if self.schedule("hourly"):
# dynamically instantiate
- # don't forget to always attach your components to the flow !!!
+ # don't forget to always attach
+ # your components to the flow !!!
self.list.append(MyDAGFlow(...))
- # run all dags, but the completed ones are cached and don't re-execute.
+ # run all dags, but the completed ones
+ # are cached and don't re-execute.
for dag in self.list:
dag.run()
@@ -80,7 +78,6 @@ In the example above, the line ``self.schedule("hourly")`` will return ``True``
from lightning_app import LightningFlow
from time import time
-
class ScheduledDAG(LightningFlow):
def __init__(self):
super().__init__()
@@ -99,7 +96,6 @@ In the example above, the line ``self.schedule("hourly")`` will return ``True``
from lightning_app import LightningFlow
from time import time
-
class ScheduledDAG(LightningFlow):
def __init__(self):
super().__init__()
@@ -112,13 +108,18 @@ In the example above, the line ``self.schedule("hourly")`` will return ``True``
if self.schedule("hourly"):
self.should_execute = True
- if self.should_execute: # Runs in 10 min
- self.data_processor.run(trigger_time=time()) # Runs in 5 min
+ # Runs in 10 min
+ if self.should_execute:
+ # Runs in 5 min
+ self.data_processor.run(trigger_time=time())
if self.data_processor.has_succeeded:
- self.training_work.run(self.data_processor.data) # Runs in 5 min
+ # Runs in 5 min
+ self.training_work.run(self.data_processor.data)
if self.training_work.has_succeeded:
self.should_execute = False
+----
+
***********
Limitations
***********
@@ -133,7 +134,6 @@ Here is an example of something which **WON'T** work:
from lightning_app import LightningFlow
from time import time
-
class ScheduledDAG(LightningFlow):
def __init__(self):
super().__init__()
@@ -143,9 +143,11 @@ Here is an example of something which **WON'T** work:
def run(self):
...
if self.schedule("hourly"):
- self.data_processor.run(trigger_time=time()) # This executes and finishes 5 min later
+ # This finishes 5 min later
+ self.data_processor.run(trigger_time=time())
if self.data_processor.has_succeeded:
- # This will never be reached as the data processor will keep processing forever...
+ # This will never be reached as the
+ # data processor will keep processing forever...
self.training_work.run(self.data_processor.data)
----
@@ -154,10 +156,30 @@ Here is an example of something which **WON'T** work:
Frequently Asked Questions
**************************
-- **Q: Can I use multiple nested schedule?**
+- **Q: Can I use multiple nested scheduler?** No, as they might cancel themselves out, but you can capture the event of one to trigger the next one.
- Not really as they might cancel themselves out, but you can capture the event of one to trigger the next one.
+- **Q: Can I use any arbitrary logic to schedule?** Yes, this design enables absolute flexibility, but you need to be careful to avoid bad practices.
-- **Q: Can I use any arbitrary logic to schedule?**
+----
- Yes, this design enables absolute flexibility, but you need to be careful to avoid bad practices.
+********
+Examples
+********
+
+.. raw:: html
+
+ `_ from `William Falcon `_ from `William Falcon
+
diff --git a/docs/source-app/glossary/sharing_components.rst b/docs/source-app/glossary/sharing_components.rst
index c4df69f95c..2699f5d3c1 100644
--- a/docs/source-app/glossary/sharing_components.rst
+++ b/docs/source-app/glossary/sharing_components.rst
@@ -6,6 +6,8 @@ Sharing my components
**Level:** Basic
+----
+
*********************************************
Why should I consider sharing my components ?
*********************************************
@@ -14,6 +16,8 @@ Lightning is community driven and its core objective is to make AI accessible to
By creating components and sharing them with everyone else, the barrier to entry will be go down.
+----
+
*************************************
How should I organize my components ?
*************************************
@@ -34,10 +38,12 @@ Here are the best practices steps before sharing the component:
.. note:: As a Lightning user, it helps to implement your components thinking someone else is going use them.
+----
+
******************************************
How should I proceed to share components ?
******************************************
Once your component is ready, create a PiPy package with your own library and then it can be re-used by anyone else.
-Here is a `Component Template
+
+.. displayitem::
+ :header: Build a DAG
+ :description: Learn how to schedule a DAG execution
+ :col_css: col-md-4
+ :button_link: ../examples/dag/dag.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
-
+.. include:: ../../glossary/storage/drive_content.rst
diff --git a/docs/source-app/glossary/storage/drive_content.rst b/docs/source-app/glossary/storage/drive_content.rst
new file mode 100644
index 0000000000..c2c1357d0f
--- /dev/null
+++ b/docs/source-app/glossary/storage/drive_content.rst
@@ -0,0 +1,199 @@
+
+
+************
+About Drives
+************
+
+Lightning Drive storage makes it easy to share files between LightningWorks so you can run your Lightning App both locally and in the cloud without changing the code.
+
+The Drive object provides a central place for your components to share data.
+
+The Drive acts as an isolate folder and any component can access it by knowing its name.
+
+Your components can put, list, get, and delete files from and to the Drive (except LightningFlows).
+
+----
+
+***********************
+What Drive does for you
+***********************
+
+Think of every instance of the Drive object acting like a Google Drive or like Dropbox.
+
+By sharing the Drive between components through the LightningFlow,
+several components can have a shared place to read and write files from.
+
+----
+
+**************
+Create a Drive
+**************
+
+In order to create a Drive, you simply need to pass its name with the prefix ``lit://`` as follows:
+
+.. code-block:: python
+
+ from lightning_app.storage import Drive
+
+ # The identifier of this Drive is ``drive_1``
+ # Note: You need to add Lightning protocol ``lit://`` as a prefix.
+
+ drive_1 = Drive("lit://drive_1")
+
+ # The identifier of this Drive is ``drive_2``
+ drive_2 = Drive("lit://drive_2")
+
+Any components can create a drive object.
+
+.. code-block:: python
+
+ from lightning_app import LightningFlow, LightningWork
+ from lightning_app.storage import Drive
+
+
+ class Flow(LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.drive_1 = Drive("lit://drive_1")
+
+ def run(self):
+ ...
+
+
+ class Work(LightningWork):
+ def __init__(self):
+ super().__init__()
+ self.drive_1 = Drive("lit://drive_1")
+
+ def run(self):
+ ...
+
+----
+
+*****************************
+Supported actions with Drives
+*****************************
+
+A Drive supports put, list, get, and delete actions.
+
+.. code-block:: python
+
+ from lightning_app.storage import Drive
+
+ drive = Drive("lit://drive")
+
+ drive.list(".") # Returns [] as empty
+
+ # Created file.
+ with open("a.txt", "w") as f:
+ f.write("Hello World !")
+
+ drive.put("a.txt")
+
+ drive.list(".") # Returns ["a.txt"] as the file copied in the Drive during the put action.
+
+ drive.get("a.txt") # Get the file into the current worker
+
+ drive.delete("a.txt")
+
+ drive.list(".") # Returns [] as empty
+
+----
+
+**********************************
+Component interactions with Drives
+**********************************
+
+Here is an illustrated code example on how to create drives within works.
+
+.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/drive_2.png
+
+.. code-block:: python
+
+ from lightning_app import LightningFlow, LightningWork
+ from lightning_app.core.app import LightningApp
+ from lightning_app.storage.drive import Drive
+
+
+ class Work_A(LightningWork):
+ def __init__(self):
+ super().__init__()
+ # The identifier of the Drive is ``drive_1``
+ # Note: You need to add Lightning protocol ``lit://`` as a prefix.
+ self.drive_1 = Drive("lit://drive_1")
+
+ def run(self):
+ # 1. Create a file.
+ with open("a.txt", "w") as f:
+ f.write("Hello World !")
+
+ # 2. Put the file into the drive.
+ self.drive_1.put("a.txt")
+
+
+ class Work_B(LightningWork):
+ def __init__(self):
+ super().__init__()
+
+ # Note: Work B has access 2 drives.
+
+ # The identifier of this Drive is ``drive_1``
+ self.drive_1 = Drive("lit://drive_1")
+ # The identifier of this Drive is ``drive_2``
+ self.drive_2 = Drive("lit://drive_2")
+
+ def run(self):
+ # 1. Create a file.
+ with open("b.txt", "w") as f:
+ f.write("Hello World !")
+
+ # 2. Put the file into both drives.
+ self.drive_1.put("b.txt")
+ self.drive_2.put("b.txt")
+
+
+ class Work_C(LightningWork):
+ def __init__(self):
+ super().__init__()
+ self.drive_2 = Drive("lit://drive_2")
+
+ def run(self):
+ # 1. Create a file.
+ with open("c.txt", "w") as f:
+ f.write("Hello World !")
+
+ # 2. Put the file into the drive.
+ self.drive_2.put("c.txt")
+
+----
+
+*****************************
+Transfer files with Drive
+*****************************
+
+In the example below, the Drive is created by the flow and passed to its LightningWork's.
+
+The ``Work_1`` put a file **a.txt** in the **Drive("lit://this_drive_id")** and the ``Work_2`` can list and get the **a.txt** file from it.
+
+.. literalinclude:: ../../../examples/app_drive/app.py
+
+
+----
+
+.. raw:: html
+
+
-
-.. displayitem::
- :header: Learn about the Path Object.
- :description: Transfer Files From One Component to Another by Reference.
- :col_css: col-md-4
- :button_link: path.html
- :height: 180
- :tag: Intermediate
-
-.. raw:: html
-
-
-
+
diff --git a/docs/source-app/glossary/storage/path.rst b/docs/source-app/glossary/storage/path.rst
index b46cdbfb1d..6da6459cf1 100644
--- a/docs/source-app/glossary/storage/path.rst
+++ b/docs/source-app/glossary/storage/path.rst
@@ -81,7 +81,7 @@ Convert every filesystem path you want to share with other LightningWorks to by
...
-Under the hood, we convert this string to a :class:`~lightning_app.storage.path.Path` object, which is a drop-in replacement for :class:`pathlib.Path` meaning it will work with :mod:`os`, :mod:`os.path` and :mod:`pathlib` filesystem operations out of the box!
+Under the hood, we convert this string to a :class:`~lightning.app.storage.path.Path` object, which is a drop-in replacement for :class:`pathlib.Path` meaning it will work with :mod:`os`, :mod:`os.path` and :mod:`pathlib` filesystem operations out of the box!
----
@@ -268,7 +268,7 @@ Link both components via a parent component:
self.deploy.run(checkpoint_dir=self.train.checkpoint_dir)
- app = lapp.LightningApp(Flow())
+ app = L.LightningApp(Flow())
----
diff --git a/docs/source-app/glossary/storage/storage.rst b/docs/source-app/glossary/storage/storage.rst
index 5bfa9689c0..37bf992bf1 100644
--- a/docs/source-app/glossary/storage/storage.rst
+++ b/docs/source-app/glossary/storage/storage.rst
@@ -48,3 +48,30 @@ Lightning storage provides two solutions :class:`~lightning_app.storage.drive.Dr
+
+.. displayitem::
+ :header: Learn about the Path Object.
+ :description: Transfer Files From One Component to Another by Reference.
+ :col_css: col-md-4
+ :button_link: path.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/index.rst b/docs/source-app/index.rst
index 80e2873143..68020dfab2 100644
--- a/docs/source-app/index.rst
+++ b/docs/source-app/index.rst
@@ -3,97 +3,192 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to ⚡ Lightning AI
-==========================
+############################
+Welcome to ⚡ Lightning Apps
+############################
.. twocolumns::
:left:
- .. image:: https://pl-bolts-doc-images.s3.us-east-2.amazonaws.com/mov.gif
+ .. image:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/Lightning.gif
:alt: Animation showing how to convert a standard training loop to a Lightning loop
:right:
- PyTorch Lightning is the deep learning framework for professional AI researchers and machine learning engineers who need maximal flexibility without sacrificing performance at scale.
- Lightning evolves with you as your projects go from idea to paper/production.
-
-.. raw:: html
-
-
+
+.. displayitem::
+ :header: Build a File Server
+ :description: Learn how to use Drive to upload / download files to your app.
+ :col_css: col-md-4
+ :button_link: ../../examples/file_server/file_server.html
+ :height: 180
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
-
-.. End of callout item section + +Keep Learning +^^^^^^^^^^^^^ + +.. raw:: html + +
"
+ self.wfile.write(html)
- class LitServer(lapp.LightningWork):
+ class LitServer(L.LightningWork):
def run(self):
httpd = socketserver.TCPServer((self.host, self.port), PlainServer)
httpd.serve_forever()
@@ -67,9 +70,9 @@ The final step, is to tell the Root component in which tab to render this compon
In this case, we render the ``LitServer`` output in the ``home`` tab of the application.
.. code:: python
- :emphasize-lines: 19, 25
+ :emphasize-lines: 20, 23, 28
- import lightning_app as la
+ import lightning as L
import socketserver
from http import HTTPStatus, server
@@ -78,16 +81,17 @@ In this case, we render the ``LitServer`` output in the ``home`` tab of the appl
def do_GET(self):
self.send_response(HTTPStatus.OK)
self.end_headers()
- self.wfile.write(b"
-
-
+ The `open-source Lightning framework `_ gives ML Researchers and Data Scientists, the fastest & most flexible
+ way to iterate on ML research ideas and deliver scalable ML systems with the performance enterprises requires at the same time.
.. join_slack::
:align: center
:margin: 0
+----
+
+*****************
+Install Lightning
+*****************
+
+
+.. raw:: html
+
+ ` guide.
-.. raw:: html
-
-
- - -Install Lightning ------------------ - - -.. - .. raw:: html - -
+---- +*********** Get Started ------------ +*********** .. raw:: html -
+
+
+Or read the :ref:`advanced install
+
+Pip users
+
+.. code-block:: bash
+
+ pip install lightning
+
+.. raw:: html
+
+
+
+
+Conda users
+
+.. code-block:: bash
+
+ conda install lightning -c conda-forge
+
.. raw:: html
- - -Install Lightning ------------------ - - -.. - .. raw:: html - -
-
-
-.. raw:: html
-
-
-
-Make sure you use Python 3.8+
-
-.. code-block:: bash
-
- python -m pip install -U lightning
-
-..
- .. raw:: html
-
-
-
-
- Conda users
-
- .. code-block:: bash
-
- Available after June 16th
-
- .. raw:: html
-
-
- +---- +*********** Get Started ------------ +*********** .. raw:: html -
+
+
+ +Build with Template(s) from the App & Component Gallery +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. raw:: html + +
+
+ +
+
+
+----
+
+***********************
+Current Lightning Users
+***********************
+
+.. raw:: html
+
+
+
+.. displayitem::
+ :header: Discover what Lightning Apps can do in 5 min
+ :description: Browse through mind-blowing ML Systems
+ :col_css: col-md-6
+ :button_link: get_started/what_app_can_do.html
+ :height: 180
+
+.. displayitem::
+ :header: Build and Train a Model
+ :description: Discover PyTorch Lightning and train your first Model.
+ :col_css: col-md-6
+ :button_link: get_started/build_model.html
+ :height: 180
+
+.. displayitem::
+ :header: Evolve a Model into an ML System
+ :description: Develop an App to train a model in the cloud
+ :col_css: col-md-6
+ :button_link: get_started/training_with_apps.html
+ :height: 180
+
+.. displayitem::
+ :header: Start from an ML system template
+ :description: Learn about Apps, from a template.
+ :col_css: col-md-6
+ :button_link: get_started/go_beyond_training.html
+ :height: 180
+
+.. raw:: html
+
+
+ + +Build with Template(s) from the App & Component Gallery +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. raw:: html + +
-.. Add callout items below this line
+.. displayitem::
+ :header: Start from Ready-to-Run Template Apps
+ :description: Jump-start your project's development
+ :col_css: col-md-6
+ :button_link: get_started/jumpstart_from_app_gallery.html
+ :height: 180
+
+.. displayitem::
+ :header: Add Component made by others to your App
+ :description: Add more functionalities to your projects
+ :col_css: col-md-6
+ :button_link: get_started/jumpstart_from_component_gallery.html
+ :height: 180
-.. customcalloutitem::
- :header: Build a Lightning App in 15 minutes
- :description: Learn the 4 key steps to build a Lightning app.
- :button_link: pages/lightning_apps_intro.html
.. raw:: html
-
- -.. End of callout item section + +Keep Learning +^^^^^^^^^^^^^ + +.. raw:: html + +
+
")
+ html = "
+
+.. displayitem::
+ :header: Level-up with PyTorch Lightning
+ :description: PyTorch Lightning Tutorials
+ :col_css: col-md-6
+ :button_link: https://pytorch-lightning.readthedocs.io/en/latest/expertise_levels.html
+ :height: 180
+
+.. displayitem::
+ :header: Level-up with Lightning Apps
+ :description: From Basics to Advanced Skills
+ :col_css: col-md-6
+ :button_link: levels/basic/index.html
+ :height: 180
+
+.. displayitem::
+ :header: API Reference
+ :description: Detailed description of each API package
+ :col_css: col-md-6
+ :button_link: api_reference/api_references.html
+ :height: 180
+
+.. displayitem::
+ :header: Hands-on Examples
+ :description: Learn by building Apps and Components.
+ :col_css: col-md-6
+ :button_link: examples/hands_on_example.html
+ :height: 180
+
+.. displayitem::
+ :header: Common Workflows
+ :description: Learn how to do ...
+ :col_css: col-md-6
+ :button_link: workflows/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Glossary
+ :description: Discover Lightning App Concepts
+ :col_css: col-md-6
+ :button_link: glossary/index.html
+ :height: 180
.. raw:: html
@@ -103,13 +198,69 @@ Get Started
")
+ html = "
"
+ self.wfile.write(html)
httpd = socketserver.TCPServer(("localhost", "3000"), PlainServer)
@@ -39,9 +41,9 @@ Any server that listens on a port, can be enabled via a work. For example, here'
To enable the server inside the component, start the server in the run method and use the ``self.host`` and ``self.port`` properties:
.. code:: python
- :emphasize-lines: 13, 14
+ :emphasize-lines: 14-15
- import lightning_app as la
+ import lightning as L
import socketserver
from http import HTTPStatus, server
@@ -50,10 +52,11 @@ To enable the server inside the component, start the server in the run method an
def do_GET(self):
self.send_response(HTTPStatus.OK)
self.end_headers()
- self.wfile.write(b"Hello lit world
Hello lit world
Hello lit world
Hello lit world
Hello lit world
-
-There are two types of components in Lightning, LightningFlow and LightningWork.
-
-Use a **LightningFlow** component for any programming logic that runs in less than 1 second.
-
-.. code:: python
-
- for i in range(10):
- print(f"{i}: this kind of code belongs in a LightningFlow")
-
-Use a **LightningWork** component for any programming logic that takes more than 1 second or requires its own hardware.
-
-.. code:: python
-
- from time import sleep
-
- for i in range(100000):
- sleep(2.0)
- print(f"{i} LightningWork: work that is long running or may never end (like a server)")
-
-----
-
-******************
-Build from scratch
-******************
-The first option is if you want to build from scratch
-
-----
-
-Option A: Build a LightningFlow
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To implement a LightningFlow, simply subclass ``LightningFlow`` and define the run method:
-
-.. code:: python
- :emphasize-lines: 5
-
- # app.py
- import lightning_app as la
-
-
- class LitFlow(lapp.LightningFlow):
- def run(self):
- for i in range(10):
- print(f"{i}: this kind of code belongs in a LightningFlow")
-
-
- app = lapp.LightningApp(LitFlow())
-
-run the app
-
-.. code:: bash
-
- lightning run app app.py
-
-----
-
-Option B: build a LightningWork
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Only implement a LightningWork if this particular piece of code:
-
-- takes more than 1 second to execute
-- or requires its own set of cloud resources
-- or both
-
-To implement a LightningWork, simply subclass ``LightningWork`` and define the run method:
-
-.. code:: python
- :emphasize-lines: 6
-
- # app.py
- from time import sleep
- import lightning_app as la
-
-
- class LitWork(lapp.LightningWork):
- def run(self):
- for i in range(100000):
- sleep(2.0)
- print(f"{i} LightningWork: work that is long running or may never end (like a server)")
-
-A LightningWork must always be attached to a LightningFlow and explicitely asked to ``run()``:
-
-.. code:: python
- :emphasize-lines: 13, 16
-
- from time import sleep
- import lightning_app as la
-
-
- class LitWork(lapp.LightningWork):
- def run(self):
- for i in range(100000):
- sleep(2.0)
- print(f"{i} LightningWork: work that is long running or may never end (like a server)")
-
-
- class LitFlow(lapp.LightningFlow):
- def __init__(self):
- super().__init__()
- self.lit_work = LitWork()
-
- def run(self):
- self.lit_work.run()
-
-
- app = lapp.LightningApp(LitFlow())
-
-run the app
-
-.. code:: bash
-
- lightning run app app.py
-
-----
-
-*********************
-Build from a template
-*********************
-If you'd prefer a component template with built-in testing that can be easily published to the
-Lightning component gallery, generate it with our template generator:
-
-.. code:: bash
-
- lightning init component your-component-name
-
-You'll see a print-out like this:
-
-.. code:: bash
-
- ➜ lightning init component your-component-name
- INFO: laying out component template at /Users/williamfalcon/Developer/opensource/_/lightning/scratch/hello-world
- INFO:
- ⚡ Lightning component template created! ⚡
- /Users/williamfalcon/Developer/opensource/_/lightning/scratch/hello-world
-
- ...
-
-----
-
-Modify the component template
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The command above generates a component file like this:
-
-.. code:: python
-
- import lightning_app as la
-
-
- class TemplateComponent(lapp.LightningWork):
- def __init__(self) -> None:
- super().__init__()
- self.value = 0
-
- def run(self):
- self.value += 1
- print("welcome to your work component")
- print("this is running inside a work")
-
-Now you can modify the component as you wish!
+.. include:: from_scratch_component_content.rst
diff --git a/docs/source-app/workflows/build_lightning_component/from_scratch_component_content.rst b/docs/source-app/workflows/build_lightning_component/from_scratch_component_content.rst
new file mode 100644
index 0000000000..002816b074
--- /dev/null
+++ b/docs/source-app/workflows/build_lightning_component/from_scratch_component_content.rst
@@ -0,0 +1,200 @@
+*******************************
+LightningFlow vs. LightningWork
+*******************************
+
+.. _flow_vs_work:
+
+.. raw:: html
+
+
+
+There are two types of components in Lightning, **LightningFlow** and **LightningWork**.
+
+Use a **LightningFlow** component for any programming logic that runs in less than 1 second.
+
+.. code:: python
+
+ for i in range(10):
+ print(f"{i}: this kind of code belongs in a LightningFlow")
+
+Use a **LightningWork** component for any programming logic that takes more than 1 second or requires its own hardware.
+
+.. code:: python
+
+ from time import sleep
+
+ for i in range(100000):
+ sleep(2.0)
+ print(f"{i} LightningWork: work that is long running or may never end (like a server)")
+
+----
+
+************************************************
+What building a Lightning component does for you
+************************************************
+Lightning Components break up complex systems into modular components. The first obvious benefit is that components
+can be reused across other apps. This means you can build once, test it and forget it.
+
+As a researcher it also means that your code can be taken to production without needing a team of engineers to help
+productionize it.
+
+As a machine learning engineer, it means that your cloud system is:
+
+- fault tolerant
+- cloud agnostic
+- testable (unlike YAML/CI/CD code)
+- version controlled
+- enables cross-functional collaboration
+
+----
+
+**************
+WAIT!
+**************
+Before you build a Lightning component from scratch, see if you can find a component that is similar to what you need
+in the `Lightning component Gallery
.. displayitem::
- :header: Build a component
+ :header: Build a Lightning component
:description: Learn the basics of building a Lightning component
:col_css: col-md-4
:button_link: basic.html
@@ -36,8 +36,8 @@ Basics
:tag: basic
.. displayitem::
- :header: Explore community components
- :description: Discover community-built components
+ :header: Explore community Lightning components
+ :description: Discover community-built Lightning components
:col_css: col-md-4
:button_link: https://lightning.ai/components
:height: 150
@@ -84,7 +84,7 @@ Intermediate
:tag: intermediate
.. displayitem::
- :header: Publish a component
+ :header: Publish a Lightning component
:description: Learn the basics of publishing a Lightning component.
:col_css: col-md-4
:button_link: publish_a_component.html
diff --git a/docs/source-app/workflows/build_lightning_component/intermediate.rst b/docs/source-app/workflows/build_lightning_component/intermediate.rst
index a1956b260d..070d3aa0ca 100644
--- a/docs/source-app/workflows/build_lightning_component/intermediate.rst
+++ b/docs/source-app/workflows/build_lightning_component/intermediate.rst
@@ -29,11 +29,11 @@ To *connect* this user interface to the component, define the configure_layout m
.. code:: python
:emphasize-lines: 5, 6
- import lightning_app as la
+ import lightning as L
from lightning_app.frontend.web import StaticWebFrontend
- class LitHTMLComponent(lapp.LightningFlow):
+ class LitHTMLComponent(L.LightningFlow):
def configure_layout(self):
return StaticWebFrontend(serve_dir="path/to/folder/with/index.html/inside")
@@ -43,15 +43,15 @@ Finally, route the component's UI through the root component's **configure_layou
:emphasize-lines: 14
# app.py
- import lightning_app as la
+ import lightning as L
- class LitHTMLComponent(lapp.LightningFlow):
+ class LitHTMLComponent(L.LightningFlow):
def configure_layout(self):
- return lapp.frontend.web.StaticWebFrontend(serve_dir="path/to/folder/with/index.html/inside")
+ return L.frontend.web.StaticWebFrontend(serve_dir="path/to/folder/with/index.html/inside")
- class LitApp(lapp.LightningFlow):
+ class LitApp(L.LightningFlow):
def __init__(self):
super().__init__()
self.lit_html_component = LitHTMLComponent()
@@ -61,7 +61,7 @@ Finally, route the component's UI through the root component's **configure_layou
return tab1
- app = lapp.LightningApp(LitApp())
+ app = L.LightningApp(LitApp())
Run your app and you'll see the UI on the Lightning App view:
diff --git a/docs/source-app/workflows/build_lightning_component/publish_a_component.rst b/docs/source-app/workflows/build_lightning_component/publish_a_component.rst
index f4ed73b2bd..8364afd3d5 100644
--- a/docs/source-app/workflows/build_lightning_component/publish_a_component.rst
+++ b/docs/source-app/workflows/build_lightning_component/publish_a_component.rst
@@ -13,7 +13,7 @@ the default template.
Generate your component template with this command:
-.. code:: bash
+.. code:: python
lightning init component your-component-name
@@ -36,20 +36,18 @@ Now import your component and use it in an app:
# app.py
from your_component import TemplateComponent
- import lightning_app as la
+ import lightning as L
-
- class LitApp(lapp.LightningFlow):
+ class LitApp(L.LightningFlow):
def __init__(self) -> None:
super().__init__()
self.your_component = TemplateComponent()
def run(self):
- print("this is a simple Lightning app to verify your component is working as expected")
+ print('this is a simple Lightning app to verify your component is working as expected')
self.your_component.run()
-
- app = lapp.LightningApp(LitApp())
+ app = L.LightningApp(LitApp())
and run the app:
diff --git a/docs/source-app/workflows/debug_locally.rst b/docs/source-app/workflows/debug_locally.rst
index 77ea163b44..cd5a5a80fd 100644
--- a/docs/source-app/workflows/debug_locally.rst
+++ b/docs/source-app/workflows/debug_locally.rst
@@ -1,3 +1,5 @@
+:orphan:
+
#####################################
Debug a Distributed Cloud App Locally
#####################################
diff --git a/docs/source-app/workflows/enable_fault_tolerance.rst b/docs/source-app/workflows/enable_fault_tolerance.rst
index c7af476d34..b1630d4d39 100644
--- a/docs/source-app/workflows/enable_fault_tolerance.rst
+++ b/docs/source-app/workflows/enable_fault_tolerance.rst
@@ -1,3 +1,5 @@
+:orphan:
+
######################
Enable Fault Tolerance
######################
diff --git a/docs/source-app/workflows/extend_app.rst b/docs/source-app/workflows/extend_app.rst
index d0ac9feab3..2e17af481b 100644
--- a/docs/source-app/workflows/extend_app.rst
+++ b/docs/source-app/workflows/extend_app.rst
@@ -1,7 +1,7 @@
######################
Extend an Existing App
######################
-You can extend a Lightning app by using community components or building your own.
+You can extend a Lightning App by using community components or building your own.
----
@@ -13,8 +13,8 @@ You can extend a Lightning app by using community components or building your ow
.. Add callout items below this line
.. displayitem::
- :header: Add more components
- :description: Extend an app by adding a prebuilt component.
+ :header: Add more Components
+ :description: Extend an App by adding a prebuilt component.
:col_css: col-md-4
:button_link: add_components/index.html
:height: 150
@@ -22,23 +22,23 @@ You can extend a Lightning app by using community components or building your ow
.. displayitem::
:header: Add a web user interface (UI)
- :description: Extend an app by adding a web user interface (UI)
+ :description: Extend an App by adding a web user interface (UI)
:col_css: col-md-4
:button_link: add_web_ui/index.html
:height: 150
:tag: basic
.. displayitem::
- :header: Add a url link
- :description: Extend an app by adding a web url link
+ :header: Add a URL link
+ :description: Extend an App by adding a web URL link
:col_css: col-md-4
:button_link: add_web_link.html
:height: 150
:tag: basic
.. displayitem::
- :header: Build a component
- :description: Extend an app by building a component
+ :header: Build a Component
+ :description: Extend an App by building a Component
:col_css: col-md-4
:button_link: build_lightning_component/index.html
:height: 150
@@ -46,7 +46,7 @@ You can extend a Lightning app by using community components or building your ow
.. displayitem::
:header: Add a server
- :description: Extend an app by adding a server to a component.
+ :description: Extend an App by adding a server to a Component.
:col_css: col-md-4
:button_link: add_server/index.html
:height: 150
diff --git a/docs/source-app/workflows/index.rst b/docs/source-app/workflows/index.rst
new file mode 100644
index 0000000000..7f0642f661
--- /dev/null
+++ b/docs/source-app/workflows/index.rst
@@ -0,0 +1,114 @@
+:orphan:
+
+################
+Common Workflows
+################
+
+.. raw:: html
+
+ `_.
+
+
+----
+
+*******************
+Structure app files
+*******************
+
+We recommend your app contain the following files:
+
+.. code:: bash
+
+ .
+ ├── .lightning (auto-generated- conatins Lightning configuration)
+ ├── .lightningignore (contains files not to upload to the cloud)
+ ├── app.py
+ ├── README.md (optional- a markdown description of your app)
+ └── requirements.txt (optional- conatins all your app dependencies)
diff --git a/docs/source-app/workflows/run_app_on_cloud/index.rst b/docs/source-app/workflows/run_app_on_cloud/index.rst
new file mode 100644
index 0000000000..55bc3b6807
--- /dev/null
+++ b/docs/source-app/workflows/run_app_on_cloud/index.rst
@@ -0,0 +1,5 @@
+#####################
+Run apps on the cloud
+#####################
+
+.. include:: index_content.rst
diff --git a/docs/source-app/workflows/run_app_on_cloud/index_content.rst b/docs/source-app/workflows/run_app_on_cloud/index_content.rst
new file mode 100644
index 0000000000..b0f67570d7
--- /dev/null
+++ b/docs/source-app/workflows/run_app_on_cloud/index_content.rst
@@ -0,0 +1,115 @@
+.. _run_app_in_cloud:
+
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+
+ cloud_files
+ lightning_cloud
+ on_prem
+ on_your_own_machine
+
+**Audience:** Users who want to share or scale Lightning Apps.
+
+----
+
+*****************************
+Run on Lightning Public Cloud
+*****************************
+
+You can run Lightning Apps for free on the Public Lightning cloud with a single flag!
+
+.. raw:: html
+
+ `_.
+
+If your app contains ``LightningWork`` components that require more compute resources, such as larger CPUs or **GPUs**, you'll need to add credits to your Lightning AI account.
+
+
+----
+
+**************************
+Add dependencies to my app
+**************************
+
+
+Add all dependencies required to run your app to a `requirements.txt` file in your app's directory. Read :ref:`build_config` for more details.
+
+
+
+----
+
+
+********
+Name app
+********
+
+Simply use the ``--name`` flag when running your app, for example:
+
+.. code:: bash
+
+ lightning run app app.py --cloud --name my-awesome-app
+
+Alternatively, you can change the name of the app in the ``.lightning`` file:
+
+.. code:: bash
+
+ ~/project/home ❯ cat .lightning
+ name: my-awesome-app
+
+The ``.lightning`` file is a general configuration file.
+To learn more about optional configuration file parameters, see :class:`~lightning.utilities.packaging.app_config.AppConfig`.
+
+------
+
+********************
+Choose Cloud Compute
+********************
+
+You can configure the hardware your app is running on by setting a :class:`~lightning.utilities.packaging.cloud_compute.CloudCompute` object onto the ``cloud_compute`` property of your work's.
+
+Learn more with the :ref:`cloud_compute` guide
diff --git a/docs/source-app/workflows/run_app_on_cloud/on_prem.rst b/docs/source-app/workflows/run_app_on_cloud/on_prem.rst
new file mode 100644
index 0000000000..be0a954f29
--- /dev/null
+++ b/docs/source-app/workflows/run_app_on_cloud/on_prem.rst
@@ -0,0 +1,6 @@
+###########################
+Run an App on Private Cloud
+###########################
+
+
+To run Lightning apps on a private or on-prem cluster, `contact us `_.
diff --git a/docs/source-app/workflows/run_app_on_cloud/on_your_own_machine.rst b/docs/source-app/workflows/run_app_on_cloud/on_your_own_machine.rst
new file mode 100644
index 0000000000..795205f552
--- /dev/null
+++ b/docs/source-app/workflows/run_app_on_cloud/on_your_own_machine.rst
@@ -0,0 +1,23 @@
+#######################
+Run on your own machine
+#######################
+
+**Audience:** Users who want to run Lightning App on a remote machine.
+
+----
+
+***********
+Run via ssh
+***********
+To run a Lightning App on any machine, simply ssh to the machine and run the app directly
+
+.. code:: bash
+
+ # log into your cloud machine
+ ssh your_name@your_cloud_machine
+
+ # get your code on the machine and install deps
+ ...
+
+ # start the app
+ lightning run app app.py
diff --git a/docs/source-app/workflows/run_components_on_different_hardware.rst b/docs/source-app/workflows/run_components_on_different_hardware.rst
index ef3aac100d..9685c3461e 100644
--- a/docs/source-app/workflows/run_components_on_different_hardware.rst
+++ b/docs/source-app/workflows/run_components_on_different_hardware.rst
@@ -1,3 +1,5 @@
+:orphan:
+
####################################
Run components on different hardware
####################################
diff --git a/docs/source-app/workflows/run_work_in_parallel.rst b/docs/source-app/workflows/run_work_in_parallel.rst
index 542b36b3b3..58089b6ed7 100644
--- a/docs/source-app/workflows/run_work_in_parallel.rst
+++ b/docs/source-app/workflows/run_work_in_parallel.rst
@@ -1,56 +1,11 @@
-####################
-Run work in parallel
-####################
+##############################
+Run LightningWorks in parallel
+##############################
-When there is a long-running workload such as a model training, or a deployment server, it may be desirable to run that work in parallel
-while the rest of the app continues to execute.
+**Audience:** Users who want to run multiple LightningWorks at once.
+
+**Prereqs:** Level 8+
----
-****************************
-Why do I need parallel work?
-****************************
-The default behavior of the ``LightningWork`` is to wait for the ``run`` method to complete:
-
-.. code:: python
-
- import lightning_app as la
-
-
- class Root(lapp.LightningFlow):
- def __init__(self):
- self.work_component_a = lapp.demo.InfinteWorkComponent()
-
- def run(self):
- self.work_component_a.run()
- print("this will never print")
-
-Since this Work component we created loops forever, the print statement will never execute. In practice
-``LightningWork`` workloads are finite and don't run forever.
-
-When a ``LightningWork`` performs a heavy operation (longer than 1 second), or requires its own hardware,
-work that is *not* done in parallel will slow down your app.
-
-----
-
-********************
-Enable parallel work
-********************
-To run work in parallel while the rest of the app executes without delays, enable ``parallel=True``:
-
-.. code:: python
- :emphasize-lines: 5
-
- import lightning_app as la
-
-
- class Root(lapp.LightningFlow):
- def __init__(self):
- self.work_component_a = lapp.demo.InfinteWorkComponent(parallel=True)
-
- def run(self):
- self.work_component_a.run()
- print("repeats while the infinite work runs ONCE (and forever) in parallel")
-
-Any work that will take more than **1 second** should be run in parallel
-unless the rest of your app depends on the output of this work (for example, downloading a dataset).
+.. include:: run_work_in_parallel_content.rst
diff --git a/docs/source-app/workflows/run_work_in_parallel_content.rst b/docs/source-app/workflows/run_work_in_parallel_content.rst
new file mode 100644
index 0000000000..ecb87c5cea
--- /dev/null
+++ b/docs/source-app/workflows/run_work_in_parallel_content.rst
@@ -0,0 +1,53 @@
+
+
+****************************************************
+What running LightningWorks in parallel does for you
+****************************************************
+
+When there is a long-running workload such as a model training, or a deployment server, you might want to run that LightningWork in parallel
+while the rest of the Lightning App continues to execute.
+
+The default behavior of the ``LightningWork`` is to wait for the ``run`` method to complete:
+
+.. code:: python
+
+ import lightning as L
+
+
+ class Root(L.LightningFlow):
+ def __init__(self):
+ self.work_component_a = L.demo.InfinteWorkComponent()
+
+ def run(self):
+ self.work_component_a.run()
+ print("this will never print")
+
+Since this LightningWork component we created loops forever, the print statement will never execute. In practice
+``LightningWork`` workloads are finite and don't run forever.
+
+When a ``LightningWork`` performs a heavy operation (longer than 1 second), or requires its own hardware,
+LightningWork that is *not* done in parallel will slow down your app.
+
+----
+
+******************************
+Enable parallel LightningWorks
+******************************
+To run LightningWorks in parallel, while the rest of the app executes without delays, enable ``parallel=True``:
+
+.. code:: python
+ :emphasize-lines: 5
+
+ import lightning as L
+
+
+ class Root(L.LightningFlow):
+ def __init__(self):
+ self.work_component_a = L.demo.InfinteWorkComponent(parallel=True)
+
+ def run(self):
+ self.work_component_a.run()
+ print("repeats while the infinite work runs ONCE (and forever) in parallel")
+
+Any LightningWorks that will take more than **1 second** should be run in parallel
+unless the rest of your Lightning App depends on the output of this work (for example, downloading a dataset).
diff --git a/docs/source-app/workflows/run_work_once.rst b/docs/source-app/workflows/run_work_once.rst
index b98df496bc..240cde3d08 100644
--- a/docs/source-app/workflows/run_work_once.rst
+++ b/docs/source-app/workflows/run_work_once.rst
@@ -1,126 +1,13 @@
-.. _cache_calls:
-
-#################
-Caching Work Runs
-#################
+##########################
+Cache LightningWork Runs
+##########################
**Audience:** Users who want to know how ``LightningWork`` works.
-**Level:** Basic
+**Level:** Advanced
-**Prerequisite**: Read the :ref:`event_loop` guide.
+**Prereqs**: Level 16+ and read the `Event Loop guide <../glossary/event_loop.html>`_.
----
-**********************************************************
-What does it mean to cache the calls of Work's run method?
-**********************************************************
-
-By default, the run method in a LightningWork "remembers" (caches) the input arguments it is getting called with and does not execute again if called with the same arguments again.
-In other words, the run method only executes when the input arguments have never been seen before.
-
-This behavior can be toggled on or off:
-
-.. code-block:: python
-
- # Run only when the input arguments change (default)
- work = MyWork(cache_calls=True)
-
- # Run everytime regardless of whether input arguments change or not
- work = MyWork(cache_calls=False)
-
-
-To better understand this, imagine you want every day to sequentially download and process some data and then train a model on those data.
-As explained in the pre-requisite, the Lightning App runs within an infinite while loop, so the pseudo-code of your application might looks like this:
-
-.. code-block:: python
-
- from datetime import datetime
-
- # Lightning code
- while True: # This is the Lightning Event Loop
-
- # Your code
- today = datetime.now().strftime("%D") # '05/25/22'
- data_processor.run(today)
- train_model.run(data_processor.data)
-
-In this scenario, you want your components to run ``once`` a day, no more! But your code is running within an infinite loop, how can this even work?
-This is where the work's internal caching mechanism comes in. By default, Lightning caches a hash of the input provided to its run method and won't re-execute the method if the same input is provided again.
-In the example above, the **data_processor** component run method receives the string **"05/25/22"**. It runs one time and any further execution during the day is skipped until tomorrow is reached and the work run method receives **06/25/22**. This logic applies everyday.
-This caching mechanism is inspired from how `React.js Components and Props `_ renders website. Only changes to the inputs re-trigger execution.
-
-*******************************
-How can I verify this behavior?
-*******************************
-
-Here's an example of this behavior with LightningWork:
-
-.. literalinclude:: ../code_samples/basics/0.py
- :language: python
- :emphasize-lines: 10, 19
-
-And you should see the following by running the code above:
-
-.. code-block:: console
-
- $ python example.py
- INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
- # After you have clicked `run` on the UI.
- I received the following props: args: () kwargs: {'value': 1}
- I received the following props: args: () kwargs: {'value': 10}
-
-As you can see, the intermediate run didn't execute, as we would expected when ``cache_calls=True``.
-
-************************************************
-What are the implications of turnin caching off?
-************************************************
-
-By setting ``cache_calls=False``, Lightning won't cache the return value and re-execute the run method on every call.
-
-.. literalinclude:: ../code_samples/basics/1.py
- :diff: ../code_samples/basics/0.py
-
-.. code-block:: console
-
- $ python example.py
- INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
- # After you have clicked `run` on the UI.
- I received the following props: args: () kwargs: {'value': 1}
- I received the following props: args: () kwargs: {'value': 1}
- I received the following props: args: () kwargs: {'value': 1}
- I received the following props: args: () kwargs: {'value': 1}
- I received the following props: args: () kwargs: {'value': 1}
- I received the following props: args: () kwargs: {'value': 10}
-
-
-Be aware than when setting both ``cache_calls=False`` and ``parallel=False`` to a work, the code after the ``self.work.run()`` is unreachable
-as the work continuously execute in a blocking way.
-
-.. code-block:: python
-
- from lightning_app import LightningApp, LightningFlow, LightningWork
-
-
- class Flow(LightningFlow):
- def __init__(self):
- super().__init__()
-
- self.work = Work(cache_calls=False, parallel=False)
-
- def run(self):
- print("HERE BEFORE")
- self.work.run()
- print("HERE AFTER")
-
-
- app = LightningApp(Flow())
-
-.. code-block:: console
-
- $ lightning run app app.py
- INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
- print("HERE BEFORE")
- print("HERE BEFORE")
- print("HERE BEFORE")
- ...
+.. include:: run_work_once_content.rst
diff --git a/docs/source-app/workflows/run_work_once_content.rst b/docs/source-app/workflows/run_work_once_content.rst
new file mode 100644
index 0000000000..dbef378135
--- /dev/null
+++ b/docs/source-app/workflows/run_work_once_content.rst
@@ -0,0 +1,151 @@
+
+********************************************************
+What caching the calls of Work's run method does for you
+********************************************************
+
+By default, the run method in a LightningWork (Work) "remembers" (caches) the input arguments it is getting called with and does not execute again if called with the same arguments again.
+In other words, the run method only executes when the input arguments have never been seen before.
+
+You can turn caching on or off:
+
+.. code-block:: python
+
+ # Run only when the input arguments change (default)
+ work = MyWork(cache_calls=True)
+
+ # Run everytime regardless of whether input arguments change or not
+ work = MyWork(cache_calls=False)
+
+To better understand this, imagine that every day you want to sequentially download and process some data and then train a model on that data.
+As explained in the `Event Loop guide <../glossary/event_loop.html>`_, the Lightning App runs within an infinite while loop, so the pseudo-code of your application might looks like this:
+
+.. code-block:: python
+
+ from datetime import datetime
+
+ # Lightning code
+ while True: # This is the Lightning Event Loop
+
+ # Your code
+ today = datetime.now().strftime("%D") # '05/25/22'
+ data_processor.run(today)
+ train_model.run(data_processor.data)
+
+In this scenario, you want your components to run ``once`` a day, and no more than that! But your code is running within an infinite loop, how can this even work?
+This is where the Work's internal caching mechanism comes in. By default, Lightning caches a hash of the input provided to its run method and won't re-execute the method if the same input is provided again.
+In the example above, the **data_processor** component run method receives the string **"05/25/22"**. It runs one time and any further execution during the day is skipped until tomorrow is reached and the work run method receives **06/25/22**. This logic applies everyday.
+This caching mechanism is inspired from how `React.js Components and Props `_ renders websites. Only changes to the inputs re-trigger execution.
+
+***************
+Caching Example
+***************
+
+Here's an example of this behavior with LightningWork:
+
+.. code:: python
+ :emphasize-lines: 11, 17
+
+ import lightning as L
+
+
+ class ExampleWork(L.LightningWork):
+ def run(self, *args, **kwargs):
+ print(f"I received the following props: args: {args} kwargs: {kwargs}")
+
+
+ work = ExampleWork()
+ work.run(value=1)
+
+ # Providing the same value. This won't run as already cached.
+ work.run(value=1)
+ work.run(value=1)
+ work.run(value=1)
+ work.run(value=1)
+
+ # Changing the provided value. This isn't cached and will run again.
+ work.run(value=10)
+
+And you should see the following by running the code above:
+
+.. code-block:: console
+
+ $ python example.py
+ INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+ # After you have clicked `run` on the UI.
+ I received the following props: args: () kwargs: {'value': 1}
+ I received the following props: args: () kwargs: {'value': 10}
+
+As you can see, the intermediate run didn't execute, as we would expected when ``cache_calls=True``.
+
+***********************************
+Implications of turning caching off
+***********************************
+
+By setting ``cache_calls=False``, Lightning won't cache the return value and re-execute the run method on every call.
+
+.. code:: python
+ :emphasize-lines: 7
+
+ from lightning_app import LightningWork
+
+
+ class ExampleWork(LightningWork):
+ def run(self, *args, **kwargs):
+ print(f"I received the following props: args: {args} kwargs: {kwargs}")
+
+
+ work = ExampleWork(cache_calls=False)
+ work.run(value=1)
+
+ # Providing the same value. This won't run as already cached.
+ work.run(value=1)
+ work.run(value=1)
+ work.run(value=1)
+ work.run(value=1)
+
+ # Changing the provided value. This isn't cached and will run again.
+ work.run(value=10)
+
+.. code-block:: console
+
+ $ python example.py
+ INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+ # After you have clicked `run` on the UI.
+ I received the following props: args: () kwargs: {'value': 1}
+ I received the following props: args: () kwargs: {'value': 1}
+ I received the following props: args: () kwargs: {'value': 1}
+ I received the following props: args: () kwargs: {'value': 1}
+ I received the following props: args: () kwargs: {'value': 1}
+ I received the following props: args: () kwargs: {'value': 10}
+
+Be aware than when setting both ``cache_calls=False`` and ``parallel=False`` to a work, the code after the ``self.work.run()`` is unreachable
+as the work continuously execute in a blocking way.
+
+.. code-block:: python
+ :emphasize-lines: 9-10
+
+ from lightning_app import LightningApp, LightningFlow, LightningWork
+
+
+ class Flow(LightningFlow):
+ def __init__(self):
+ super().__init__()
+
+ self.work = Work(cache_calls=False, parallel=False)
+
+ def run(self):
+ print("HERE BEFORE")
+ self.work.run()
+ print("HERE AFTER")
+
+
+ app = LightningApp(Flow())
+
+.. code-block:: console
+
+ $ lightning run app app.py
+ INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+ print("HERE BEFORE")
+ print("HERE BEFORE")
+ print("HERE BEFORE")
+ ...
diff --git a/docs/source-app/workflows/schedule_apps.rst b/docs/source-app/workflows/schedule_apps.rst
index e64c64872e..7b596cd08b 100644
--- a/docs/source-app/workflows/schedule_apps.rst
+++ b/docs/source-app/workflows/schedule_apps.rst
@@ -1,3 +1,5 @@
+:orphan:
+
#################
Schedule App Runs
#################
diff --git a/docs/source-app/workflows/share_app.rst b/docs/source-app/workflows/share_app.rst
index 7dd6be7c37..87045bde8d 100644
--- a/docs/source-app/workflows/share_app.rst
+++ b/docs/source-app/workflows/share_app.rst
@@ -30,4 +30,4 @@ Run local:
lightning run app app.py
-then use one of the many guides to `expose a tunnel `.
+And then, use one of the many guides to `expose a tunnel `_.
diff --git a/docs/source-app/workflows/share_files_between_components.rst b/docs/source-app/workflows/share_files_between_components.rst
index 7292236a18..15108515b3 100644
--- a/docs/source-app/workflows/share_files_between_components.rst
+++ b/docs/source-app/workflows/share_files_between_components.rst
@@ -62,7 +62,7 @@ To use a file, pass the reference to the file:
******************************
Use a directory - coming soon
- ***************
+ ******************************
TODO
----
@@ -73,57 +73,32 @@ Example: Share a model checkpoint
A common workflow in ML is to use a checkpoint created by another component.
First, define a component that saves a checkpoint:
-.. code:: python
-
- import lightning_app as lalit
- from lightning_app.storage.path import Path
- import torch
- import os
-
-
- class ModelTraining(lit.LightningWork):
- def __init__(self, *args, **kwargs):
- super().__init__(*args, **kwargs)
- self.model_checkpoints_path = Path("/checkpoints")
-
- def run(self):
- # make fake checkpoints
- checkpoint_1 = torch.tensor([0, 1, 2, 3, 4])
- checkpoint_2 = torch.tensor([0, 1, 2, 3, 4])
- torch.save(checkpoint_1, self.model_checkpoints_path + "checkpoint_1.ckpt")
- torch.save(checkpoint_2, self.model_checkpoints_path + "checkpoint_2.ckpt")
-
+.. literalinclude:: ./share_files_between_components/app.py
+ :lines: -19
Next, define a component that needs the checkpoints:
-.. code:: python
-
- class ModelDeploy(lit.LightningWork):
- def __init__(self, ckpt_path, *args, **kwargs):
- super().__init__()
- self.ckpt_path = ckpt_path
-
- def run(self):
- ckpts = os.list_dir(self.ckpt_path)
- checkpoint_1 = torch.load(ckpts[0])
- checkpoint_2 = torch.load(ckpts[1])
+.. literalinclude:: ./share_files_between_components/app.py
+ :lines: 20-31
Link both components via a parent component:
-.. code:: python
-
- class Root(lit.LightningFlow):
- def __init__(self):
- super().__init__()
- self.train = ModelTraining()
- self.deploy = ModelDeploy(ckpt_path=self.train.model_checkpoints_path)
-
- def run(self):
- self.train.run()
- self.deploy.run()
+.. literalinclude:: ./share_files_between_components/app.py
+ :lines: 32-
- app = lit.LightningApp(Root())
+Run the app above with the following command:
+
+.. code-block:: bash
+
+ lightning run app docs/source-app/workflows/share_files_between_components/app.py
+
+.. code-block:: console
+
+ Your Lightning App is starting. This won't take long.
+ INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view
+ Loaded checkpoint_1: tensor([0, 1, 2, 3, 4])
+ Loaded checkpoint_2: tensor([0, 1, 2, 3, 4])
For example, here we save a file on one component and use it in another component:
@@ -136,7 +111,7 @@ For example, here we save a file on one component and use it in another componen
class ComponentA(LightningWork):
def __init__(self):
super().__init__()
- self.boring_path = Path("boring_file.txt")
+ self.boring_path = None
def run(self):
# This should be used as a REFERENCE to the file.
diff --git a/docs/source-app/workflows/share_files_between_components/app.py b/docs/source-app/workflows/share_files_between_components/app.py
new file mode 100644
index 0000000000..c087fc8117
--- /dev/null
+++ b/docs/source-app/workflows/share_files_between_components/app.py
@@ -0,0 +1,48 @@
+import os
+
+import torch
+
+import lightning as L
+from lightning.app.storage.path import Path
+
+
+class ModelTraining(L.LightningWork):
+ def __init__(self, *args, **kwargs):
+ super().__init__(*args, **kwargs)
+ self.checkpoints_path = Path("./checkpoints")
+
+ def run(self):
+ # make fake checkpoints
+ checkpoint_1 = torch.tensor([0, 1, 2, 3, 4])
+ checkpoint_2 = torch.tensor([0, 1, 2, 3, 4])
+ os.makedirs(self.checkpoints_path, exist_ok=True)
+ checkpoint_path = str(self.checkpoints_path / "checkpoint_{}.ckpt")
+ torch.save(checkpoint_1, str(checkpoint_path).format("1"))
+ torch.save(checkpoint_2, str(checkpoint_path).format("2"))
+
+
+class ModelDeploy(L.LightningWork):
+ def __init__(self, ckpt_path, *args, **kwargs):
+ super().__init__()
+ self.ckpt_path = ckpt_path
+
+ def run(self):
+ ckpts = os.listdir(self.ckpt_path)
+ checkpoint_1 = torch.load(os.path.join(self.ckpt_path, ckpts[0]))
+ checkpoint_2 = torch.load(os.path.join(self.ckpt_path, ckpts[1]))
+ print(f"Loaded checkpoint_1: {checkpoint_1}")
+ print(f"Loaded checkpoint_2: {checkpoint_2}")
+
+
+class LitApp(L.LightningFlow):
+ def __init__(self):
+ super().__init__()
+ self.train = ModelTraining()
+ self.deploy = ModelDeploy(ckpt_path=self.train.checkpoints_path)
+
+ def run(self):
+ self.train.run()
+ self.deploy.run()
+
+
+app = L.LightningApp(LitApp())
diff --git a/docs/source-app/workflows/test_an_app.rst b/docs/source-app/workflows/test_an_app.rst
index d8e48e2b58..c51ae3aa8f 100644
--- a/docs/source-app/workflows/test_an_app.rst
+++ b/docs/source-app/workflows/test_an_app.rst
@@ -1,3 +1,5 @@
+:orphan:
+
###########
Test an App
###########
diff --git a/docs/source-pytorch/Makefile b/docs/source-pytorch/Makefile
new file mode 100644
index 0000000000..68be4c930e
--- /dev/null
+++ b/docs/source-pytorch/Makefile
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+SOURCEDIR = .
+BUILDDIR = ../build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/source-pytorch/conf.py b/docs/source-pytorch/conf.py
index 6ebb32ce87..e75c2ed863 100644
--- a/docs/source-pytorch/conf.py
+++ b/docs/source-pytorch/conf.py
@@ -188,7 +188,7 @@ html_theme_path = [pt_lightning_sphinx_theme.get_html_theme_path()]
html_theme_options = {
"pytorch_project": "https://pytorchlightning.ai",
- "canonical_url": pytorch_lightning.__docs_url__,
+ "canonical_url": pytorch_lightning.__about__.__docs_url__,
"collapse_navigation": False,
"display_version": True,
"logo_only": False,
diff --git a/docs/source-pytorch/make.bat b/docs/source-pytorch/make.bat
new file mode 100644
index 0000000000..9b565142ae
--- /dev/null
+++ b/docs/source-pytorch/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=../build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
diff --git a/src/lightning_app/CHANGELOG.md b/src/lightning_app/CHANGELOG.md
new file mode 100644
index 0000000000..17ad3a0cde
--- /dev/null
+++ b/src/lightning_app/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
+
+## \[0.6.0\] - 2022-MM-DD
+
+### Added
+
+- Update the Lightning App docs ([#13537](https://github.com/PyTorchLightning/pytorch-lightning/pull/13537))
+
+### Changed
+
+### Deprecated
+
+### Fixed
+
diff --git a/docs/source-app/workflows/run_app_on_cloud/cloud_files.rst b/docs/source-app/workflows/run_app_on_cloud/cloud_files.rst
new file mode 100644
index 0000000000..3130cd0f33
--- /dev/null
+++ b/docs/source-app/workflows/run_app_on_cloud/cloud_files.rst
@@ -0,0 +1,58 @@
+.. _ignore:
+
+##################################
+Configure Your Lightning Cloud App
+##################################
+
+**Audience:** Users who want to control Lightning App files on the cloud.
+
+----
+
+**************************************
+Ignore file uploads to Lightning cloud
+**************************************
+Running Lightning Apps on the cloud will upload the source code of your app to the cloud. You can use ``.lightningignore`` file(s) to ignore files or directories while uploading. The `.lightningignore` file follows the same format as a `.gitignore`
+file.
+
+For example, the source code directory below with the ``.lightningignore`` file will ignore the file named
+``model.pt`` and directory named ``data_dir``.
+
+.. code:: bash
+
+ .
+ ├── README.md
+ ├── app.py
+ ├── data_dir
+ │ ├── image1.png
+ │ ├── image2.png
+ │ └── ...
+ ├── .lightningignore
+ ├── requirements.txt
+ └── model.pt
+
+
+.. code:: bash
+
+ ~/project/home ❯ cat .lightningignore
+ model.pt
+ data_dir
+
+A sample ``.lightningignore`` file can be found `here
+
+.. displayitem::
+ :header: Add a web user interface
+ :description: Learn how to add React, StreamLit, Dash to your App.
+ :col_css: col-md-4
+ :button_link: add_web_ui/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Add a web link
+ :description: Learn how to embed external websites
+ :col_css: col-md-4
+ :button_link: add_web_link.html
+ :height: 180
+
+.. displayitem::
+ :header: Arrange App tabs
+ :description: Learn how to organize your UI
+ :col_css: col-md-4
+ :button_link: arrange_tabs/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Build a Lightning App
+ :description: Simple App to get started
+ :col_css: col-md-4
+ :button_link: build_lightning_app/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Build a Lightning Component
+ :description: Understand how to separated the glue from the actual work
+ :col_css: col-md-4
+ :button_link: build_lightning_component/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Cache Work run calls
+ :description: Understand how to trigger a work run method
+ :col_css: col-md-4
+ :button_link: run_work_once.html
+ :height: 180
+
+.. displayitem::
+ :header: Customize your cloud compute
+ :description: Select machines to run on
+ :col_css: col-md-4
+ :button_link: ../core_api/lightning_work/compute.html
+ :height: 180
+
+.. displayitem::
+ :header: Extend an existing App
+ :description: Learn where to go next with an App
+ :col_css: col-md-4
+ :button_link: extend_app.html
+ :height: 180
+
+.. displayitem::
+ :header: Publish a Lightning Component
+ :description: Share your components with others
+ :col_css: col-md-4
+ :button_link: build_lightning_component/publish_a_component.html
+ :height: 180
+
+.. displayitem::
+ :header: Run a server within a Lightning App
+ :description: Lightning Work can be infinite jobs
+ :col_css: col-md-4
+ :button_link: add_server/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Run an App on the cloud
+ :description: Learn how to get things done in the cloud with ease
+ :col_css: col-md-4
+ :button_link: run_app_on_cloud/index.html
+ :height: 180
+
+.. displayitem::
+ :header: Run Works in parallel
+ :description: Learn how to make your Work non blocking
+ :col_css: col-md-4
+ :button_link: run_work_in_parallel.html
+ :height: 180
+
+.. displayitem::
+ :header: Share an App
+ :description: Learn how to share your work with others
+ :col_css: col-md-4
+ :button_link: share_app.html
+ :height: 180
+
+.. displayitem::
+ :header: Share files between components
+ :description: Learn how Lightning Storage emulates a single filesystem in a distributed setting
+ :col_css: col-md-4
+ :button_link: share_files_between_components.html
+ :height: 180
+
+
+.. raw:: html
+
+
+
+
+
+----
+
+************
+Other Clouds
+************
+
+.. raw:: html
+
+
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: Run on Lightning Cloud
+ :description: Learn how to run on the Lightning public cloud
+ :col_css: col-md-4
+ :button_link: lightning_cloud.html
+ :height: 150
+ :tag: basic
+
+.. displayitem::
+ :header: Choose Hardware
+ :description: Configure you app cloud resources
+ :col_css: col-md-4
+ :button_link: ../../core_api/lightning_work/compute.html
+ :height: 150
+ :tag: Basic
+
+.. displayitem::
+ :header: Set Environment Variables
+ :description: Manage your environment variables in the cloud
+ :col_css: col-md-4
+ :button_link: ../../glossary/environment_variables.html
+ :height: 150
+ :tag: Basic
+
+.. displayitem::
+ :header: Configure Your Lightning Cloud App
+ :description: Customize your cloud apps files
+ :col_css: col-md-4
+ :button_link: cloud_files.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Manage App Dependancies
+ :description: Configure your python requirements or use a custom docker image
+ :col_css: col-md-4
+ :button_link: ../../glossary/build_config/build_config.html
+ :height: 150
+ :tag: Intermediate
+
+.. displayitem::
+ :header: Share Files Between Works
+ :description: Learn more about data transfering
+ :col_css: col-md-4
+ :button_link: ../../glossary/storage/storage.html
+ :height: 150
+ :tag: Intermediate
+
+.. raw:: html
+
+
+
+
diff --git a/docs/source-app/workflows/run_app_on_cloud/lightning_cloud.rst b/docs/source-app/workflows/run_app_on_cloud/lightning_cloud.rst
new file mode 100644
index 0000000000..aaa9d7bb08
--- /dev/null
+++ b/docs/source-app/workflows/run_app_on_cloud/lightning_cloud.rst
@@ -0,0 +1,67 @@
+#######################
+Run an App on the Cloud
+#######################
+
+**Audience:** Users who want to share their apps or run on specialized hardware (like GPUs).
+
+----
+
+*********************************
+Run on the public Lightning cloud
+*********************************
+To run any app on the public lightning cloud use the ``--cloud`` argument:
+
+.. code:: bash
+
+ lightning run app app.py --cloud
+
+
+.. note::
+ By default, running your apps on the public Lightning cloud is free of charge using default CPUs, and any app uploaded to the Lightning cloud will be shared with the community (source code and app view will be public). If you would like to make your apps private please `contact us
+
+.. Add callout items below this line
+
+.. displayitem::
+ :header: Run On Your Own Machine
+ :description: Run Lightning Apps on any machine
+ :col_css: col-md-4
+ :button_link: on_your_own_machine.html
+ :height: 150
+ :tag: basic
+
+.. displayitem::
+ :header: Run On Your Private Cloud
+ :description: Run Lightning Apps on your own cloud
+ :col_css: col-md-4
+ :button_link: on_prem.html
+ :height: 150
+ :tag: basic
+
+
+.. raw:: html
+
+
+