# lammps-troubleshooting

> This skill should be used when users ask about troubleshooting in lammps; it prioritizes documentation references and then source inspection only for unresolved details.

- Author: Tao E. Li
- Repository: TEL-Research-Group/lammps
- Version: 20260207223556
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/TEL-Research-Group/lammps
- Web: https://mule.run/skillshub/@@TEL-Research-Group/lammps~lammps-troubleshooting:20260207223556

---

---
name: lammps-troubleshooting
description: This skill should be used when users ask about troubleshooting in lammps; it prioritizes documentation references and then source inspection only for unresolved details.
---

# lammps: Troubleshooting

## High-Signal Playbook
### Route the request
- Use `lammps-inputs-and-modeling` first if the issue is clearly a setup inconsistency.
- Use `lammps-parallel-hpc` if failures appear only under large MPI/GPU configurations.
- Use `lammps-simulation-workflows` when restart/equilibration sequencing is the root cause.

### Triage questions
- Did failure occur during input parsing, run initialization, or mid-run?
- Is the issue deterministic with same seed/ranks?
- Does it reproduce in serial or only in parallel?
- Are there lost atoms, missing bonded atoms, NaN/Inf thermo values, or segfaults?
- Did warnings start before the fatal error?

### Canonical workflow
- Create a minimal reproducer that triggers quickly (`doc/src/Errors_details.rst`).
- Run serial and small-MPI variants to isolate decomposition effects (`doc/src/Errors_details.rst`).
- Increase thermo/dump frequency near failure and visualize trajectories (`doc/src/Errors_details.rst`).
- Use conservative neighbor settings while debugging (`doc/src/neigh_modify.rst`, `doc/src/Errors_details.rst`).
- Check units/potential consistency and close contacts (`doc/src/units.rst`, `doc/src/pair_coeff.rst`, `doc/src/Errors_details.rst`).
- If needed, stabilize startup with minimization or temporary `fix nve/limit` / `fix dt/reset` (`doc/src/Errors_details.rst`).

### Minimal working examples
- Debug-mode output settings (`doc/src/Run_output.rst`, `doc/src/dump_modify.rst`):
```LAMMPS
thermo 1
thermo_modify lost warn warn default
neighbor 2.0 bin
neigh_modify every 1 delay 0 check yes
dump dbg all custom 10 dump.debug id type x y z vx vy vz fx fy fz
dump_modify dbg sort id pbc yes
run 1000
```
- Quick post-velocity stabilization pattern (`doc/src/velocity.rst`):
```LAMMPS
velocity all create 300.0 12345
run 0
velocity all scale 300.0
```

### Pitfalls
- Silencing lost-atom errors (`thermo_modify lost ignore`) before root-cause analysis (`doc/src/Errors_details.rst`).
- Excessively delayed neighbor rebuilds causing missing interactions (`doc/src/neigh_modify.rst`).
- Communication cutoff too short for bonded topology (`doc/src/Errors_warnings.rst`, `doc/src/Errors_details.rst`).
- Misreading normal trajectory divergence across processor counts as a code bug (`doc/src/Errors_common.rst`).
- Treating all warnings as harmless; many are early indicators (`doc/src/Errors_warnings.rst`).

### Validation checklist
- Reproducer succeeds with no lost/missing atoms and no NaN/Inf fields.
- Warning count is understood and acceptable for the production regime.
- Key observables match expected statistical behavior across rank counts.
- Final production settings remain stable after removing temporary debug overrides.

## Scope
- Handle questions about known issues, diagnostics, and debugging patterns.
- Keep responses abstract and architectural for large codebases; avoid exhaustive per-function documentation unless requested.

## Primary documentation references
- `doc/src/Errors.rst`
- `doc/src/Errors_common.rst`
- `doc/src/Errors_details.rst`
- `doc/src/Errors_warnings.rst`
- `doc/src/Errors_messages.rst`
- `doc/src/Errors_bugs.rst`
- `doc/src/Run_output.rst`
- `doc/src/neigh_modify.rst`

## Workflow
- Start with the primary references above.
- If details are missing, inspect `references/doc_map.md` for additional topic documents (generated inventory plus curated anchors).
- Use tutorials/examples as executable usage patterns when available.
- Use tests as behavior or regression references when available.
- If ambiguity remains after docs, inspect `references/source_map.md` and start with the ranked source entry points.
- Cite exact documentation file paths in responses.

## Tutorials and examples
- `examples`

## Test references
- None discovered.

## Optional deeper inspection
- `fortran`
- `lib`
- `python`
- `src`

## Source entry points for unresolved issues
- `src/error.h`
- `src/error.cpp`
- `src/MACHDYN/compute_smd_hourglass_error.h`
- `src/MACHDYN/compute_smd_hourglass_error.cpp`
- `src/CG-SPICA/lj_spica_common.h`
- `src/ADIOS/adios_common.h`
- `lib/kokkos/simd/src/Kokkos_SIMD_Common_Math.hpp`
- `lib/kokkos/simd/src/Kokkos_SIMD_Common.hpp`
- Prefer targeted source search (for example: `rg -n "<symbol_or_keyword>" fortran lib python src`).