Dev/production doc by amd-fuyuajin · Pull Request #824 · AMD-AGI/Primus

amd-fuyuajin · 2026-06-29T04:17:42Z

working on production documentation

lhzhang333 · 2026-06-29T06:37:16Z

+  -- --image rocm/primus:v26.3 train pretrain --config <your-config>.yaml
+```
+
+3. **Config file default** — `container.options.image` in `runner/.primus.yaml` (or your `~/.primus.yaml`), which ships as `rocm/primus:v26.2`.


The Primus version numbers (v26.2/v26.3) need to be aligned, consistent with the main branch.

lhzhang333 · 2026-06-29T06:42:05Z

 - **[CLI Architecture](./cli/CLI-ARCHITECTURE.md)** - Design philosophy and deep dive

-### 📖 User Guides
+### User Guides


Were the icons all removed on purpose or by mistake?

lhzhang333 · 2026-06-29T06:44:07Z

- - **[Megatron Model Extension Guide](./backends/adding-megatron-models.md)** - How to add a new Megatron model config
- - **[TorchTitan Model Extension Guide](./backends/adding-torchtitan-models.md)** - How to add a new TorchTitan model config
+- **[Backend Extension Guide](./backends/extending-backends.md)** - How to add a new backend
+  - **[Megatron Model Extension Guide](./backends/adding-megatron-models.md)** - How to add a new Megatron model config


Unnecessary indentation?

lhzhang333 · 2026-06-29T06:56:45Z

+| `enable_primus_turbo` | `true` | Master flag for Primus-Turbo optimized kernels and paths. |
+| `use_turbo_attention` | `false` | Turbo attention implementation. |
+| `use_turbo_parallel_linear` | `false` | Turbo parallel linear layers. |
+| `use_turbo_grouped_mlp` | `false` | Turbo grouped GEMM/MLP flag for MoE paths (the preset ships this key; in the Megatron preset it is a deprecated alias of `use_turbo_grouped_gemm`). |


use_turbo_grouped_mlp has already been removed in main branch.

dso-amd · 2026-07-07T19:20:50Z

@@ -0,0 +1,139 @@
+# Primus Documentation
+
+Production-grade documentation for the Primus large-scale foundation model training framework on AMD GPUs.


Suggested change

Production-grade documentation for the Primus large-scale foundation model training framework on AMD GPUs.

Production documentation for **Primus**, a large-scale foundation model training framework for AMD GPUs.

Just say ay either "Production documentation" (better, I think, as that is the folder name) or "Complete documentation". It is not a "grade" difference between the short and the full doc.

dso-amd · 2026-07-07T19:42:15Z

+
+---
+
+## Quick Navigation by Audience


The title describes what we are doing here, but sounds a bit odd to the audience themselves. Try something like "Choose your path" or "Choose your starting point". Of course, make sure no links are broken after the title change.

dso-amd · 2026-07-07T19:43:21Z

+
+| I am a... | Start here |
+|-----------|------------|
+| **New user** getting started | [Getting Started](./01-getting-started/overview.md) |


dso-amd · 2026-07-07T19:45:51Z

+
+## Documentation Structure
+
+### [01 - Getting Started](./01-getting-started/)


Because no other section layers are numbered, I suggest removing 01, 02, 03, 04, 05. Of course, make sure links don't break after the changes.

Also, the link seems to link back to itself? Either just remove the link, or, probably better: set up a real "Getting started" landing page, that lists all the topics under it?

The same comment applies to 02, 03, 04 .... etc.

Also: the contents that are listed below appear in the different order in the book. Let's make sure they are synced up in order.

dso-amd · 2026-07-07T19:51:33Z

+
+Start here if you are new to Primus.
+
+- [Project Overview](./01-getting-started/overview.md) -- what Primus does, who it is for, key capabilities


Change all " -- " to just "—" (i.e., use the real em dash in place of --, and do not leave spaces before and after), or to ": " (use colon instead of em dash,).

dso-amd · 2026-07-07T19:51:43Z

+
+Start here if you are new to Primus.
+
+- [Project Overview](./01-getting-started/overview.md) -- what Primus does, who it is for, key capabilities


Suggested change

- [Project Overview](./01-getting-started/overview.md) -- what Primus does, who it is for, key capabilities

- [Project overview](./01-getting-started/overview.md) -- what Primus does, who it is for, key capabilities

dso-amd · 2026-07-07T19:51:58Z

+Start here if you are new to Primus.
+
+- [Project Overview](./01-getting-started/overview.md) -- what Primus does, who it is for, key capabilities
+- [Installation Guide](./01-getting-started/installation.md) -- prerequisites, Docker/bare-metal/Slurm setup


Suggested change

- [Installation Guide](./01-getting-started/installation.md) -- prerequisites, Docker/bare-metal/Slurm setup

- [Installation guide](./01-getting-started/installation.md) -- prerequisites, Docker/bare-metal/Slurm setup

Also see comment on -- for the last line. Same comment applies throughout this page.

dso-amd · 2026-07-07T19:53:03Z

+
+- [Project Overview](./01-getting-started/overview.md) -- what Primus does, who it is for, key capabilities
+- [Installation Guide](./01-getting-started/installation.md) -- prerequisites, Docker/bare-metal/Slurm setup
+- [Quick Start](./01-getting-started/quickstart.md) -- first training run in 5 minutes


Suggested change

- [Quick Start](./01-getting-started/quickstart.md) -- first training run in 5 minutes

- [Quickstart](./01-getting-started/quickstart.md) -- first training run in 5 minutes

dso-amd · 2026-07-07T19:53:52Z

+
+Core workflows and day-to-day usage.
+
+- [CLI Reference](./02-user-guide/cli-reference.md) -- `primus-cli` modes, flags, and subcommands


Suggested change

- [CLI Reference](./02-user-guide/cli-reference.md) -- `primus-cli` modes, flags, and subcommands

- [CLI reference](./02-user-guide/cli-reference.md) -- `primus-cli` modes, flags, and subcommands

We don't use title case. Again, make sure the actual file title is also changed, or at least everything is consistent!

dso-amd · 2026-07-07T19:54:40Z

+Core workflows and day-to-day usage.
+
+- [CLI Reference](./02-user-guide/cli-reference.md) -- `primus-cli` modes, flags, and subcommands
+- [Configuration System](./02-user-guide/configuration-system.md) -- YAML config model, presets, overrides, inheritance


Suggested change

- [Configuration System](./02-user-guide/configuration-system.md) -- YAML config model, presets, overrides, inheritance

- [Configuration system](./02-user-guide/configuration-system.md) -- YAML config model, presets, overrides, inheritance

dso-amd · 2026-07-07T19:54:56Z

+- [CLI Reference](./02-user-guide/cli-reference.md) -- `primus-cli` modes, flags, and subcommands
+- [Configuration System](./02-user-guide/configuration-system.md) -- YAML config model, presets, overrides, inheritance
+- [Pretraining](./02-user-guide/pretraining.md) -- pretraining **concepts**: backends, YAML structure, parallelism, config inventory
+- [Backend Training Recipes](./02-user-guide/training-recipes.md) -- pretraining **commands**: copy-paste, GPU-arch-specific run commands


Suggested change

- [Backend Training Recipes](./02-user-guide/training-recipes.md) -- pretraining **commands**: copy-paste, GPU-arch-specific run commands

- [Backend training recipes](./02-user-guide/training-recipes.md) -- pretraining **commands**: copy-paste, GPU-arch-specific run commands

dso-amd · 2026-07-07T19:55:36Z

+- [Configuration System](./02-user-guide/configuration-system.md) -- YAML config model, presets, overrides, inheritance
+- [Pretraining](./02-user-guide/pretraining.md) -- pretraining **concepts**: backends, YAML structure, parallelism, config inventory
+- [Backend Training Recipes](./02-user-guide/training-recipes.md) -- pretraining **commands**: copy-paste, GPU-arch-specific run commands
+- [Post-Training](./02-user-guide/posttraining.md) -- SFT and LoRA fine-tuning via Megatron Bridge


Suggested change

- [Post-Training](./02-user-guide/posttraining.md) -- SFT and LoRA fine-tuning via Megatron Bridge

- [Post-training](./02-user-guide/posttraining.md) -- SFT and LoRA fine-tuning via Megatron Bridge

dso-amd · 2026-07-07T19:56:03Z

+
+Parameter references for Primus presets, backend-facing keys, and commonly used environment variables.
+
+- [Megatron Parameters](./03-configuration-reference/megatron-parameters.md) -- Megatron-LM backend YAML parameters and Primus overrides


Suggested change

- [Megatron Parameters](./03-configuration-reference/megatron-parameters.md) -- Megatron-LM backend YAML parameters and Primus overrides

- [Megatron parameters](./03-configuration-reference/megatron-parameters.md) -- Megatron-LM backend YAML parameters and Primus overrides

dso-amd · 2026-07-07T19:56:14Z

+Parameter references for Primus presets, backend-facing keys, and commonly used environment variables.
+
+- [Megatron Parameters](./03-configuration-reference/megatron-parameters.md) -- Megatron-LM backend YAML parameters and Primus overrides
+- [TorchTitan Parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields


Suggested change

- [TorchTitan Parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields

- [TorchTitan parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields

dso-amd · 2026-07-07T19:56:33Z

+
+- [Megatron Parameters](./03-configuration-reference/megatron-parameters.md) -- Megatron-LM backend YAML parameters and Primus overrides
+- [TorchTitan Parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields
+- [MaxText Parameters](./03-configuration-reference/maxtext-parameters.md) -- Primus MaxText overlay defaults and common fields


Suggested change

- [MaxText Parameters](./03-configuration-reference/maxtext-parameters.md) -- Primus MaxText overlay defaults and common fields

- [MaxText parameters](./03-configuration-reference/maxtext-parameters.md) -- Primus MaxText overlay defaults and common fields

dso-amd · 2026-07-07T19:57:08Z

+- [Megatron Parameters](./03-configuration-reference/megatron-parameters.md) -- Megatron-LM backend YAML parameters and Primus overrides
+- [TorchTitan Parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields
+- [MaxText Parameters](./03-configuration-reference/maxtext-parameters.md) -- Primus MaxText overlay defaults and common fields
+- [Megatron Bridge Parameters](./03-configuration-reference/megatron-bridge-parameters.md) -- Megatron Bridge recipe, SFT, and pretraining fields surfaced through Primus


Suggested change

- [Megatron Bridge Parameters](./03-configuration-reference/megatron-bridge-parameters.md) -- Megatron Bridge recipe, SFT, and pretraining fields surfaced through Primus

- [Megatron Bridge parameters](./03-configuration-reference/megatron-bridge-parameters.md) -- Megatron Bridge recipe, SFT, and pretraining fields surfaced through Primus

dso-amd · 2026-07-07T19:57:16Z

+- [TorchTitan Parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields
+- [MaxText Parameters](./03-configuration-reference/maxtext-parameters.md) -- Primus MaxText overlay defaults and common fields
+- [Megatron Bridge Parameters](./03-configuration-reference/megatron-bridge-parameters.md) -- Megatron Bridge recipe, SFT, and pretraining fields surfaced through Primus
+- [Environment Variables](./03-configuration-reference/environment-variables.md) -- practical reference for commonly encountered environment variables


Suggested change

- [Environment Variables](./03-configuration-reference/environment-variables.md) -- practical reference for commonly encountered environment variables

- [Environment variables](./03-configuration-reference/environment-variables.md) -- practical reference for commonly encountered environment variables

dso-amd · 2026-07-07T19:57:31Z

+- [Megatron Bridge Parameters](./03-configuration-reference/megatron-bridge-parameters.md) -- Megatron Bridge recipe, SFT, and pretraining fields surfaced through Primus
+- [Environment Variables](./03-configuration-reference/environment-variables.md) -- practical reference for commonly encountered environment variables
+
+### [04 - Technical Guides](./04-technical-guides/)


Suggested change

### [04 - Technical Guides](./04-technical-guides/)

### [04 - Technical guides](./04-technical-guides/)

dso-amd · 2026-07-07T19:58:03Z

+
+Deep technical topics for advanced users.
+
+- [Parallelism Strategies](./04-technical-guides/parallelism-strategies.md) -- DP, TP, PP, SP, CP, EP, FSDP explained


Change all titles to use sentence case. I will skipping commenting them one by one below....

dso-amd · 2026-07-07T20:02:26Z

+
+## Executive summary
+
+**Primus (Primus-LM)** is a YAML-driven training framework for large-scale foundation model work on AMD GPUs (ROCm). It targets **machine learning engineers**, **researchers**, and **platform/operations teams** who need reproducible, multi-backend training pipelines on AMD Instinct hardware.


It is not clear what is Primus-LM and how it is related to Primus. Either add some explanations, for remove Primus-LM.

dso-amd · 2026-07-07T20:17:50Z

+
+**Repository:** [https://github.com/AMD-AIG-AIMA/Primus](https://github.com/AMD-AIG-AIMA/Primus)
+
+**License:** The project README states Apache License 2.0; the repository root `LICENSE` file is MIT. Treat licensing as project-specific and confirm with your compliance process before redistribution.


This does not look to be the right place for discussing licensing. And it's also not clear when we have 2 licenses for this software, and what should users do with that. Move this to e.g. end of the doc (?), and give clear explanations.

dso-amd · 2026-07-07T20:19:11Z

+| **Multi-backend training** | One workflow surface over Megatron-LM, TorchTitan, JAX MaxText, Megatron Bridge, and HummingbirdXT. |
+| **Unified CLI** | `primus-cli` with **direct** (bare metal), **container** (Docker/Podman), and **slurm** (cluster) execution modes. |
+| **YAML-driven configuration** | Experiment, model, module, and platform presets composed from reusable fragments under `primus/configs/`. |
+| **Benchmark suite** | Built-in benchmarks (for example GEMM) for quick hardware and stack validation. |


Suggested change

| **Benchmark suite** | Built-in benchmarks (for example GEMM) for quick hardware and stack validation. |

| **Benchmark suite** | Built-in benchmarks (for example, GEMM) for quick hardware and stack validation. |

dso-amd · 2026-07-07T20:21:48Z

+| **Preflight diagnostics** | Cluster-oriented checks for host, GPU, and network health before long jobs. |
+| **Performance projection** | Tools to estimate memory use and throughput without occupying a full cluster. |
+
+Workflows span **pretraining** and **post-training** (including SFT and LoRA). Some Megatron configuration files include RL-related parameters, but this doc set does not treat RL workflows as publication-ready until maintainers add examples and support guidance.


Shouldn't discuss there what is or is not publication ready and when they will be published. Explain it better here why RL workflows are not published (without promising we will publish them).

dso-amd · 2026-07-08T20:39:27Z

+| **Network** | Network configuration relevant to distributed training |
+| **Performance tests** | Heavier GEMM and communication tests (slower than info-only) |
+
+Running `preflight` with **no selection flags** runs the full workflow (informational report plus performance tests). Narrow flags restrict work to the pieces you need.


This is redundant, as it is illustrated below. Remove?

dso-amd · 2026-07-08T20:39:48Z

+primus-cli direct -- preflight --host --gpu --network
+```
+
+### Full preflight (info and performance tests)


