# Reading VASP POSCAR and CONTCAR files into a Structure

Getting a structure off disk is the first thing most workflows do, and VASP's
POSCAR/CONTCAR is the format a great many of them meet first. *httk-atomistic*
gives you two entry points:

`load_structure(path)`
: **The end-to-end convenience.** It calls `httk.core.load`, which picks a
  reader by file type — and transparently decompresses `.bz2` and `.gz`, so an
  archived `CONTCAR.bz2` needs no special handling — then dispatches on the
  payload's `"format"` tag to the matching structure builder. This is what you
  want in a script.

`structure_from_poscar(mapping)`
: **The bridge alone.** It takes the neutral, string-preserving mapping that
  `httk.io.read_poscar` produces (`{"format": "vasp-poscar", "cell": [...],
  "coords": [...], ...}`) and turns it into a `Structure`. Use it when the
  file has already been parsed, when the mapping came from somewhere other
  than a file, or when you want to edit the mapping before building.

Notably, `structure_from_poscar` **imports nothing from *httk-io***. It only
understands the shape of the mapping. That is what keeps parsing (*httk-io*) and
the domain model (*httk-atomistic*) decoupled: neither distribution depends on
the other, and the neutral mapping is the whole contract between them.
`load_structure` does need *httk-io* installed at run time, though — not to
import it, but because importing `httk.core` walks the `httk.handlers` namespace
package, and that is where *httk-io* registers the POSCAR reader for the
`POSCAR`/`CONTCAR` filenames.

**The values stay exact.** The file's numbers are read as *strings* and turned
into exact rationals, never into floats first, so a lattice row written as
`5.3982999999999999` is that exact decimal and a coordinate written as `1/3`
would be that exact third. Direct coordinates become reduced coordinates
verbatim. Cartesian coordinates are converted exactly as `cart * basis.inv()`,
and the VASP universal scaling factor cancels in that expression (it scales the
lattice vectors and the Cartesian positions alike), so the reduced coordinates
come out exact either way. The one place exactness is unavoidably lost is a
*negative* scale line, which encodes a target cell **volume**: the resulting
overall scale is a cube root, which leaves the squarefree-radical field, so it
is a deterministic rational approximation — the basis rows themselves stay
exact.

One incompatibility worth knowing: VASP-4 POSCAR files have no species line, so
the elements are simply not in the file. `structure_from_poscar` raises
`ValueError` rather than guessing.

```{literalinclude} ../../examples/load_from_poscar.py
:language: python
:lines: 47-
```