Struct vasp_poscar::Poscar

pub struct Poscar(_);

Represents a POSCAR file.

The key parts of the API are currently:

• Reading files through Poscar::from_reader.
• In-memory construction via Builder.
• Manipulation/inspection of the data via [raw] and RawPoscar. (this will be supplanted with cleaner solutions over time)
• Writing files, via std::fmt::Display.

Please follow the links above to learn about these APIs. The remaining item is documented below.

Writing files

Printing of POSCAR files is implemented as a std::fmt::Display impl on the Poscar type. This means that you can use it in all of the standard library macros like print!, format!, and write!.

By default, the crate prints to roundtrip precision, switching to exponential for values with large or small magnitudes. If you would prefer a more tabular output format, you may specify format flags, which will be used to control the formatting of all floats.

use vasp_poscar::Poscar;

let poscar = Poscar::from_reader("\
POSCAR File
   1.0
     1.0   0.0   0.0
     0.0   1.23456789012 -0.2
     0.0   0.0   1.0
  1
Direct
 0.1  -1.2e-30  0.0
".as_bytes())?;

// Default format: roundtrip
assert_eq!(format!("{}", poscar), "\
POSCAR File
  1.0
    1.0 0.0 0.0
    0.0 1.23456789012 -0.2
    0.0 0.0 1.0
   1
Direct
  0.1 -1.2e-30 0.0
");

// Custom formats
assert_eq!(format!("{:>9.6}", poscar), "\
POSCAR File
   1.000000
     1.000000  0.000000  0.000000
     0.000000  1.234568 -0.200000
     0.000000  0.000000  1.000000
   1
Direct
   0.100000 -0.000000  0.000000
");

Methods

impl Poscar

pub fn from_reader<R: BufRead>(f: R) -> Result<Self, Error>

Reads a POSCAR from an open file or a &[u8] buffer.

This takes any type of object that implements BufRead. For example, use a BufReader if you want to read from a file, or &[u8] if you want to read from a string.

A successful read will always read the entire object to EOF. This is simply the nature of the file format. If you need to extract a POSCAR embedded within a larger resource, you will likely need to use an adapter like Read::take.

pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Self, Error>

Reads a POSCAR from the filesystem.

impl Poscar

pub fn into_raw(self) -> RawPoscar

Convert into a form with public data members that you can freely match against and unpack.

When you are done modifying the object, you may call validate to turn it back into a Poscar. (or you can just keep all the data to yourself. We don't mind!)

Currently, this is the most versatile way of manipulating a Poscar object, though it may not be the most stable or convenient. Be prepared for breaking changes to affect code using this method. In the future, stabler alternatives for common operations may be provided on Poscar itself.

impl Poscar

Accessing simple properties

pub fn comment(&self) -> &str

pub fn group_symbols(&self) -> Option<impl VeclikeIterator<Item = &str> + '_>

Get the symbols for each atom type, if provided.

pub fn group_counts(&self) -> impl VeclikeIterator<Item = usize> + '_

Get the counts of each atom type.

pub fn num_sites(&self) -> usize

Get the number of sites in the unit cell.

pub fn site_symbols(&self) -> Option<impl VeclikeIterator<Item = &str> + '_>

Get the symbols for each site in the unit cell.

impl Poscar

Accessing computed properties

pub fn scaled_volume(&self) -> f64

Volume of a unit cell, taking the scale line into account.

This quantity is non-negative.

impl Poscar

Accessing the lattice vectors

pub fn scaled_lattice_vectors(&self) -> [[f64; 3]; 3]

Compute the true lattice vectors, taking the scale line into account.

pub fn unscaled_lattice_vectors(&self) -> [[f64; 3]; 3]

Get the lattice vectors as they are written.

impl Poscar

Accessing positions

pub fn scaled_positions(&self) -> Coords<Cow<[[f64; 3]]>>

Get either scaled_cart_positions or frac_positions, depending on which is stored.

pub fn scaled_cart_positions(&self) -> Cow<[[f64; 3]]>

Compute the Cartesian positions, taking into account the scale factor.

pub fn unscaled_cart_positions(&self) -> Cow<[[f64; 3]]>

Get the Cartesian positions, as they would be written in the file.

pub fn frac_positions(&self) -> Cow<[[f64; 3]]>

Get the fractional positions, as they would be written in the file.

impl Poscar

Accessing velocities

pub fn frac_velocities(&self) -> Option<Cow<[[f64; 3]]>>

Get the fractional-space velocities.

pub fn cart_velocities(&self) -> Option<Cow<[[f64; 3]]>>

Get the cartesian velocities.

Notice that the scale factor does not affect velocities.

Trait Implementations

impl Clone for Poscar

fn clone(&self) -> Poscar

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Poscar

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

Formats the value using the given formatter.

impl Display for Poscar

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

Formats the value using the given formatter.