Suggested change

### Full preflight (info and performance tests)

### Full preflight (information and performance tests)

dso-amd · 2026-07-08T20:41:17Z

+primus-cli direct -- preflight --host --gpu --network
+```
+
+### Full preflight (info and performance tests)


Suggested change

### Full preflight (info and performance tests)

### Full preflight (information and performance tests)

dso-amd · 2026-07-08T20:41:45Z

+
+### Performance tests only
+
+Skips the host/GPU/network info report and runs GEMM + communication tests.


Suggested change

Skips the host/GPU/network info report and runs GEMM + communication tests.

Skips the host, GPU, and network information report and runs GEMM + communication tests.

dso-amd · 2026-07-08T20:43:27Z

+| `--host` | Include host information (CPU, memory, PCIe). Alias: `--check-host`. |
+| `--gpu` | Include GPU information. Alias: `--check-gpu`. |
+| `--network` | Include network information. Alias: `--check-network`. |
+| `--perf-test` | Run **only** performance tests (GEMM and intra/inter-node communication); skips the info report. |


Suggested change

| `--perf-test` | Run **only** performance tests (GEMM and intra/inter-node communication); skips the info report. |

| `--perf-test` | Run **only** performance tests (GEMM plus intra- and inter-node communication); skip the information report. |

dso-amd · 2026-07-08T20:46:18Z

+| `--network` | Include network information. Alias: `--check-network`. |
+| `--perf-test` | Run **only** performance tests (GEMM and intra/inter-node communication); skips the info report. |
+| `--plot` | Generate plots when used with `--perf-test`. |
+| `--dist-timeout-sec` | Timeout in seconds for `torch.distributed` process-group init (default: 120). On failure, preflight still attempts to write the info report and exits non-zero. |


Suggested change

| `--dist-timeout-sec` | Timeout in seconds for `torch.distributed` process-group init (default: 120). On failure, preflight still attempts to write the info report and exits non-zero. |

| `--dist-timeout-sec` | Timeout in seconds for `torch.distributed` process-group initialization (default: 120). On failure, `preflight` still attempts to write the information report and exits with a non-zero status. |

dso-amd · 2026-07-08T20:49:37Z

+
+**Behavior notes**
+
+- With **no** `--host`, `--gpu`, or `--network` flags and **no** `--perf-test`, preflight runs the **full** default (info plus perf tests).


Suggested change

- With **no** `--host`, `--gpu`, or `--network` flags and **no** `--perf-test`, preflight runs the **full** default (info plus perf tests).

- With **no** `--host`, `--gpu`, or `--network` flags and **no** `--perf-test`, `preflight` runs in the **full** workflow (information plus performance tests).

dso-amd · 2026-07-08T20:49:52Z

+**Behavior notes**
+
+- With **no** `--host`, `--gpu`, or `--network` flags and **no** `--perf-test`, preflight runs the **full** default (info plus perf tests).
+- Combine `--host`, `--gpu`, and `--network` to limit the informational report to those sections.


Suggested change

- Combine `--host`, `--gpu`, and `--network` to limit the informational report to those sections.

- Combine `--host`, `--gpu`, and `--network` to limit the information report to include only those sections.

dso-amd · 2026-07-08T20:51:43Z

+primus-cli direct -- preflight --host --gpu --network
+```
+
+### Multi-node (Slurm example)


