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. Moreover the ExtXYZ.Atoms object directly adheres to the AtomsBase common interface for atomistic structures.

Maintainer: James Kermode (@jameskermode).

This package is registered in the General registry, so installation of the latest stable release is as simple as pressing ] to enter pkg> mode in the Julia REPL, and then entering:

pkg> add ExtXYZ

or for the development version:

pkg> dev https://github.com/libAtoms/ExtXYZ.jl

• The JuLIP.jl package is an optional - but recommended - companion. JuLIP can use ExtXYZ.jl to read and write extended XYZ files to/from JuLIP.Atoms instances, using the functions JuLIP.read_extxyz() and JuLIP.write_extxyz().
• The package is integrated with AtomsIO.jl to provide a uniform interface (based on AtomsBase) for reading and writing a large range of atomistic structure files.

Please open issues/PRs here with suggestions of other packages it would be useful to provide interfaces to.

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. Moreover ExtXYZ.Atoms provides a datastructure to expose the read configurations in an AtomsBase-compatible manner. All read and write 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

# Get a frame as AtomsBase-compatible ExtXYZ.Atoms object:
Atoms(read_frame("input.xyz"))

# Get list of frames as AtomsBase-compatible ExtXYZ.Atoms object:
Atoms.(read_frames("seq.xyz", 1:4)

The function iread_frames() provides lazy file-reading using a Channel:

for frame in iread_frames("input.xyz")
    process(frame) # do something with each frame
do

write_frames() can also be used for asynchronous writing by passing in a Channel:

Channel() do ch
    @async write_frames(outfile, ch)
    
    for frame in frames
        put!(ch, frame)
    end
end