suggested documentation update:

[tpchuckles]

proposing to change the main installation instructions from:

git clone https://github.com/h-walk/PySlice.git
cd PySlice

to:

git clone --filter=blob:none --no-checkout https://github.com/h-walk/PySlice
cd PySlice/
git sparse-checkout set --no-cone '/*' '!/tests/*'
git checkout main

excluding the tests directory gives you 4.7 MB to download, instead of 400 MB.

I would make this change myself but someone probably ought to check pip -e and subsequent still works and i can't at the moment.

and really, eventually, we should get on pypi so people can just "pip install ...." off the bat and have it work. lately i've been cloning, deleting tests folder, zipping, and emailing, if i want to share specific versions of the code with people. that's a bit silly though.

[tpchuckles]

User feedback at M&M mostly boiled down to "needs better documentation". well. having contributed in large part to the code, i personally know how it works, so what's the problem??

below is what codex thinks are some ambiguities based on the readme alone, and a number of these reflect questions i have received in private from users. I will be treating this as a sort of "to do list" for documentation changes moving forwards. the second block are additional questions based on the scripts inside of "tests"

 Questions raised by the README alone:

  - What is the simplest verified installation path: pip, uv, CPU-only, or GPU?
  - Is Python 3.12 required only for ORB, while the rest of PySlice supports Python 3.10–3.13?
  - Does uv sync install OVITO, or is the separate OVITO command still required?
  - How can users confirm which backend—CUDA, MPS, or CPU—was selected?
  - What trajectory properties are mandatory: periodic cell, velocities, fixed atom count/order, uniform timestep, and minimum frame count?
  - Is Trajectory.timestep the MD integration timestep or the saved-frame interval? The examples suggest the latter, but this matters for TACAW frequencies.
  - What units and coordinate conventions apply to positions, cells, reciprocal-space axes, probe positions, and returned intensities?
  - How should a structure be oriented, padded, or repeated before multislice simulation?
  - What defaults does MultisliceCalculator.setup() use when slice_thickness or probe positions are omitted?
  - The README shows probe_xs/probe_ys, while the class reference shows probe_positions. Which interface is preferred?
  - How should sampling, slice thickness, voltage, aperture, and detector angles be chosen and checked for convergence?
  - What determines TACAW frequency resolution and valid frequency range?
  - How are kx_path and ky_path constructed for a crystallographic dispersion path?
  - Are mean-wave subtraction, windowing, normalization, or other preprocessing performed automatically by TACAWData?
  - How are Trajectory, WFData, spectra, diffraction patterns, and images saved and restored?
  - What runtime and GPU-memory requirements should users expect for the supplied examples?
  - Are random timestep selections reproducible, and how is a random seed specified?
  - Which included input datasets, if any, allow the examples to run immediately?
  - What output should each example produce so users can recognize a successful calculation?
  - Is there a recommended troubleshooting path for missing OVITO, unavailable CUDA, out-of-memory errors, or unsupported trajectory data?

  Minimum suggested example set: four examples

  1. Installation and smoke test

     Run a very small silicon calculation on CPU, report the selected backend and package versions, plot one diffraction pattern, and state the expected output shape. This establishes that installation works
     without optional MD dependencies.

  2. Load and validate an existing trajectory

     Load one repository-supplied CIF and one tiny trajectory, print frame count, atom count, cell, timestep, and atom mapping, then demonstrate a spatial/time subset. This clarifies accepted data and units
     before an expensive calculation.

  3. Existing trajectory → TACAW result

     Use a small supplied trajectory to calculate spectral diffraction and one short dispersion path. Explain saved-frame spacing, attainable frequencies, construction of the reciprocal-space path, expected
     output, and how to save it.

  4. Minimal STEM workflow

     Perform a tiny probe scan and produce BF, ADF/HAADF, and a diffraction/4D-STEM output from the same result. This should demonstrate the preferred probe-position API, detector-angle units, output
     dimensions, and saving/reloading.

  ORB-based MD can remain an optional fifth example because it adds model downloads, Python-version constraints, substantial compute, and GPU-memory considerations. The first four would let a new user verify
  the core package before attempting that heavier workflow.

