Skip to content
Skills Library
Science & research · Building & coding

reactantnitro-accelerators

/reactantnitro-accelerators

Choosing and configuring the accelerator a ReactantNitro run executes on: CPU, CUDA, ROCm, TPU, and how many devices it shards over. The one-process-one-XLA model, `setup_devices!` (REPL) and its tool form `nitro_setup` (Kaimon) as one shared code path, the `n_devs` pin and its precedence, and `CUDA_VISIBLE_DEVICES` for restricting GPUs. Invoke when starting a run on a specific accelerator, when a run unexpectedly uses the wrong backend or the wrong number of devices, or when deciding what `n_devs` means for a session.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Choosing and configuring the accelerator a ReactantNitro run executes on: CPU, CUDA, ROCm, TPU, and how many devices it shards over. The one-process-one-XLA model, `setup_devices!` (REPL) and its tool form `nitro_setup` (Kaimon) as one shared code path, the `n_devs` pin and its precedence, and `CUDA_VISIBLE_DEVICES` for restricting GPUs. Invoke when starting a run on a specific accelerator, when a run unexpectedly uses the wrong backend or the wrong number of devices, or when deciding what `n_devs` means for a session.

Original author description

Choosing and configuring the accelerator a ReactantNitro run executes on: CPU, CUDA, ROCm, TPU, and how many devices it shards over. The one-process-one-XLA model, `setup_devices!` (REPL) and its tool form `nitro_setup` (Kaimon) as one shared code path, the `n_devs` pin and its precedence, and `CUDA_VISIBLE_DEVICES` for restricting GPUs. Invoke when starting a run on a specific accelerator, when a run unexpectedly uses the wrong backend or the wrong number of devices, or when deciding what `n_devs` means for a session.

How it works

  1. The model: one process, one XLA
  2. Choosing the backend
  3. ndevs: what it is and what it is not
  4. Restricting GPUs: CUDAVISIBLEDEVICES
  5. Reading the current state
Original SKILL.md headings · 110 lines, 872 words
SKILL.md preview
---
name: reactantnitro-accelerators
description: >
  Choosing and configuring the accelerator a ReactantNitro run executes on: CPU, CUDA, ROCm,
  TPU, and how many devices it shards over. The one-process-one-XLA model, `setup_devices!`
  (REPL) and its tool form `nitro_setup` (Kaimon) as one shared code path, the `n_devs` pin
  and its precedence, and `CUDA_VISIBLE_DEVICES` for restricting GPUs. Invoke when starting a
  run on a specific accelerator, when a run unexpectedly uses the wrong backend or the wrong
  number of devices, or when deciding what `n_devs` means for a session.
---

# Accelerators and devices

## The model: one process, one XLA

A Julia process initializes its XLA/PJRT client **once**, at the first device access, and the
client is then fixed for the process's lifetime. Everything in this page is a consequence of
that fact:

- **`n_devs` never creates clients or processes.** It slices the already-visible device set to
  build the `Sharding.Mesh`; XLA partitions ONE compiled program over that mesh. There is
  no MPI and no NCCL here, and `n_devs = 4` is not "four training processes".
- **Backend choice is a process event.** Reactant's default backend is the highest-priority
  working one, decided at first device access (GPU where one is visible, else CPU). Changing
  the backend after the fact is allowed (`set_default_backend` swaps the pointer) but device
  VISIBILITY is frozen: `CUDA_VISIBLE_DEVICES` must be set before the process starts.
- **The CPU backend reports a single device.** With no GPU visible, `Reactant.devices()`
  returns one device, so a CPU session's `n_devs` is 1 and the mesh is skipped.

## Choosing the backend

One code path, two entry points: the framework function `ReactantNitro.setup_devices!`, and the
Kaimon tool `nitro_setup`, which is a thin wrapper over exactly that function. A REPL session
and a Kaimon session therefore configure identically.

**REPL / a script (the non-Kaimon workflow):**

```julia
using ReactantNitro
setup_devices!(backend = "cpu")            # run everything on CPU
setup_devices!(backend = "cuda", n_devs = 2)  # two of the visible CUDA devices
setup_devices!()                           # report what is in effect
```

`backend` passes through to `Reactant.set_default_backend` and names a Reactant backend:
`"cpu"`, `"gpu"` (whichever of CUDA/ROCm is available), `"cuda"`, `"rocm"`, `"tpu"`.

**Kaimon (the tool form):**

