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)

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.

Reading from IOBuffers is currently not supported on Windows.

read_frames(file[, range])

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.

Reading from IOBuffers is currently not supported on Windows.

iread_frames(file[, range])

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.

Example usage:

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

write_frame(file, dict)

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

write_frames(file, dicts)

Write a sequence of atomic configurations to file. 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