Suggested change

### Multi-node (Slurm example)

### Multi-node (Slurm mode)

dso-amd · 2026-07-08T20:52:04Z

+primus-cli slurm srun -N 4 -- preflight --host --gpu --network
+```
+
+Full preflight:


Suggested change

Full preflight:

Full `preflight`:

dso-amd · 2026-07-08T20:54:11Z

+primus-cli slurm srun -N 4 -- preflight --perf-test
+```
+
+Use the same launcher pattern you rely on for training so distributed environment variables (`WORLD_SIZE`, `RANK`, `MASTER_ADDR`, etc.) are consistent.


Suggested change

Use the same launcher pattern you rely on for training so distributed environment variables (`WORLD_SIZE`, `RANK`, `MASTER_ADDR`, etc.) are consistent.

Use the same launcher pattern you reply on for training to ensure that distributed environment variables (`WORLD_SIZE`, `RANK`, `MASTER_ADDR`, etc.) are consistent.

dso-amd · 2026-07-08T20:54:37Z

+
+| File(s) | Contents |
+|---------|----------|
+| `<name>.md` / `<name>.pdf` | **Informational** report: host, GPU, and network sections when those checks are enabled. |


Suggested change

| `<name>.md` / `<name>.pdf` | **Informational** report: host, GPU, and network sections when those checks are enabled. |