## Additional questions

  - Which files under tests/ are supported user examples, true automated tests, research demonstrations, benchmarks, or stress tests?
  - From which working directory should examples run? Many assume relative inputs/ and outputs/ directories.
  - Which APIs are considered public? Several scripts directly use Probe, Potential, Propagate, and backend internals, while the README emphasizes calculators.
  - How does a user explicitly select NumPy, Torch CPU, or Torch GPU? Tests use both device="cpu" and PYSLICE_BACKEND=numpy.
  - What are the defaults and tradeoffs among loop_probes, use_memmap, min_dk, max_kx/max_ky, kth, cache_wavefunctions, and cache_potentials?
  - Where is cached data written, how large can it become, when is it reused, and how is a calculation forcibly rerun?
  - What exactly does return_layers mean? Does the default retain only the final exit wave, and does None intentionally return no wavefunctions?
  - Why does MultisliceCalculator.run() sometimes return WFData and sometimes (WFData, HAADFData) when on-the-fly ADF is enabled?
  - What formats are accepted for probe positions, how are irregular position lists handled, and how is a regular scan reshaped into an image?
  - What are the default ADF collection angles? Are ADF=True, ADF=(5, 40), and HAADFData.calculateADF() equivalent workflows?
  - Are the detector limits given in mrad while max_kx, max_ky, and min_dk are reciprocal ångströms?
  - Does slicing a trajectory translate the retained atoms and update its simulation cell? The regression tests explicitly check this.
  - Is simulation restricted to propagation along the z axis? A regression test indicates other slice_axis values are rejected.
  - When is atom_mapping mandatory? Tests indicate OVITO numeric type IDs must not silently be treated as atomic numbers.
  - Is SEA export an officially supported optional feature, and how should its dependency be installed? One legacy script attempts to obtain a private repository using credentials from a local file; that
    script should not be presented as a user example.

  - Which scripts are safe to run directly? Some delete caches or output files, and the shell runners contain site-specific Slurm accounts, modules, and environment paths.

  ## Additional examples

  I would add only two distinct examples, while expanding two of the four previously proposed examples.

  1. Memory-safe STEM/ADF

     This is the one genuinely necessary additional example. PySlice-github/tests/04_adf_calculator.py demonstrates an important production workflow:
      - ADF=(inner, outer)
      - return_layers=None
      - cache_wavefunctions=False
      - loop_probes=<batch size>
      - unpacking wf_data, haadf = calculator.run()

     Without this, a beginner may unnecessarily retain an enormous 4D-STEM wavefunction stack and run out of memory.

  2. Caching, restart, and output management

     A small calculation should demonstrate:
      - where output/cache files go;
      - cache_wavefunctions versus cache_potentials;
      - use_memmap;
      - return_layers;
      - rerunning versus reusing cached results;
      - safely cleaning only that example’s output directory;
      - saving and reloading final results using the officially supported format.

     This should be distilled from the caching tests, not copied from them.

  The existing installation smoke test should also be expanded to show explicit backend selection and array conversion. The existing loader example should show timestep slicing, reproducible random-frame
  selection, spatial cropping, tiling, and validation of atom mappings.

  ## Examples that should remain advanced

  These are useful demonstrations but not required for initial onboarding:

  - manual potential/propagation and inverse-object reconstruction;
  - defocus, aberrations, partial coherence, lens series, and probe tilts;
  - LACBED, Midgley diffraction, SED, Kikuchi patterns, and PRISM;
  - frozen-phonon CBED and count/noise simulations;
  - benchmark, “enormous,” and memory stress scripts;
  - SEA integration regression tests;
  - backend unit tests and the large review-regression suite.

  The most important documentation change is therefore not a large increase in beginner examples. It is to stop describing the whole tests/ directory as “detailed examples” without classifying the scripts. A
  small examples/ directory containing approximately six curated, safe workflows would be much clearer than directing new users into the current mixed test suite.