chore: import upstream snapshot with attribution

doc/source/train/common/torch-configure-run.rst

@@ -0,0 +1,86 @@
+Configure scale and GPUs
+------------------------
+
+Outside of your training function, create a :class:`~ray.train.ScalingConfig` object to configure:
+
+1. :class:`num_workers <ray.train.ScalingConfig>` - The number of distributed training worker processes.
+2. :class:`use_gpu <ray.train.ScalingConfig>` - Whether each worker should use a GPU (or CPU).
+
+.. testcode::
+
+    from ray.train import ScalingConfig
+    scaling_config = ScalingConfig(num_workers=2, use_gpu=True)
+
+
+For more details, see :ref:`train_scaling_config`.
+
+Configure persistent storage
+----------------------------
+
+Create a :class:`~ray.train.RunConfig` object to specify the path where results
+(including checkpoints and artifacts) will be saved.
+
+.. testcode::
+
+    from ray.train import RunConfig
+
+    # Local path (/some/local/path/unique_run_name)
+    run_config = RunConfig(storage_path="/some/local/path", name="unique_run_name")
+
+    # Shared cloud storage URI (s3://bucket/unique_run_name)
+    run_config = RunConfig(storage_path="s3://bucket", name="unique_run_name")
+
+    # Shared NFS path (/mnt/nfs/unique_run_name)
+    run_config = RunConfig(storage_path="/mnt/nfs", name="unique_run_name")
+
+
+.. warning::
+
+    Specifying a *shared storage location* (such as cloud storage or NFS) is
+    *optional* for single-node clusters, but it is **required for multi-node clusters.**
+    Using a local path will :ref:`raise an error <multinode-local-storage-warning>`
+    during checkpointing for multi-node clusters.
+
+
+For more details, see :ref:`persistent-storage-guide`.
+
+
+Launch a training job
+---------------------
+
+Tying this all together, you can now launch a distributed training job
+with a :class:`~ray.train.torch.TorchTrainer`.
+
+.. testcode::
+    :hide:
+
+    from ray.train import ScalingConfig
+
+    train_func = lambda: None
+    scaling_config = ScalingConfig(num_workers=1)
+    run_config = None
+
+.. testcode::
+
+    from ray.train.torch import TorchTrainer
+
+    trainer = TorchTrainer(
+        train_func, scaling_config=scaling_config, run_config=run_config
+    )
+    result = trainer.fit()
+
+
+Access training results
+-----------------------
+
+After training completes, a :class:`~ray.train.Result` object is returned which contains
+information about the training run, including the metrics and checkpoints reported during training.
+
+.. testcode::
+
+    result.metrics     # The metrics reported during training.
+    result.checkpoint  # The latest checkpoint reported during training.
+    result.path        # The path where logs are stored.
+    result.error       # The exception that was raised, if training failed.
+
+For more usage examples, see :ref:`train-inspect-results`.

doc/source/train/common/torch-configure-train_func.rst

@@ -0,0 +1,51 @@
+First, update your training code to support distributed training.
+Begin by wrapping your code in a :ref:`training function <train-overview-training-function>`:
+
+.. testcode::
+    :skipif: True
+
+    def train_func():
+        # Your model training code here.
+        ...
+
+Each distributed training worker executes this function.
+
+You can also specify the input argument for `train_func` as a dictionary via the Trainer's `train_loop_config`. For example:
+
+.. testcode:: python
+    :skipif: True
+
+    def train_func(config):
+        lr = config["lr"]
+        num_epochs = config["num_epochs"]
+
+    config = {"lr": 1e-4, "num_epochs": 10}
+    trainer = ray.train.torch.TorchTrainer(train_func, train_loop_config=config, ...)
+
+.. warning::
+
+    Avoid passing large data objects through `train_loop_config` to reduce the
+    serialization and deserialization overhead. Instead, it's preferred to
+    initialize large objects (e.g. datasets, models) directly in `train_func`.
+
+    .. code-block:: diff
+
+         def load_dataset():
+             # Return a large in-memory dataset
+             ...
+
+         def load_model():
+             # Return a large in-memory model instance
+             ...
+
+        -config = {"data": load_dataset(), "model": load_model()}
+
+         def train_func(config):
+        -    data = config["data"]
+        -    model = config["model"]
+
+        +    data = load_dataset()
+        +    model = load_model()
+             ...
+
+         trainer = ray.train.torch.TorchTrainer(train_func, train_loop_config=config, ...)