| `<name>.md` / `<name>.pdf` | **Information** report: host, GPU, and network sections when those checks are enabled. |

dso-amd · 2026-07-08T20:55:08Z

+| File(s) | Contents |
+|---------|----------|
+| `<name>.md` / `<name>.pdf` | **Informational** report: host, GPU, and network sections when those checks are enabled. |
+| `<name>_perf.md` / `<name>_perf.pdf` | **Performance** report: GEMM and communication results from the perf test path. |


Suggested change

| `<name>_perf.md` / `<name>_perf.pdf` | **Performance** report: GEMM and communication results from the perf test path. |

| `<name>_perf.md` / `<name>_perf.pdf` | **Performance** report: GEMM and communication results from the performance test path. |

dso-amd · 2026-07-08T20:55:40Z

+
+## Interpreting results
+
+1. **Info report:** Confirm GPU count, model match expectations, and PCIe topology is sensible for your workload. Network sections should reflect the interfaces you intend for distributed training.


Suggested change

1. **Info report:** Confirm GPU count, model match expectations, and PCIe topology is sensible for your workload. Network sections should reflect the interfaces you intend for distributed training.

1. **Information report:** Confirm GPU count, model match expectations, and PCIe topology is sensible for your workload. Network sections should reflect the interfaces you intend for distributed training.