```julia
nitro_setup(backend = "cpu")
nitro_setup(backend = "cuda", n_devs = 2)
nitro_setup()   # report
```

The tool returns a one-line report; the function returns `(; backend, visible, n_devs, pinned)`.

**Calling it is optional.** A session that never calls it runs on Reactant's default backend
with `n_devs` = every visible device, `length(Reactant.devices())`, which is what a CPU
machine gets automatically. The setup call exists to be explicit and to fail fast: an unknown
backend or a device count larger than what is visible is a loud error, not a silent fallback.

**If you are porting:** your model may have run under a different framework where the backend
was chosen per-run or per-process via environment or a config file. Here the backend is set at
the process level before any run, and a run never re-selects it.

## `n_devs`: what it is and what it is not

- It is the number of LOCAL, VISIBLE devices the batch is sharded over on the `:data` axis of a
  1-D mesh. `1` skips the mesh entirely.
- It is NOT a process count, a batch multiplier, or a memory setting. The batch size is GLOBAL
  and is split across the mesh: `batch_size = 32` on four devices puts 8 samples on each, and
  its numerics are those of a 32-sample batch, not a 128-sample one. Adding devices buys
  throughput and does not change the effective batch.
- The default is every visible device, so a host with four GPUs data-parallelizes **without
  being asked**. If that is surprising, pin a count or set `CUDA_VISIBLE_DEVICES`.
- The mesh runs one global program: BatchNorm statistics are over the global batch, and a
  `Dropout` mask is one global mask split across devices. Every `ReactantRNG` is placed as
  `"PHILOX"` at any device count, so a mesh run draws the same masks as a single-device run.

### The pin and its precedence

`setup_devices!(n_devs = k)` (or `nitro_setup(n_devs = k)`) pins the count for the whole
process. Resolved order, highest wins:

1. an explicit `n_devs` keyword on `Nitro` / `train!` / `nitro_train`, for one run
2. the session pin from `setup_devices!` / `nitro_setup`
3. the experiment's declared `n_devs` field
4. `length(Reactant.devices())`, every visible device

So a pinned session overrides what an experiment declares (the session operator's explicit
choice beats the model author's default), and a per-run keyword overrides the pin. A batch that
does not divide evenly across the mesh is a setup error naming both numbers.

## Restricting GPUs: `CUDA_VISIBLE_DEVICES`

To run on a subset of the GPUs on a host, set `CUDA_VISIBLE_DEVICES` **before starting the
process** (in the shell, the job script, or the session launcher); visibility is fixed at the
first XLA client access and cannot be changed mid-process. `n_devs` can then only select within
what is visible, and asking for more than is visible is an error that names the variable:

```
ReactantNitro: `n_devs = 4` but Reactant sees 2 device(s).
`n_devs` counts LOCAL, VISIBLE devices and the default is all of them, so this is either a
hand-set value that is too large or a `CUDA_VISIBLE_DEVICES` narrower than you meant.
```

The same rule applies at the Reactant level: `Reactant.devices()` is what the process can see,
and it is fixed once the client exists.

## Reading the current state

`setup_devices!()` / `nitro_setup()` with no arguments change nothing and report: the backend
in use (`Reactant.XLA.platform_name(Reactant.XLA.default_backend())`), how many devices are
visible, and the `n_devs` the next run will use, plus whether it is pinned or the default.

For the underlying library's full platform matrix (driver versions, detection, disabling GPU
support), the Reactant documentation's configuration page is the reference; the framework does
not restate it.

Versions

The database has no other skills named reactantnitro-accelerators.

Database snapshot: 13.11.2026 · package version 9265883f907b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95reactantnitro-kaimon
    Drive ReactantNitro runs from a Kaimon-hosted session: the `nitro_*` GateTools the KaimonGate extension registers (train, validate, evaluate, predict, export, runs, status, stop), when the tools appear, why every tool returns immediately and the run runs in the background, how…
  • 100reactantnitro-device-boundary
    Debug and prevent CPU/GPU divergence in ReactantNitro: why a fully green CPU test suite can pass while code has never once worked on a device, what a model author must and must not do at the boundary, what scalar indexing does differently on each backend, how to read a residency…
  • 95new-notebook
    Scaffold a new notebook in this repo - creates the py:percent source in src/, registers it in notebooks.json with an accelerator, and builds it. Use when adding a notebook to the JAX-on-TPU series.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.