<!-- https://docs.dseams.info/user/howto/linkcell-carried.md -->

# Linkcell neighbours and carried updates {#linkcell-neighbours-and-carried-updates}

Build the cutoff neighbour list, then keep rings when only part of
the next frame moved. The scaling argument is
[Linkcell strong scaling](../../explanation/linkcell-scaling.md).
The list itself is
[Cutoff neighbour lists](neighbour-lists.md).

## The cutoff list {#the-cutoff-list}

`neighListO` builds one shared CSR with `nneigh::orthoFullCsr` when
the OpenMP team has more than one thread and the caller is outside a
team. The box is orthorhombic (length 3) or a restricted triclinic
dump (length at least 6). On one thread, and when that CSR call is
not taken, a linked linkcell fills the rows with
`linkcell::pairs_within`. vesin is the fallback when linkcell is
absent or the call fails.
`nneigh::preferSerialCutoff(true)` forces the one-thread builder.

Published CHILL+ calls `orthoFullCsr` on those boxes
(`chill::chillPlusPublishedCutoff`). Cutoff q4 and q6 do the same
(`chill::steinhardtQlCutoff`). The ring census reads the atom-ID rows.
The pair set does not depend on the thread count.

The half list keeps each pair on the lower index. The test that locks
this is the Catch2 case `half cutoff list is the lower index of the full list`:

```cpp
// excerpt: tests/test_neighbours.cpp
  REQUIRE(nneigh::orthoFullCsr(cloud, nullptr, 3.5, fullOff, fullCols, false));
  REQUIRE(nneigh::orthoFullCsr(cloud, nullptr, 3.5, halfOff, halfCols, true));
```

A skin reuses the wide list while every atom stays inside the Verlet
shell. Bonds are the pairs still inside the cutoff.

## Carried rings {#carried-rings}

A frame range on one worker visits frames in order through one
`FrameCarry`. `RingUpdater` redoes only the sources near a changed
bond. The result equals `ringNetwork` on that frame.

Carry is off for a single frame (`--last` omitted or equal to
`--frame`) and whenever `--rebuild` is set. On a LAMMPS dump,
`--jobs` above 1 also turns it off, because the frames are split
across workers. A non-dump range keeps one carry when `--jobs` is
above 1. More than one MPI rank on a dump leaves carry off as well.

The hop-ball test moves one atom across a periodic face and requires
the carried rings to match a full search, with fewer sources recomputed
than the atom count:

```cpp
// excerpt: tests/test_ring_hop.cpp
  const auto &carried = updater.update(moved);
  const auto full = primitive::ringNetwork(moved, 6);
  REQUIRE(carried == full);
```

## What was timed {#what-was-timed}

[Benchmarks](benchmarks.md) records both windows at 4096 molecules,
200 transitions, and eight threads. Every transition stayed inside the
hop ball, and the carried rings matched a full search. Speedup is
rebuild divided by carry.

The mW window (10 fs step) at 0.1, 1, and 10 ps is on that page. The
strict seeded graph there is the row `seeded-strict`.

The TIP4P/2005 ice/water slab (2 fs step) is finer: 0.01, 0.1, and
1 ps. An oxygen moves farther in one picosecond than an mW site. The
`seeded-strict` speedups are 8.31, 3.28, and 2.59.

```python
# excerpt: tests/cli_surface.py
        ["--frame", "1", "--last", "2", "--jobs", "1", "--rebuild", "read", cubic],
```

That argv is the walk with carry forced off. To keep the updater, drop
`--rebuild`, pass a `--last` past `--frame`, and leave `--jobs` at 1
on a dump.