dso-amd · 2026-07-08T20:55:56Z

+## Interpreting results
+
+1. **Info report:** Confirm GPU count, model match expectations, and PCIe topology is sensible for your workload. Network sections should reflect the interfaces you intend for distributed training.
+2. **Perf report:** Compare GEMM and collective results across nodes. Large outliers on one node often indicate driver, fabric, or process placement issues.


Suggested change

2. **Perf report:** Compare GEMM and collective results across nodes. Large outliers on one node often indicate driver, fabric, or process placement issues.

2. **Performance report:** Compare GEMM and collective results across nodes. Large outliers on one node often indicate driver, fabric, or process placement issues.

dso-amd · 2026-07-08T20:56:39Z

+
+1. **Info report:** Confirm GPU count, model match expectations, and PCIe topology is sensible for your workload. Network sections should reflect the interfaces you intend for distributed training.
+2. **Perf report:** Compare GEMM and collective results across nodes. Large outliers on one node often indicate driver, fabric, or process placement issues.
+3. **Timeouts:** If `--dist-timeout-sec` is exceeded, inspect firewall rules, interface bindings, and `MASTER_ADDR` / `MASTER_PORT` before scaling up training.


Suggested change

3. **Timeouts:** If `--dist-timeout-sec` is exceeded, inspect firewall rules, interface bindings, and `MASTER_ADDR` / `MASTER_PORT` before scaling up training.

