ExtXYZ.jl Documentation

This package provides Julia bindings for the extxyz C library which implements a parser and writer for the extended XYZ file format used in materials and molecular modelling, following the specification set out in the extxyz repo.

Basic Usage

Four key functions are exported: read_frame() and write_frame() for reading and writing single configurations (snapshots), respectively, and read_frames() and write_frames() for reading and writing trajectories. All functions can work with string filenames, an open Base.IO instance or (intended primarily for internal use) a C FILE* pointer, stored as a Ptr{Cvoid} type.

using ExtXYZ

frame = read_frame("input.xyz")  # single atomic configuration, represented as a Dict{String}{Any}
write_frame("output.xyz", frame) # write a single frame to `output.xyz`. 

frame10 = read_frame("input.xyz", 10) # read a specific frame, counting from 1 for first frame in file

all_frames = read_frames("seq.xyz")  # read all frames, returns Vector{Dict{String}{Any}}
frames = read_frames("seq.xyz", 1:4) # specific range of frames

write_frames("output.xyz", frames, append=true) # append four frames to output

read_frame(file; use_regex=false, use_cleri=true)

Read a single frame from the ExtXYZ file file, which can be a file pointer, an open IO stream, a string filename or an IOBuffer.

Keyword arguments:

• use_regex: if false (default), per-atom lines are parsed with a fast whitespace tokenizer that validates each field. If true, the stricter but slower PCRE2 regular-expression parser is used instead; it is marginally more rigid about numeric formats.
• use_cleri: if true (default), the comment (key/value) line is parsed with the libcleri grammar. If false, a faster first-char-dispatch parser is used instead; it is bit-identical to the grammar on valid input and validates each token with the same patterns, and is most worthwhile for many small frames where comment-line parsing dominates.

Malformed input raises an ErrorException containing the parser's message.

Reading from IOBuffers is currently not supported on Windows.

read_frames(file[, range]; use_regex=false, use_cleri=true)

Read a sequence of frames from the ExtXYZ file, which can be specified by a file pointer, filename, IOStream or IOBuffer.

range can be a single integer, range object or integer array of frame indices. See read_frame for the meaning of use_regex and use_cleri.

Reading from IOBuffers is currently not supported on Windows.

iread_frames(file[, range]; use_regex=false)

Return a Channel for reading from an ExtXYZ file. Frames are yielded one by one. range can be a single integer, range object or integer array of frame indices. See read_frame for the meaning of use_regex and use_cleri.

Example usage:

ch = iread_frames("file.xyz")
for frame in ch
    process(frame)
end

write_frame(file, dict; fmt_i=nothing, fmt_f=nothing, fmt_b=nothing, fmt_s=nothing)

Write a single atomic configuration represented by dict to file, which can be a file pointer, open IO stream or string filename.

The fmt_* keyword arguments accept C printf-style format strings overriding the output format for integer, float, bool and string values respectively (e.g. fmt_f="%21.16f" for full double precision). When nothing (default), the library defaults are used ("%8d", "%16.8f", "%.1s", "%s").

write_frames(file, dicts; append=false, fmt_i=nothing, fmt_f=nothing, fmt_b=nothing, fmt_s=nothing)

Write a sequence of atomic configurations to file. See write_frame for the meaning of the fmt_* format-string keywords. Can also be used asynchronously by passing a Channel in place of dicts, e.g.

Channel() do ch
    @async write_frames(outfile, ch)

    for frame in frames
        put!(ch, frame)
    end
end