reworked introduction

Author: boeschf

docs/software/ml/index.md

@@ -1,25 +1,69 @@
 [](){#ref-software-ml}
 # Machine Learning Applications and Frameworks
 
-## Containerized Machine Learning Applications
+## Overview
 
-CSCS supports a variety of machine learning applications and frameworks on its
-systems. Typically, machine learning applications are containerized to ensure
-compatibility and ease of use across different environments.
+CSCS supports a wide range of machine learning (ML) applications and frameworks
+on its systems. Most ML workloads are containerized to ensure portability,
+reproducibility, and ease of use across environments.
 
-CSCS does not provide any specific machine learning container images, but users
-can create their own containers using popular base container registries, such
-as [Nvidia's NGC Catalog](https://catalog.ngc.nvidia.com/containers). These
-containers can be run on Alps, allowing users to leverage the
-high-performance computing resources available for their machine learning
-tasks.
+Users can choose between running containers, using provided uenv software
+stacks, or building custom Python environments tailored to their needs.
 
-* Jobs using containers can be easily set up and submitted using the [container
-  engine][ref-container-engine].
-* To build images, see the [guide to building container images on
-  Alps][ref-build-containers].
+## Running Machine Learning Applications with Containers
 
-## Uenv Software Stacks
+Containerization is the recommended approach for ML workloads on Alps, as it
+simplifies software management and maximizes compatibility with other systems.
+
+* CSCS does not provide ready-to-use ML container images
+* Users are encouraged to build their own containers, starting from popular
+  sources such as the [Nvidia NGC
+  Catalog](https://catalog.ngc.nvidia.com/containers)
+
+Helpful references:
+
+* Running containers on Alps: [Container Engine Guide][ref-container-engine]
+* Building custom container images: [Container Build
+  Guide][ref-build-containers]
+
+## Using Provided uenv Software Stacks
+
+Alternatively, CSCS provides pre-configured software stacks ([uenvs][ref-uenv])
+that can serve as a starting point for machine learning projects. These
+environments provide optimized compilers, libraries, and selected ML
+frameworks.
+
+Available ML-related uenvs:
+
+* [PyTorch][ref-uenv-pytorch] — available on [Clariden][ref-cluster-clariden]
+  and [Daint][ref-cluster-daint]
+
+To extend these environments with additional Python packages, it is recommended
+to create a Python Virtual Environment (venv). See this [PyTorch venv
+example][ref-uenv-pytorch-venv] for details.
+
+!!! note
+    While many Python packages provide pre-built binaries for common
+    architectures, some may require building from source.
+
+## Building Custom Python Environments
+
+Users may also choose to build entirely custom software stacks using Python
+package managers such as `pip` or `conda`. Most ML libraries are available via
+the [Python Package Index (PyPI)](https://pypi.org/).
+
+To ensure optimal performance on CSCS systems, we recommend starting from an
+environment that already includes:
+
+* CUDA, cuDNN
+* MPI, NCCL
+* c/c++ compilers
+
+This can be achieved either by:
+
+* Building a [custom container image][ref-build-containers] based on a suitable
+  ML-ready base image.
+* Starting from a provided uenv (e.g., [PrgEnv GNU][ref-uenv-prgenv-gnu] or
+  [PyTorch uenv][ref-uenv-pytorch]) and extending it with a virtual
+  environment.
 
-CSCS provides a base [PyTorch uenv][ref-uenv-pytorch] that is available on the
-[Clariden][ref-cluster-clariden] and [Daint][ref-cluster-daint] cluster.

docs/software/ml/pytorch.md

@@ -284,6 +284,7 @@ There are two ways to access the software provided by the uenv, once it has been
 
     [Check out the guide for using Spack with uenv][ref-building-uenv-spack].
 
+[](){#ref-uenv-pytorch-venv}
 ## Adding Python packages on top of the uenv
 
 Uenvs are read-only, and cannot be modified. However, it is possible to add Python packages on top of the uenv using virtual environments.