3. **Timeouts:** If `--dist-timeout-sec` is exceeded, inspect firewall rules, interface bindings, `MASTER_ADDR`, and `MASTER_PORT` before scaling up training.

dso-amd · 2026-07-08T20:57:41Z

+
+| Symptom | What to verify in reports |
+|---------|---------------------------|
+| Missing or wrong GPU count | GPU section; ROCm health on the node |


dso-amd · 2026-07-08T20:57:52Z

+| Symptom | What to verify in reports |
+|---------|---------------------------|
+| Missing or wrong GPU count | GPU section; ROCm health on the node |
+| Wrong network device or address | Network section; NCCL/RCCL environment |


dso-amd · 2026-07-08T20:58:10Z

+|---------|---------------------------|
+| Missing or wrong GPU count | GPU section; ROCm health on the node |
+| Wrong network device or address | Network section; NCCL/RCCL environment |
+| Slow or asymmetric inter-node comm | Perf report; compare ranks or nodes |


dso-amd · 2026-07-08T21:01:18Z

+| Missing or wrong GPU count | GPU section; ROCm health on the node |
+| Wrong network device or address | Network section; NCCL/RCCL environment |
+| Slow or asymmetric inter-node comm | Perf report; compare ranks or nodes |
+| Hangs at distributed init | Use `--dist-timeout-sec`; check rendezvous and Slurm network setup |


