Struct ParamDocument 

pub struct ParamDocument {

    pub general: GeneralParams,
    pub electronic: ElectronicParams,
    pub basis_set: BasisSetParams,
    pub exchange_correlation: ExchangeCorrelationParams,
    pub electronic_minimisation: ElectronicMinimisationParams,
    pub geometry_optimization: GeometryOptimizationParams,
    pub phonon: PhononParams,
    pub band_structure: BandStructureParams,
    pub molecular_dynamics: MolecularDynamicsParams,
    pub electric_field: ElectricFieldParams,
    pub pseudopotential: PseudopotentialParams,
    pub density_mixing: DensityMixingParams,
    pub population_analysis: PopulationAnalysisParams,
    pub optics: OpticsParams,
    pub nmr: NmrParams,
    pub solvation: SolvationParams,
    pub electronic_excitations: ElectronicExcitationsParams,
    pub transition_state: TransitionStateParams,
}

Complete representation of a CASTEP .param file.

This is the primary type for working with CASTEP parameter files. It organizes the 100+ CASTEP parameters into 18 logical groups, making it easier to discover related parameters and maintain the codebase.

Organization

Each field represents a group of related parameters. All groups default to empty (all parameters None), allowing you to specify only the parameters you need.

Validation

The document automatically validates inter-group constraints during parsing:

• Band count parameters (NBANDS, NEXTRA_BANDS, PERC_EXTRA_BANDS) are mutually exclusive
• Band structure parameters (BS_NBANDS, BS_NEXTRA_BANDS, BS_PERC_EXTRA_BANDS) are mutually exclusive
• Optics parameters (OPTICS_NBANDS, OPTICS_NEXTRA_BANDS, OPTICS_PERC_EXTRA_BANDS) are mutually exclusive

Each parameter group also validates its own internal constraints.

Construction

Use the builder pattern (via bon):

use castep_cell_io::ParamDocument;

let doc = ParamDocument::builder()
    .general(Default::default())
    .electronic(Default::default())
    .basis_set(Default::default())
    .exchange_correlation(Default::default())
    .electronic_minimisation(Default::default())
    .geometry_optimization(Default::default())
    .phonon(Default::default())
    .band_structure(Default::default())
    .molecular_dynamics(Default::default())
    .electric_field(Default::default())
    .pseudopotential(Default::default())
    .density_mixing(Default::default())
    .population_analysis(Default::default())
    .optics(Default::default())
    .nmr(Default::default())
    .solvation(Default::default())
    .electronic_excitations(Default::default())
    .transition_state(Default::default())
    .build();

Or use Default for an empty document:

use castep_cell_io::ParamDocument;

let doc = ParamDocument::default();
assert!(doc.general.task.is_none());

Parsing and Serialization

Implements FromCellFile for parsing and ToCellFile for serialization. Parsing automatically applies validation.

See the module-level documentation for examples.

Fields

general: GeneralParams

General calculation parameters.

Controls task type, output verbosity, continuation, and runtime limits. See GeneralParams for available parameters.

electronic: ElectronicParams

Electronic structure parameters.

Controls charge, spin, band counts, and electronic smearing. See ElectronicParams for available parameters.

basis_set: BasisSetParams

Basis set parameters.

Controls plane-wave cutoff energy and finite basis corrections. See BasisSetParams for available parameters.

exchange_correlation: ExchangeCorrelationParams

Exchange-correlation functional parameters.

Controls XC functional choice, spin polarization, and DFT+U. See ExchangeCorrelationParams for available parameters.

electronic_minimisation: ElectronicMinimisationParams

Electronic minimization (SCF) parameters.

Controls SCF convergence criteria and mixing schemes. See ElectronicMinimisationParams for available parameters.

geometry_optimization: GeometryOptimizationParams

Geometry optimization parameters.

Controls optimization method and convergence criteria. See GeometryOptimizationParams for available parameters.

phonon: PhononParams

Phonon calculation parameters.

Controls phonon calculation settings and convergence. See PhononParams for available parameters.

band_structure: BandStructureParams

Band structure calculation parameters.

Controls band structure calculation settings. See BandStructureParams for available parameters.

molecular_dynamics: MolecularDynamicsParams

Molecular dynamics parameters.

Controls MD ensemble, timestep, temperature, and thermostat. See MolecularDynamicsParams for available parameters.

electric_field: ElectricFieldParams

Electric field parameters.

Controls finite electric field calculations. See ElectricFieldParams for available parameters.

pseudopotential: PseudopotentialParams

Pseudopotential parameters.

Controls pseudopotential generation and testing. See PseudopotentialParams for available parameters.

density_mixing: DensityMixingParams

Density mixing parameters.

Controls charge density mixing during SCF. See DensityMixingParams for available parameters.

population_analysis: PopulationAnalysisParams

Population analysis parameters.

Controls Mulliken and Hirshfeld population analysis. See PopulationAnalysisParams for available parameters.

optics: OpticsParams

Optical properties parameters.

Controls optical property calculations. See OpticsParams for available parameters.

nmr: NmrParams

NMR parameters.

Controls NMR chemical shift calculations. See NmrParams for available parameters.

solvation: SolvationParams

Solvation parameters.

Controls implicit solvent models. See SolvationParams for available parameters.

electronic_excitations: ElectronicExcitationsParams

Electronic excitations parameters.

Controls excited state calculations. See ElectronicExcitationsParams for available parameters.

transition_state: TransitionStateParams

Transition state search parameters.

Controls transition state search methods. See TransitionStateParams for available parameters.

Implementations

impl ParamDocument

pub fn builder() -> ParamDocumentBuilder

Create an instance of ParamDocument using the builder syntax

Trait Implementations

impl Clone for ParamDocument

fn clone(&self) -> ParamDocument

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ParamDocument

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

Formats the value using the given formatter.

impl Default for ParamDocument

fn default() -> ParamDocument

Returns the “default value” for a type.

impl FromCellFile for ParamDocument

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

Parse a ParamDocument from a slice of parsed Cell tokens.

This method is called by [castep_cell_fmt::parse] after tokenizing the input text. It delegates parsing to each parameter group, then validates the complete document.

Parsing Strategy

Each parameter group independently scans the token stream for its keywords. This allows parameters to appear in any order in the file. Unknown keywords are silently ignored (CASTEP’s behavior).

Validation

After parsing all groups, validation is automatically called to check inter-group and intra-group constraints.

Errors

Returns Error if:

• Any parameter value is malformed
• Validation constraints are violated
• Required parameter combinations are missing

Example

use castep_cell_io::ParamDocument;

let input = r#"
TASK : GeometryOptimization
XC_FUNCTIONAL : PBE
CUT_OFF_ENERGY : 500 eV
"#;

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

impl ToCellFile for ParamDocument

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.

Group Order

Parameters are emitted in a standard order matching the field declaration order:

1. General parameters
2. Electronic structure
3. Basis set
4. Exchange-correlation
5. Electronic minimization
6. Geometry optimization
7. Phonon calculations
8. Band structure
9. Molecular dynamics
10. Electric field
11. Pseudopotentials
12. Density mixing
13. Population analysis
14. Optics
15. NMR
16. Solvation
17. Electronic excitations
18. Transition state search

Parameters that are None are omitted from the output.

Example

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

let doc = ParamDocument::default();
let cells = doc.to_cell_file();
let output = to_string_many_spaced(&cells);