Struct vasp_poscar::builder::Builder

pub struct Builder(_);

Allows construction of Poscar/RawPoscar via the builder pattern.

Overview

Builder is the most straightforward way to construct a Poscar or RawPoscar object from data in memory.

use vasp_poscar::{Builder, ScaleLine, Coords};

let poscar =
    Builder::new()
    .comment("Cubic BN")
    .scale(ScaleLine::Factor(3.57))
    .lattice_vectors(&[
        [0.0, 0.5, 0.5],
        [0.5, 0.0, 0.5],
        [0.5, 0.5, 0.0],
    ])
    .group_symbols(vec!["B", "N"])
    .group_counts(vec![1, 1])
    .positions(Coords::Frac(vec![
        [0.00, 0.00, 0.00],
        [0.25, 0.25, 0.25],
    ]))
    .build_raw(); // or .build()?;

Most fields have reasonable defaults, and even those fields which you are required to set provide helpers for selecting "unreasonable" defaults.

use vasp_poscar::{Builder, Zeroed, Coords};

let poscar =
    Builder::new()
    .dummy_lattice_vectors()
    .positions(Coords::Frac(Zeroed))
    .group_counts(vec![3])
    .build_raw();

Working with this API requires you to be familiar with the POSCAR format. Its setters map almost one-to-one with the sections of a POSCAR file (though there are a few additional conveniences).

Defaults

All optional fields of a Poscar are disabled by default. Others may have default values or behavior that is detailed in the documentation of the appropriate setter. Some fields, like positions and lattice_vectors, have no default, and failure to set them will result in a panic at runtime in the build method.

Panics

Contract violations

Generally speaking, invalid data provided to the Builder will at worst produce a ValidationError, and even then, it will only do so when building a Poscar. (building a RawPoscar performs no validation)

However, egregious misuse of the Builder API may make it impossible to construct even a RawPoscar. In this case, the build methods will panic. In particular, the rules are:

All required fields must be set:

• positions
• lattice_vectors

If positions is set to Zeroed, then group_counts also becomes required.

Poisoning

Calling build_raw or build "consumes" the Builder in a manner which causes all future method calls to panic at runtime. If you wish to reuse a Builder, you must clone it before calling one of these methods.

Methods

impl Builder

Initialization

pub fn new() -> Builder

Alias for Default::default.

impl Builder

Setting metadata

pub fn comment<S: Into<String>>(&mut self, s: S) -> &mut Self

Set the comment line.

Defaults to "POSCAR File", which you will no doubt agree is spectacularly exciting.

impl Builder

Setting the lattice

pub fn scale(&mut self, s: ScaleLine) -> &mut Self

Set the scale line.

Defaults to ScaleLine::Factor(1.0).

pub fn lattice_vectors(&mut self, vectors: &[[f64; 3]; 3]) -> &mut Self

Set the unscaled lattice vectors, as they would be written in the file.

This field is required. The build_raw and build methods will panic unless this method or dummy_lattice_vectors has been called.

pub fn dummy_lattice_vectors(&mut self) -> &mut Self

Set an identity matrix as the lattice.

You may think of this as an "explicit default". This may be useful in applications where the lattice given to the builder will ultimately be discarded.

impl Builder

Setting coordinate data

pub fn positions<V>(&mut self, vs: V) -> &mut Self where
    V: PositionsArgument, 

Set unscaled positions as they would be written in the Poscar.

This field is required. The build_raw and build methods will panic unless this method has been called.

The argument should be an iterable over [f64; 3], &[f64; 3], or (f64, f64, f64), wrapped in the Coords enum. Examples of valid arguments:

• Coords<Vec<[f64; 3]>>
• Coords<&[f64; 3]>
• Coords::Cart(xs.iter().zip(&ys).zip(&zs).map(|((&x, &y), &z)| (x, y, z))), where xs and family are Vec<f64>.

You may also use Coords::Cart(Zeroed) or Coords::Frac(Zeroed) to set dummy values equal in length to the total atom count. See Zeroed.

Panics

If Zeroed is used, then you must also supply group_counts, or else build_raw and build will panic.

impl Builder

Setting velocities

pub fn velocities<V>(&mut self, vs: V) -> &mut Self where
    V: VelocitiesArgument, 

Set velocities as they would be written in the file.

The argument should be an iterable over [f64; 3], &[f64; 3], or (f64, f64, f64), wrapped in the Coords enum. Examples of valid arguments:

• Coords<Vec<[f64; 3]>>
• Coords<&[f64; 3]>
• Coords::Cart(xs.iter().zip(&ys).zip(&zs).map(|((&x, &y), &z)| (x, y, z))), where xs and family are Vec<f64>.

You may also use Coords::Cart(Zeroed) or Coords::Frac(Zeroed) to set dummy values equal in length to the total atom count. See Zeroed.

pub fn no_velocities(&mut self) -> &mut Self

Undoes the effect of velocities, removing that section from the file.

impl Builder

Setting atom types

pub fn group_counts<Cs>(&mut self, cs: Cs) -> &mut Self where
    Cs: IntoIterator<Item = usize>, 

Set explicit counts for each atom type.

pub fn auto_group_counts(&mut self) -> &mut Self

Undoes the effect of group_counts, restoring the default behavior.

By default, it is assumed that all atoms are the same type, resulting in a single atom type of count positions.len().

pub fn group_symbols<Cs>(&mut self, syms: Cs) -> &mut Self where
    Cs: IntoIterator,
    Cs::Item: Into<String>, 

Set symbols for each atom type.

pub fn no_group_symbols(&mut self) -> &mut Self

Undoes the effect of group_symbols, removing the symbols line from the file.

pub fn site_symbols<Cs>(&mut self, syms: Cs) -> &mut Self where
    Cs: IntoIterator,
    Cs::Item: Into<String>, 

Set symbols for each site in the unit cell.

This is a convenience wrapper that calls both group_symbols and group_counts.

impl Builder

Enabling selective dynamics

pub fn dynamics<V>(&mut self, vs: V) -> &mut Self where
    V: DynamicsArgument, 

Set selective dynamics flags.

The argument should be an iterable over [bool; 3], &[bool; 3], or (bool, bool, bool). Examples of valid arguments:

• Vec<[bool; 3]>
• &[bool; 3]
• xs.iter().zip(&ys).zip(&zs).map(|((&x, &y), &z)| (x, y, z)), where xs and family are Vec<bool>.

pub fn no_dynamics(&mut self) -> &mut Self

Undoes the effect of dynamics, removing that section from the file.

impl Builder

Building

pub fn build(&mut self) -> Result<Poscar, ValidationError>

Creates a Poscar.

Errors: See ValidationError

Panics: See toplevel documentation

pub fn build_raw(&mut self) -> RawPoscar

Creates a RawPoscar.

Panics: See toplevel documentation

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Builder

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

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Builder

Returns the "default value" for a type.