Language bindings

1 Python (PyO3)

1.1 Installation

# From PyPI
pip install readcon

# From source with maturin
maturin develop --features python

# Or via pixi
pixi r -e python python-build

1.2 Usage

import readcon

# Read frames
frames = readcon.read_con("path/to/file.con")
frames = readcon.read_con_string(contents)

# Access data
for frame in frames:
    print(frame.cell)           # [f64, f64, f64]
    print(frame.angles)         # [f64, f64, f64]
    print(frame.has_velocities)
    for atom in frame.atoms:
        print(atom.symbol, atom.x, atom.y, atom.z, atom.mass)
        if atom.has_velocity:
            print(atom.vx, atom.vy, atom.vz)

# Construct frames (v0.4.0+)
atom = readcon.Atom(symbol="Cu", x=0.0, y=0.0, z=0.0,
                    is_fixed=False, atom_id=1)
frame = readcon.ConFrame(cell=[10.0, 10.0, 10.0],
                         angles=[90.0, 90.0, 90.0],
                         atoms=[atom])

# Write frames (with optional precision)
readcon.write_con("output.con", frames)
readcon.write_con("precise.con", frames, precision=17)
output_str = readcon.write_con_string(frames)

# ASE conversion (v0.4.0+, requires ase)
ase_atoms = frame.to_ase()
frame2 = readcon.ConFrame.from_ase(ase_atoms)

1.3 Types

readcon.Atom

Constructable with keyword arguments (v0.4.0+). Properties: symbol, x, y, z, is_fixed, atom_id, mass (v0.4.2+), vx, vy, vz, has_velocity

readcon.ConFrame

Constructable with cell, angles, atoms, and optional headers (v0.4.0+). Properties: cell, angles, atoms, has_velocities, prebox_header, postbox_header. Methods: to_ase(), from_ase() (v0.4.0+)

2 Julia (ccall)

2.1 Installation

Set READCON_LIB_PATH to the shared library path, or build with cargo build --release and the Julia package will find it automatically.

export READCON_LIB_PATH=/path/to/libreadcon_core.so

2.2 Usage

using ReadCon

frames = read_con("path/to/file.con")

for frame in frames
    println(frame.cell)
    println(frame.angles)
    println(frame.has_velocities)
    for atom in frame.atoms
        println(atom.x, " ", atom.y, " ", atom.z)
    end
end

2.3 Types

ReadCon.Atom

atomic_number, x, y, z, atom_id, mass, is_fixed, vx, vy, vz, has_velocity

ReadCon.ConFrame

cell, angles, atoms, has_velocities, prebox_header, postbox_header

3 C/C++ (FFI)

3.1 C API

Include readcon-core.h and link against libreadcon_core.

#include "readcon-core.h"

CConFrameIterator *iter = read_con_file_iterator("file.con");
RKRConFrame *handle;
while ((handle = con_frame_iterator_next(iter)) != NULL) {
    CFrame *frame = rkr_frame_to_c_frame(handle);
    printf("Atoms: %zu, Velocities: %s\n",
           frame->num_atoms, frame->has_velocities ? "yes" : "no");
    for (size_t i = 0; i < frame->num_atoms; i++) {
        CAtom *a = &frame->atoms[i];
        if (a->has_velocity) {
            printf("  vel=(%.6f, %.6f, %.6f)\n", a->vx, a->vy, a->vz);
        }
    }
    free_c_frame(frame);
    free_rkr_frame(handle);
}
free_con_frame_iterator(iter);

3.2 C++ API

Include readcon-core.hpp for RAII wrappers.

#include "readcon-core.hpp"

readcon::ConFrameIterator frames("file.con");
for (auto&& frame : frames) {
    auto& cell = frame.cell();
    auto& atoms = frame.atoms();
    bool has_vel = frame.has_velocities();
    for (const auto& atom : atoms) {
        if (atom.has_velocity) {
            std::cout << atom.vx << " " << atom.vy << " " << atom.vz << "\n";
        }
    }
}

3.3 Build system integration

3.3.1 Meson subproject

readcon = subproject('readcon-core')
readcon_dep = readcon.get_variable('readcon_dep')

executable('my_app', 'main.cpp', dependencies: readcon_dep)

3.3.2 CMake subproject

add_subdirectory(readcon-core)
target_link_libraries(my_app PRIVATE readcon-core::readcon-core)