Struct CellDocument 

pub struct CellDocument {
    pub lattice: Lattice,
    pub positions: Positions,
    pub kpoints: KpointsParams,
    pub spectral: SpectralParams,
    pub optics_magres: OpticsMagresParams,
    pub symmetry: SymmetryParams,
    pub constraints: ConstraintsParams,
    pub external_fields: ExternalFieldParams,
    pub species: SpeciesParams,
    pub phonon: PhononParams,
    pub phonon_fine: PhononFineParams,
    pub dynamics: DynamicsParams,
}

Complete representation of a CASTEP .cell file.

This is the primary type for working with CASTEP cell files. It contains all structural information, calculation parameters, and optional blocks that can appear in a cell file.

Required Fields

• lattice: Periodic boundary conditions
• positions: Atomic coordinates

All other fields are optional and correspond to specific CASTEP features.

Construction

Use the builder pattern (via bon) for ergonomic construction:

use castep_cell_io::CellDocument;

let doc = CellDocument::builder()
    .lattice(todo!())  // LatticeCart - automatically wrapped in Lattice::Cart
    .positions(todo!())  // PositionsFrac/PositionsAbs - automatically wrapped
    .build();

Parsing and Serialization

Implements FromCellFile for parsing and ToCellFile for serialization:

use castep_cell_io::CellDocument;
use castep_cell_fmt::{ToCellFile, format::to_string_many_spaced};

// Parse from string
let input = std::fs::read_to_string("input.cell")?;
let doc = castep_cell_fmt::parse::<CellDocument>(&input)?;

// Serialize back to CASTEP format
let cells = doc.to_cell_file();
let output = to_string_many_spaced(&cells);

Optional Blocks (via Cell Document Groups)

The document organizes optional blocks into logical sub-groups, mirroring the ParamDocument pattern:

• K-points: kpoints — SCF k-point sampling
• Spectral: spectral — BS_ and SPECTRAL_ k-point paths
• Optics/Magres: optics_magres — optics and magnetic resonance k-points
• Symmetry: symmetry — symmetry operations and generation
• Constraints: constraints — ionic and cell constraints
• External fields: external_fields — electric field and pressure
• Species: species — masses, pseudopotentials, Hubbard U
• Phonon: phonon — coarse phonon k-point settings
• Phonon fine: phonon_fine — fine phonon k-point settings
• Dynamics: dynamics — ionic velocities for MD

Fields

lattice: Lattice

Lattice vectors defining the simulation cell.

Required field. Defines the periodic boundary conditions.

positions: Positions

Atomic positions within the cell.

Required field. Can be fractional or absolute coordinates.

kpoints: KpointsParams

SCF k-point sampling parameters.

Contains KPOINTS_LIST, KPOINTS_MP_GRID, KPOINTS_MP_SPACING, and KPOINTS_MP_OFFSET.

spectral: SpectralParams

Spectral/BS k-point parameters.

Contains BS_ and SPECTRAL_ prefixed k-point types for band structure calculations.

optics_magres: OpticsMagresParams

Optics and magnetic resonance k-point lists.

Contains OPTICS_KPOINTS_LIST and MAGRES_KPOINTS_LIST.

symmetry: SymmetryParams

Symmetry parameters.

Contains SYMMETRY_OPS, SYMMETRY_GENERATE, and SYMMETRY_TOL.

constraints: ConstraintsParams

Movement constraints for ions and cell.

Contains FIX_COM, IONIC_CONSTRAINTS, NONLINEAR_CONSTRAINTS, FIX_ALL_IONS, FIX_ALL_CELL, CELL_CONSTRAINTS, and FIX_VOL.

external_fields: ExternalFieldParams

External field parameters.

Contains EXTERNAL_EFIELD and EXTERNAL_PRESSURE.

species: SpeciesParams

Species properties.

Contains SPECIES_MASS, SPECIES_POT, SPECIES_LCAO_STATES, SPECIES_Q, HUBBARD_U, and SEDC_CUSTOM_PARAMS.

phonon: PhononParams

Phonon (coarse) k-point parameters.

Contains phonon k-point lists, paths, MP grids, and related settings.

phonon_fine: PhononFineParams

Phonon fine k-point parameters.

Contains fine phonon k-point paths, lists, and MP grids.

dynamics: DynamicsParams

Molecular dynamics dynamics parameters.

Contains IONIC_VELOCITIES for MD restart.

Implementations

impl CellDocument

pub fn builder() -> CellDocumentBuilder

Create an instance of CellDocument using the builder syntax

Trait Implementations

impl Clone for CellDocument

fn clone(&self) -> CellDocument

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CellDocument

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromCellFile for CellDocument

fn from_cell_file(cells: &[Cell<'_>]) -> CResult<Self>

Parse a CellDocument from a slice of parsed Cell tokens.

This method is called by [castep_cell_fmt::parse] after tokenizing the input text. It extracts all recognized blocks and keywords from the token stream.

Required Blocks

• %BLOCK LATTICE_CART — must be present
• Either %BLOCK POSITIONS_FRAC or %BLOCK POSITIONS_ABS — must have exactly one

Errors

Returns Error if:

• Required blocks are missing
• Block content is malformed
• Multiple position blocks are present
• Any block fails to parse according to its schema

Example

use castep_cell_io::CellDocument;

let input = r#"
%BLOCK LATTICE_CART
  10.0  0.0  0.0
   0.0 10.0  0.0
   0.0  0.0 10.0
%ENDBLOCK LATTICE_CART

%BLOCK POSITIONS_FRAC
Si  0.0  0.0  0.0
Si  0.25 0.25 0.25
%ENDBLOCK POSITIONS_FRAC
"#;

let doc = castep_cell_fmt::parse::<CellDocument>(input)?;

impl ToCellFile for CellDocument

fn to_cell_file(&self) -> Vec<Cell<'_>>

Serialize this document to a vector of Cell tokens.

Converts the structured document back to the token representation used by castep_cell_fmt. The tokens can then be formatted to text with castep_cell_fmt::format.

Block Order

Blocks are emitted in a standard order:

1. Lattice and positions (required)
2. K-point sampling blocks
3. Constraints and flags
4. External fields
5. Species properties
6. Phonon calculation blocks
7. Dynamics (ionic velocities)

Optional blocks that are None are omitted from the output.

Example

use castep_cell_io::CellDocument;
use castep_cell_fmt::{ToCellFile, format::to_string_many_spaced};

// Assuming you have a CellDocument instance
let doc = todo!(); // Your CellDocument instance
let cells = doc.to_cell_file();
let output = to_string_many_spaced(&cells);