Suggested change

| Hangs at distributed init | Use `--dist-timeout-sec`; check rendezvous and Slurm network setup |

| Hangs at distributed process group initialization | Use `--dist-timeout-sec` to avoid, then check rendezvous and Slurm network setup |

…xamples

…_docs

amd-fuyuajin requested review from Xiaoming-AMD, limou102 and wenxie-amd as code owners June 29, 2026 04:17

lhzhang333 reviewed Jun 29, 2026

View reviewed changes

dso-amd reviewed Jul 7, 2026

View reviewed changes

dso-amd reviewed Jul 8, 2026

View reviewed changes

amd-fuyuajin added 8 commits July 10, 2026 14:20

draft production documentation

b889fff

docs: verify and correct production_docs against code, configs, and e…

cb6616e

…xamples

update installation.md

d667eb2

verify documentation part 01

56a7598

verified documentation part 02

c217500

update documents part 02 pretraining.md

5c06b69

update documentation part 03 and 04

c72920b

update documentation part 05 and 06

e59ecf8

amd-fuyuajin force-pushed the dev/production-doc branch from 2894067 to e59ecf8 Compare July 10, 2026 14:22

style: fix trailing whitespace and end-of-file newlines in production…

a6a5523

…_docs

		@@ -0,0 +1,139 @@
		# Primus Documentation

		Production-grade documentation for the Primus large-scale foundation model training framework on AMD GPUs.

	Production-grade documentation for the Primus large-scale foundation model training framework on AMD GPUs.
	Production documentation for Primus, a large-scale foundation model training framework for AMD GPUs.

	\| New user getting started \| [Getting Started](./01-getting-started/overview.md) \|
	\| New user \| [Getting Started](./01-getting-started/overview.md) \|


		## Documentation Structure

		### [01 - Getting Started](./01-getting-started/)


		Start here if you are new to Primus.

		- [Project Overview](./01-getting-started/overview.md) -- what Primus does, who it is for, key capabilities

	- [Installation Guide](./01-getting-started/installation.md) -- prerequisites, Docker/bare-metal/Slurm setup
	- [Installation guide](./01-getting-started/installation.md) -- prerequisites, Docker/bare-metal/Slurm setup

	- [Quick Start](./01-getting-started/quickstart.md) -- first training run in 5 minutes
	- [Quickstart](./01-getting-started/quickstart.md) -- first training run in 5 minutes


		Core workflows and day-to-day usage.

		- [CLI Reference](./02-user-guide/cli-reference.md) -- `primus-cli` modes, flags, and subcommands

	- [Configuration System](./02-user-guide/configuration-system.md) -- YAML config model, presets, overrides, inheritance
	- [Configuration system](./02-user-guide/configuration-system.md) -- YAML config model, presets, overrides, inheritance

	- [Backend Training Recipes](./02-user-guide/training-recipes.md) -- pretraining commands: copy-paste, GPU-arch-specific run commands
	- [Backend training recipes](./02-user-guide/training-recipes.md) -- pretraining commands: copy-paste, GPU-arch-specific run commands

	- [Post-Training](./02-user-guide/posttraining.md) -- SFT and LoRA fine-tuning via Megatron Bridge
	- [Post-training](./02-user-guide/posttraining.md) -- SFT and LoRA fine-tuning via Megatron Bridge


		Parameter references for Primus presets, backend-facing keys, and commonly used environment variables.

		- [Megatron Parameters](./03-configuration-reference/megatron-parameters.md) -- Megatron-LM backend YAML parameters and Primus overrides

	- [TorchTitan Parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields
	- [TorchTitan parameters](./03-configuration-reference/torchtitan-parameters.md) -- Primus TorchTitan preset keys and common JobConfig fields

	- [MaxText Parameters](./03-configuration-reference/maxtext-parameters.md) -- Primus MaxText overlay defaults and common fields
	- [MaxText parameters](./03-configuration-reference/maxtext-parameters.md) -- Primus MaxText overlay defaults and common fields

	- [Megatron Bridge Parameters](./03-configuration-reference/megatron-bridge-parameters.md) -- Megatron Bridge recipe, SFT, and pretraining fields surfaced through Primus
	- [Megatron Bridge parameters](./03-configuration-reference/megatron-bridge-parameters.md) -- Megatron Bridge recipe, SFT, and pretraining fields surfaced through Primus

	- [Environment Variables](./03-configuration-reference/environment-variables.md) -- practical reference for commonly encountered environment variables
	- [Environment variables](./03-configuration-reference/environment-variables.md) -- practical reference for commonly encountered environment variables

	### [04 - Technical Guides](./04-technical-guides/)
	### [04 - Technical guides](./04-technical-guides/)


		Deep technical topics for advanced users.

		- [Parallelism Strategies](./04-technical-guides/parallelism-strategies.md) -- DP, TP, PP, SP, CP, EP, FSDP explained


		## Executive summary

		Primus (Primus-LM) is a YAML-driven training framework for large-scale foundation model work on AMD GPUs (ROCm). It targets machine learning engineers, researchers, and platform/operations teams who need reproducible, multi-backend training pipelines on AMD Instinct hardware.


		Repository: [https://github.com/AMD-AIG-AIMA/Primus](https://github.com/AMD-AIG-AIMA/Primus)

		License: The project README states Apache License 2.0; the repository root `LICENSE` file is MIT. Treat licensing as project-specific and confirm with your compliance process before redistribution.

Uh oh!

Conversation

amd-fuyuajin commented Jun 29, 2026

Uh oh!

lhzhang333 Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dso-amd Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lhzhang333 Jun 29, 2026 •

edited

Loading

dso-amd Jul 8, 2026 •

edited

Loading

dso-amd Jul 8, 2026 •

edited

Loading

	\| Benchmark suite \| Built-in benchmarks (for example GEMM) for quick hardware and stack validation. \|
	\| Benchmark suite \| Built-in benchmarks (for example, GEMM) for quick hardware and stack validation. \|

	### Full preflight (info and performance tests)
	### Full preflight (information and performance tests)


		### Performance tests only

		Skips the host/GPU/network info report and runs GEMM + communication tests.

	Skips the host/GPU/network info report and runs GEMM + communication tests.
	Skips the host, GPU, and network information report and runs GEMM + communication tests.

	\| `--perf-test` \| Run only performance tests (GEMM and intra/inter-node communication); skips the info report. \|
	\| `--perf-test` \| Run only performance tests (GEMM plus intra- and inter-node communication); skip the information report. \|

	\| `--dist-timeout-sec` \| Timeout in seconds for `torch.distributed` process-group init (default: 120). On failure, preflight still attempts to write the info report and exits non-zero. \|
	\| `--dist-timeout-sec` \| Timeout in seconds for `torch.distributed` process-group initialization (default: 120). On failure, `preflight` still attempts to write the information report and exits with a non-zero status. \|


		Behavior notes

		- With no `--host`, `--gpu`, or `--network` flags and no `--perf-test`, preflight runs the full default (info plus perf tests).

	- Combine `--host`, `--gpu`, and `--network` to limit the informational report to those sections.
	- Combine `--host`, `--gpu`, and `--network` to limit the information report to include only those sections.

	Use the same launcher pattern you rely on for training so distributed environment variables (`WORLD_SIZE`, `RANK`, `MASTER_ADDR`, etc.) are consistent.
	Use the same launcher pattern you reply on for training to ensure that distributed environment variables (`WORLD_SIZE`, `RANK`, `MASTER_ADDR`, etc.) are consistent.

	\| `<name>.md` / `<name>.pdf` \| Informational report: host, GPU, and network sections when those checks are enabled. \|
	\| `<name>.md` / `<name>.pdf` \| Information report: host, GPU, and network sections when those checks are enabled. \|