### Run Rust Example

Source: https://github.com/lode-org/readcon-core/blob/main/README.md

Execute the Rust example directly using cargo.

```bash
cargo run --example rust_usage -- resources/test/tiny_multi_cuh2.con
```

--------------------------------

### Python Installation (Pixi)

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/bindings.org

Install and run Python-related tasks using Pixi.

```shell
pixi r -e python python-build
```

--------------------------------

### ASE Conversion Example

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/bindings.org

Converts a readcon frame to ASE format and back. Requires the 'ase' library to be installed.

```python
ase_atoms = frame.to_ase()
frame2 = readcon.ConFrame.from_ase(ase_atoms)
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Clone the readcon-core repository and install project dependencies using pixi.

```shell
git clone https://github.com/lode-org/readcon-core.git
cd readcon-core
pixi install
```

--------------------------------

### Meson Build and Test Setup

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Set up and run tests for the project using Meson build system.

```shell
# Meson build with valgrind leak checking
meson setup bbdir -Dwith_tests=True -Dwith_examples=True
meson test -C bbdir
```

--------------------------------

### Initial PyPI Release Setup

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Manual steps required for the very first release to PyPI when the trusted publisher is not yet configured.

```shell
#+begin_src shell

```

--------------------------------

### Install readcon-core with cargo-c

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/architecture.org

Installs the readcon-core library using cargo-c, specifying installation paths for headers, libraries, and pkg-config files.

```bash
cargo cinstall --prefix=$PREFIX --libdir=$PREFIX/lib --library-type cdylib
```

--------------------------------

### Install C/C++ readcon-core System Library

Source: https://github.com/lode-org/readcon-core/blob/main/README.md

Installs C/C++ libraries and headers for system-wide use. Requires a C99 or C++17 compiler.

```bash
cargo cinstall --release --prefix /usr/local
```

--------------------------------

### Python Installation (Source with Maturin)

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/bindings.org

Install readcon from source using Maturin, enabling the 'python' feature.

```shell
maturin develop --features python
```

--------------------------------

### Print Library Version

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Example of how to use the VERSION constant to display the readcon-core library version.

```rust
use readcon_core::VERSION;

println!("readcon-core version: {}", VERSION);
```

--------------------------------

### Install readcon Python Package

Source: https://github.com/lode-org/readcon-core/blob/main/README.md

Use this command to install the readcon Python package.

```python
pip install readcon
```

--------------------------------

### Periodic Boundary Conditions Example

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/spec.org

Demonstrates the JSON structure for specifying periodic boundary conditions. Use this to indicate which cell directions are periodic.

```json
{"con_spec_version":2,"pbc":[true,true,false]}
```

--------------------------------

### Rust: Example Usage of ConFrameBuilder

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Demonstrates the creation of a ConFrameBuilder, adding an atom, and building the final frame. Includes assertions for the constructed frame's header.

```rust
let mut builder = ConFrameBuilder::new([10.0; 3], [90.0; 3]);
builder.add_atom("Cu", 0.0, 0.0, 0.0, [false; 3], 0, 63.546);
let frame = builder.build();
assert_eq!(frame.header.natm_types, 1);
```

--------------------------------

### Start Cap'n Proto RPC Server

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/rpc.org

Launches a TCP RPC server for the readcon-core service on a specified host and port. This function is asynchronous and requires a Tokio runtime.

```rust
// Start a TCP RPC server
#[tokio::main]
async fn main() {
    readcon_core::rpc::server::start_server("127.0.0.1:9876")
        .await
        .unwrap();
}
```

--------------------------------

### Install readcon Python Package

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/tutorials.org

Provides commands for installing the readcon Python package via pip, from source using maturin, or through pixi.

```shell
# From PyPI
pip install readcon

# From source
maturin develop --features python

# Via pixi
pixi r -e python python-build
```

--------------------------------

### Python Version and Spec Queries

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/bindings.org

Print the installed readcon version and the supported CON specification version.

```python
import readcon

print(readcon.__version__)       # e.g. "0.5.0"
print(readcon.CON_SPEC_VERSION)  # 2
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Examples of commit messages following the conventional commits specification for various types of changes.

```text
feat: add convel format support with optional velocity fields
enh: integrate fast-float2 for f64 parsing hot path
fix: handle empty velocity section in multi-frame files
doc: update tutorials with Julia convel example
bld: add CMakeLists.txt for cmake subproject use
tst: add roundtrip test for convel writer
```

--------------------------------

### Install Readcon Python Bindings

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/faq.org

Install the Python bindings for readcon-core using pip. This allows you to use the library's functionality within your Python projects.

```python
import readcon

```

--------------------------------

### Build readcon-core with RPC feature

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/rpc.org

Build the readcon-core project with the 'rpc' feature enabled. This requires the Cap'n Proto compiler to be installed.

```shell
# Requires capnproto installed (via pixi or system package)
cargo build --features rpc

# Or via pixi (capnproto is a dependency)
pixi r build-rpc
```

--------------------------------

### Legacy (pre-v2) File Structure

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/spec.org

An example of a legacy readcon file that predates the version 2 specification. It is parsed as version 1.

```text
Random Number Seed
0.0000 TIME
15.345600 21.702000 100.000000
90.000000 90.000000 90.000000
0 0
0 0 0
2
216 2
63.546 1.00793
Cu
Coordinates of Component 1
   0.639400    0.904500   -0.000100 1    0
   3.197000    0.904500   -0.000100 1    1
...
```

--------------------------------

### Complete Rust Write Example

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/writer.md

This Rust code snippet shows how to build a ConFrame object by adding atoms with their properties (like velocity and force), setting metadata, and then writing the frame to a file named 'output.con' with a specified precision.

```rust
use readcon_core::types::ConFrameBuilder;
use readcon_core::writer::ConFrameWriter;
use std::path::Path;

fn main() -> std::io::Result<()> {
    // Build a frame
    let mut builder = ConFrameBuilder::new([10.0, 10.0, 10.0], [90.0, 90.0, 90.0]);
    
    // Add atoms (interleaved by element, then sorted by symbol)
    builder
        .add_atom("Cu", 0.0, 0.0, 0.0, [false; 3], 0, 63.546)
        .with_velocity([0.1, 0.2, 0.3])
        .with_force([1.0, 0.0, 0.0]);
    
    builder
        .add_atom("H", 1.0, 1.0, 1.0, [false; 3], 1, 1.008)
        .with_velocity([0.01, 0.02, 0.03])
        .with_force([0.5, 0.0, 0.0]);
    
    // Set metadata
    builder
        .prebox_header("Generated by my_app")
        .set_frame_index(0)
        .set_energy(-42.5)
        .set_time(0.0)
        .set_units(serde_json::json!({"length": "angstrom", "energy": "eV"}));
    
    let frame = builder.build();
    
    // Write to file
    let mut writer = ConFrameWriter::from_path_with_precision("output.con", 8)?;
    writer.write_frame(&frame)?;
    
    Ok(())
}

```

--------------------------------

### Combine Multiple Features

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Example of how to enable multiple features simultaneously for readcon-core by listing them in the 'features' array within the Cargo.toml file.

```toml
[dependencies]
readcon-core = { version = "0.10.0", features = ["parallel", "zstd", "metatensor"] }
```

--------------------------------

### Expected Output File Content

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/writer.md

This is the content of the 'output.con' file generated by the Rust code example. It includes header information, atom data, velocities, and forces.

```text
Generated by my_app
{"con_spec_version":2,"sections":["velocities","forces"],"energy":-42.5,"frame_index":0,"time":0.0,"units":{"energy":"eV","length":"angstrom"}}
10.000000 10.000000 10.000000
90.000000 90.000000 90.000000
POSTBOX LINE 1
POSTBOX LINE 2
2
1 1
63.5460000 1.00800000
Cu
Coordinates of Component 1
0.00000000 0.00000000 0.00000000 0 0
H
Coordinates of Component 2
1.00000000 1.00000000 1.00000000 0 1

Cu
Velocities of Component 1
0.10000000 0.20000000 0.30000000 0 0
H
Velocities of Component 2
0.01000000 0.02000000 0.03000000 0 1

Cu
Forces of Component 1
1.00000000 0.00000000 0.00000000 0 0
H
Forces of Component 2
0.50000000 0.00000000 0.00000000 0 1

```

--------------------------------

### Lattice Vectors Example

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/spec.org

Shows the JSON format for defining the exact 3x3 lattice cell matrix. This provides precise cell dimensions in angstroms.

```json
{"con_spec_version":2,"lattice_vectors":[[10.0,0.0,0.0],[0.0,10.0,0.0],[0.0,0.0,20.0]]}
```

--------------------------------

### JSON Metadata Example for Sections

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/faq.org

Illustrates the 'sections' key in the JSON metadata for version 2 con files, specifying the presence and order of per-atom data like velocities and forces. This mechanism provides explicit parsing instructions.

```json
{"con_spec_version":2,"sections":["velocities","forces"]}
```

--------------------------------

### Example of UnsupportedSpecVersion Condition

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/errors.md

Demonstrates the UnsupportedSpecVersion error, which arises when a .con file specifies a 'con_spec_version' value that is newer than the readcon-core library currently supports. The library's maximum supported version is 2.

```json
{"con_spec_version": 5}  [library only supports up to 2]
```

--------------------------------

### Example of MissingSpecVersion Condition

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/errors.md

Shows the MissingSpecVersion error, occurring when the JSON metadata in a .con file lacks the required 'con_spec_version' key. This is specifically triggered if line 2 starts with '{' but the key is absent.

```json
{"energy": -42.5}  [missing con_spec_version]
```

--------------------------------

### Profile-Guided Optimization (PGO) - Step 1: Build Instrumented Binary

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Build an instrumented binary for Profile-Guided Optimization (PGO). Ensure to pass necessary features and use --no-run to avoid executing the benchmarks at this stage.

```shell
# 1. Build instrumented binary; pass --features for everything you
#    want profile data on.
mkdir -p /tmp/readcon-pgo
RUSTFLAGS="-Cprofile-generate=/tmp/readcon-pgo" \
  cargo bench --features parallel,zstd,rpc --no-run
```

--------------------------------

### Profile-Guided Optimization (PGO) - Step 2: Run Benches for Profile Data Collection

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Run the benchmarks with the instrumented binary to collect raw profile data (.profraw files). This step is crucial for PGO.

```shell
# 2. Run the benches to collect .profraw files.
RUSTFLAGS="-Cprofile-generate=/tmp/readcon-pgo" \
  cargo bench --features parallel,zstd,rpc
```

--------------------------------

### Reproducing Benchmark Results

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/benchmarks.org

Shell command to reproduce the benchmarks discussed in the documentation. Ensure you have the necessary tools and data available.

```shell

```

--------------------------------

### Run Benchmarks

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Execute project benchmarks using either Cargo or pixi.

```shell
# Benchmarks
cargo bench
# or: pixi r bench
```

--------------------------------

### Connect to and use RPC Client

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/rpc.org

Establishes a connection to the readcon-core RPC server and demonstrates parsing a file and writing frames. Requires the RpcClient to be imported.

```rust
use readcon_core::rpc::client::RpcClient;
use std::path::Path;

let client = RpcClient::new("127.0.0.1:9876").unwrap();
let frames = client.parse_file(Path::new("input.con")).unwrap();
let output = client.write_frames(&frames).unwrap();
```

--------------------------------

### Initialize Julia ReadCon Project

Source: https://github.com/lode-org/readcon-core/blob/main/README.md

Use this command to instantiate the Julia project for ReadCon.

```julia
julia --project=julia/ReadCon -e 'using Pkg; Pkg.instantiate()'
```

--------------------------------

### Get Timestep

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the integration timestep from metadata. Returns `None` if not set.

```rust
pub fn timestep(&self) -> Option<f64>
```

--------------------------------

### Get Library Version

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Retrieve the library version string, which is injected from Cargo.toml at compile time.

```rust
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
```

--------------------------------

### Create GitHub Release

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Build the release, package libraries and headers, and create a GitHub release with artifacts and notes.

```shell
cargo build --release

# Package shared/static library + headers for C/C++/Julia
mkdir -p /tmp/pkg/{lib,include}
cp target/release/libreadcon_core.so /tmp/pkg/lib/
cp target/release/libreadcon_core.a /tmp/pkg/lib/
cp include/readcon-core.h /tmp/pkg/include/
cp include/readcon-core.hpp /tmp/pkg/include/
tar czf readcon-core-vX.Y.Z-linux-x86_64.tar.gz -C /tmp pkg/

# Package Julia bindings
tar czf ReadCon.jl-vX.Y.Z.tar.gz -C julia ReadCon/

# Create release (attach capnp schema too)
gh release create vX.Y.Z \
  readcon-core-vX.Y.Z-linux-x86_64.tar.gz \
  ReadCon.jl-vX.Y.Z.tar.gz \
  schema/ReadCon.capnp \
  --repo lode-org/readcon-core \
  --title "vX.Y.Z" \
  --notes-file <(cog changelog --at vX.Y.Z)
```

--------------------------------

### Get Potential Parameters

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the potential parameters as a JSON object from metadata. Returns `None` if absent.

```rust
pub fn potential_params(&self) -> Option<&serde_json::Value>
```

--------------------------------

### Build with PGO

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Build the project with Profile-Guided Optimization (PGO) by merging profraw data and then building with the merged profile.

```shell
rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin/llvm-profdata \
  merge -o /tmp/readcon-pgo/merged.profdata /tmp/readcon-pgo
RUSTFLAGS="-Cprofile-use=/tmp/readcon-pgo/merged.profdata" \
  cargo build --release --features parallel,zstd,rpc
```

--------------------------------

### Get NEB Band Index

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the index of the NEB (Nudged Elastic Band) band. Returns `None` if absent.

```rust
pub fn neb_band(&self) -> Option<u64>
```

--------------------------------

### Get Frame Index

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the zero-based index of this frame within a trajectory. Returns `Some(index)` if present, otherwise `None`.

```rust
pub fn frame_index(&self) -> Option<u64>
```

--------------------------------

### Build and Write a New CON Frame

Source: https://github.com/lode-org/readcon-core/blob/main/readme_src.org

Demonstrates how to create a new CON frame with specified cell dimensions, angles, and atom properties, then write it to a file.

```python
b = readcon.ConFrameBuilder(cell=[10.0, 10.0, 10.0], angles=[90.0, 90.0, 90.0])
b.set_energy(-42.5).add_atom("Cu", 0.0, 0.0, 0.0, 1, 63.546)
b.write("out.con")
```

--------------------------------

### build()

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Consumes the builder and produces a ConFrame. Atoms are grouped by symbol in encounter order.

```APIDOC
## build()

### Description
Consumes the builder and produces a `ConFrame`. Atoms are grouped by symbol in encounter order.

### Method
Consumes the builder.

### Returns
Constructed ConFrame.

### Example
```rust
let mut builder = ConFrameBuilder::new([10.0; 3], [90.0; 3]);
builder.add_atom("Cu", 0.0, 0.0, 0.0, [false; 3], 0, 63.546);
let frame = builder.build();
assert_eq!(frame.header.natm_types, 1);
```

### Source
`src/types.rs:715`
```

--------------------------------

### Build Release with Pixi

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Build the project in release mode using pixi.

```shell
# Build release
pixi r build
```

--------------------------------

### v2 File with Velocities and Forces

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/spec.org

A version 2 readcon file that includes optional 'velocities' and 'forces' sections, along with energy and potential parameters.

```text
Generated by eOn
{"con_spec_version":2,"sections":["velocities","forces"],"energy":-42.5,"potential":{"type":"EMT","params":{}}}
15.345600 21.702000 100.000000
90.000000 90.000000 90.000000
0 0
218 0 1
2
2 2
63.546000 1.007930
Cu
Coordinates of Component 1
   0.639400    0.904500    6.975300 7    0
   3.196900    0.904500    6.975300 7    1
H
Coordinates of Component 2
   8.682300    9.947000   11.733000 0  2
   7.942100    9.947000   11.733000 0  3

Cu
Velocities of Component 1
   0.001234    0.002345   -0.003456 7    0
   0.004567   -0.005678    0.006789 7    1
H
Velocities of Component 2
  -0.012345    0.023456    0.034567 0  2
   0.045678   -0.056789   -0.067890 0  3

Cu
Forces of Component 1
   0.123456    0.234567   -0.345678 7    0
   0.456789   -0.567890    0.678901 7    1
H
Forces of Component 2
  -1.234567    2.345678    3.456789 0  2
   4.567890   -5.678901   -6.789012 0  3
```

--------------------------------

### Check Supported Spec Version

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Example of how to use the CON_SPEC_VERSION constant to conditionally execute code based on the supported specification version.

```rust
use readcon_core::CON_SPEC_VERSION;

if frame.header.spec_version <= CON_SPEC_VERSION {
    println!("Supported spec version");
}
```

--------------------------------

### Get NEB Bead Index

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the index of the NEB (Nudged Elastic Band) bead (image). Returns `None` if absent.

```rust
pub fn neb_bead(&self) -> Option<u64>
```

--------------------------------

### Run Tests with Pixi

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Execute the project's tests using the pixi run command.

```shell
# Run tests
pixi r test

# Run with all features (needs capnproto)
pixi r test-all
```

--------------------------------

### Build and Write a New Frame in Python

Source: https://github.com/lode-org/readcon-core/blob/main/README.md

Construct a new frame with specified cell dimensions, angles, energy, and atom data, then write it to a file.

```python
# Build and write a new frame
b = readcon.ConFrameBuilder(cell=[10.0, 10.0, 10.0], angles=[90.0, 90.0, 90.0])
b.set_energy(-42.5).add_atom("Cu", 0.0, 0.0, 0.0, 1, 63.546)
b.write("out.con")
```

--------------------------------

### Get Periodic Boundary Conditions

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the periodic boundary conditions as a boolean array for x, y, and z directions. Returns `None` if not set.

```rust
pub fn pbc(&self) -> Option<[bool; 3]>
```

--------------------------------

### Meson Build System Integration

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/bindings.org

Integrate ReadCon Core as a subproject in Meson, obtaining the dependency and linking it to your executable.

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

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

```

--------------------------------

### Set Periodic Boundary Conditions

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Sets the periodic boundary conditions for the simulation.

```rust
pub fn set_pbc(&mut self, pbc: [bool; 3])
```

--------------------------------

### Get Simulation Time

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the simulation time for this frame, based on the declared time unit. Returns `Some(time)` if present, otherwise `None`.

```rust
pub fn time(&self) -> Option<f64>
```

--------------------------------

### Constructing Frames Programmatically

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/tutorials.org

Demonstrates how to create ConFrame objects from scratch using Atom and ConFrame constructors. This is useful for building trajectory data programmatically.

```python
import readcon

atoms = [
    readcon.Atom(symbol="Cu", x=0.0, y=0.0, z=0.0,
                 fixed=[False, False, False], atom_id=1),
    readcon.Atom(symbol="Cu", x=2.55, y=2.55, z=0.0,
                 fixed=[False, False, False], atom_id=2),
]
frame = readcon.ConFrame(
    cell=[10.0, 10.0, 10.0],
    angles=[90.0, 90.0, 90.0],
    atoms=atoms,
)
frame.atoms.append(readcon.Atom(symbol="H", x=1.0, y=1.0, z=1.0))
frame.atoms[0].fixed = [True, False, True]
```

--------------------------------

### Run Tests

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Execute all tests, including those with all features enabled, and run Python tests using pixi.

```shell
cargo test
cargo test --all-features
pixi r -e python python-test
```

--------------------------------

### Get Lattice Vectors

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the exact 3x3 lattice vector matrix in angstroms. This takes precedence over length/angle values. Returns `None` if not set.

```rust
pub fn lattice_vectors(&self) -> Option<[[f64; 3]; 3]>
```

--------------------------------

### Build and Write a ConFrame

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/index.md

Create a new ConFrame using ConFrameBuilder, add atoms, build the frame, and then write it to a .con file using ConFrameWriter.

```rust
use readcon_core::types::ConFrameBuilder;
use readcon_core::writer::ConFrameWriter;

let mut builder = ConFrameBuilder::new([10.0; 3], [90.0; 3]);
builder.add_atom("Cu", 0.0, 0.0, 0.0, [false; 3], 0, 63.546);
let frame = builder.build();

let mut writer = ConFrameWriter::from_path("output.con")?;
writer.write_frame(&frame)?;
```

--------------------------------

### Run Cross-implementation Speed Comparison

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/benchmarks.org

Executes a Python script to compare the speed of ASE, C, and readcon implementations. Requires matplotlib and numpy.

```bash
uv run --with matplotlib --with numpy --with ase python benches/compare_readers.py
```

--------------------------------

### Get Potential Type

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the potential type string from metadata (e.g., "EMT", "LJ"). Returns `None` if absent.

```rust
pub fn potential_type(&self) -> Option<&str>
```

--------------------------------

### Build ConFrame with Atoms and Velocities

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/tutorials.org

Demonstrates building a ConFrame object by adding atoms with and without velocity and force information using the C++ API.

```cpp
#include "readcon-core.hpp"

readcon::ConFrameBuilder builder(
    {10.0, 10.0, 10.0}, {90.0, 90.0, 90.0});
builder.add_atom("Cu", 0.0, 0.0, 0.0, false, 1, 63.546);
builder.add_atom_with_velocity_and_forces(
    "Cu", 2.55, 2.55, 0.0,
    {true, false, true},
    2, 63.546,
    0.1, 0.2, 0.3,
    -0.1, -0.2, -0.3);
auto frame = builder.build();
```

--------------------------------

### Get Per-Frame Total Energy

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the total energy value stored in the frame's JSON metadata. Returns `Some(energy)` if present, otherwise `None`.

```rust
pub fn energy(&self) -> Option<f64>
```

--------------------------------

### JSON Metadata for Validation Mode

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/spec.org

Example of JSON metadata enabling validation mode. When 'validate' is set to true, readers perform stricter checks on data consistency.

```json
{"con_spec_version":2,"validate":true}
```

--------------------------------

### Runtime Access to Library Version (C/FFI)

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Shows how to access the library version string from C or other FFI consumers using the provided C API function.

```c
const char* version = rkr_library_version();
```

--------------------------------

### Get CON Spec Version

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Access the current CON/convel format specification version implemented by the build. This constant is used to check compatibility with different format versions.

```rust
pub const CON_SPEC_VERSION: u32 = 2;
```

--------------------------------

### Convert Chemical Symbol to Atomic Number

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/helpers.md

Use this function to get the atomic number for a given chemical symbol. It is case-sensitive and returns 0 for unknown or invalid symbols.

```rust
use readcon_core::helpers::symbol_to_atomic_number;

assert_eq!(symbol_to_atomic_number("H"), 1);
assert_eq!(symbol_to_atomic_number("C"), 6);
assert_eq!(symbol_to_atomic_number("Fe"), 26);
assert_eq!(symbol_to_atomic_number("U"), 92);
assert_eq!(symbol_to_atomic_number("Xx"), 0);  // Unknown
assert_eq!(symbol_to_atomic_number("h"), 0);   // Case-sensitive
```

--------------------------------

### Automatic Compression Support (Rust)

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/iterators.md

Demonstrates automatic detection and handling of compressed files (.con.gz, .con.zst) when reading frames. Pass the full filename to reading functions.

```rust
// All these work automatically:
read_all_frames(Path::new("frames.con"))?;
read_all_frames(Path::new("frames.con.gz"))?;
read_all_frames(Path::new("frames.con.zst"))?;
```

--------------------------------

### set_pbc()

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Sets the periodic boundary conditions for the simulation.

```APIDOC
## set_pbc()

### Description
Sets periodic boundary conditions.

### Parameters
- `pbc` (`[bool; 3]`) - An array of three booleans indicating PBC status for x, y, and z directions.
```

--------------------------------

### Example of IncompleteFrame Condition

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/errors.md

Illustrates the condition for an IncompleteFrame error, where the file ends prematurely while reading atom coordinate data. This happens when the iterator finishes before all promised atoms are parsed.

```text
User comment
{"con_spec_version":2}
10.0 10.0 10.0
90.0 90.0 90.0
Line 5
Line 6
1
1
12.011
C
Coordinates of Component 1
1.0 1.0 1.0 0 0
[FILE ENDS HERE, but 1 atom promised]
```

--------------------------------

### Count Elements from Frame Data

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/helpers.md

An example function showing how to count the occurrences of each element symbol within a `ConFrame`'s atom data. It utilizes a HashMap for efficient counting.

```rust
use readcon_core::helpers::symbol_to_atomic_number;
use std::collections::HashMap;

fn count_elements(frame: &ConFrame) -> HashMap<String, usize> {
    let mut counts = HashMap::new();
    for atom in &frame.atom_data {
        *counts.entry(atom.symbol.to_string()).or_insert(0) += 1;
    }
    counts
}
```

--------------------------------

### Example of InvalidNumberFormat Condition

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/errors.md

Illustrates the InvalidNumberFormat error, which occurs when a token on a numeric line cannot be parsed into the required numeric type (e.g., float or integer). The parser fails on a non-numeric token.

```text
10.0 abc 30.0  [cannot parse "abc" as f64]
```

--------------------------------

### Run Core Rust Tests

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Execute the core Rust tests for the project.

```shell
# Core Rust tests
cargo test
```

--------------------------------

### Example of IncompleteVelocitySection Condition

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/errors.md

Shows the scenario leading to an IncompleteVelocitySection error, where the file terminates during the parsing of velocity data after a blank separator line. The iterator ends before all velocity atoms are read.

```text
[... complete coordinate section ...]
[blank line]
Cu
Velocities of Component 1
[FILE ENDS, expected velocity line]
```

--------------------------------

### Convert Atomic Number to Chemical Symbol

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/helpers.md

Use this function to get the chemical symbol for a given atomic number. It returns 'X' for atomic numbers outside the supported range (1-92).

```rust
use readcon_core::helpers::atomic_number_to_symbol;

assert_eq!(atomic_number_to_symbol(1), "H");
assert_eq!(atomic_number_to_symbol(6), "C");
assert_eq!(atomic_number_to_symbol(26), "Fe");
assert_eq!(atomic_number_to_symbol(92), "U");
assert_eq!(atomic_number_to_symbol(0), "X");     // Unknown
assert_eq!(atomic_number_to_symbol(100), "X");   // Out of range
```

--------------------------------

### Enable RPC Feature

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Configure the readcon-core dependency to include the 'rpc' feature for Cap'n Proto RPC interface, enabling network-accessible parsing. This adds significant dependencies including capnp, capnp-rpc, and tokio.

```toml
[dependencies]
readcon-core = { version = "0.10.0", features = ["rpc"] }
```

--------------------------------

### Build and Write Frame

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/index.md

Construct a new ConFrame using `ConFrameBuilder` and write it to a file using `ConFrameWriter`, with support for compression.

```APIDOC
## Build and Write Frame

### Description
Allows programmatic creation of `ConFrame` objects using `ConFrameBuilder` and writing them to a file with `ConFrameWriter`, supporting compression.

### Method
1. Instantiate `ConFrameBuilder`.
2. Add atoms and metadata using builder methods.
3. Build the `ConFrame`.
4. Instantiate `ConFrameWriter` with a file path.
5. Write the frame using `writer.write_frame()`.

### Endpoint
N/A (Rust library usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use readcon_core::types::ConFrameBuilder;
use readcon_core::writer::ConFrameWriter;

let mut builder = ConFrameBuilder::new([10.0; 3], [90.0; 3]);
builder.add_atom("Cu", 0.0, 0.0, 0.0, [false; 3], 0, 63.546);
let frame = builder.build();

let mut writer = ConFrameWriter::from_path("output.con")?;
writer.write_frame(&frame)?;
```

### Response
#### Success Response
Indicates successful writing of the frame to the specified file.

#### Response Example
```rust
// File 'output.con' is created or appended with the frame.
```

### Error Handling
Returns a `Result` which can contain an error during frame building or file writing.
```

--------------------------------

### Commit Release Preparation

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Stage and commit all files related to release preparation, including version files, CHANGELOG.md, and README.md.

```shell
git add Cargo.toml Cargo.lock meson.build pyproject.toml \
           pixi.toml docs/source/conf.py src/lib.rs \
           CHANGELOG.md README.md docs/orgmode/contributing.org
git commit -m "maint: bump to vX.Y.Z"
```

--------------------------------

### Example of InvalidVectorLength Condition

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/errors.md

Demonstrates the InvalidVectorLength error condition where a numeric line contains an incorrect number of columns. This occurs when parsing functions expect a specific number of tokens but find a different count.

```text
10.0 10.0 10.0 90.0  [4 values instead of 3]
```

--------------------------------

### Query Library and File Spec Versions in C/C++

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/tutorials.org

Shows how to perform compile-time checks for the library spec version and retrieve runtime library and file spec versions. Uses the 'readcon-core.h' header.

```c
#include "readcon-core.h"

// Compile-time library version check
#if RKR_CON_SPEC_VERSION >= 2
    // atom_id semantics available
#endif

// Runtime library version
printf("spec v%u, lib %s\n",
       rkr_con_spec_version(), rkr_library_version());

// Per-frame version (from parsed file)
RKRConFrame *handle = rkr_read_first_frame("input.con");
printf("File spec version: %u\n", rkr_frame_spec_version(handle));

// Full JSON metadata
char *json = rkr_frame_metadata_json(handle);
printf("Metadata: %s\n", json);
rkr_free_string(json);
free_rkr_frame(handle);

```

--------------------------------

### Get Units

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Retrieves the unit system as a JSON object (e.g., `{"length":"angstrom","energy":"eV"}`). Returns `None` if absent.

```rust
pub fn units(&self) -> Option<&serde_json::Value>
```

--------------------------------

### Tag Release

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Create a signed Git tag for the release.

```shell
git tag -s vX.Y.Z -m "vX.Y.Z"
```

--------------------------------

### Enable Python Bindings Feature

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Configure the readcon-core dependency to include the 'python' feature for PyO3-based Python bindings. This is primarily for Rust consumers embedding Python interpreters; Python users should install the 'readcon' package via pip.

```toml
[dependencies]
readcon-core = { version = "0.10.0", features = ["python"] }
```

--------------------------------

### Publish to crates.io

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/contributing.org

Publish the release to crates.io.

```shell
cargo publish
```

--------------------------------

### RAII Frame Iteration in C++

Source: https://github.com/lode-org/readcon-core/blob/main/docs/orgmode/tutorials.org

Demonstrates iterating through frames in a CONVEL file using a range-based for loop and RAII, printing cell dimensions and atom information.

```cpp
#include "readcon-core.hpp"
#include <iostream>

int main(int argc, char *argv[]) {
    readcon::ConFrameIterator frames(argv[1]);

    for (auto&& frame : frames) {
        auto cell = frame.cell();
        auto angles = frame.angles();
        std::cout << "Cell: " << cell[0] << ", " << cell[1] << ", "
                  << cell[2] << "\n";
        std::cout << "Has velocities: " << std::boolalpha
                  << frame.has_velocities() << "\n";

        for (const auto& atom : frame.atoms()) {
            std::cout << "  (" << atom.x << ", " << atom.y << ", "
                      << atom.z << ")";
            if (atom.has_velocity) {
                std::cout << " vel=(" << atom.vx << ", " << atom.vy
                          << ", " << atom.vz << ")";
            }
            std::cout << "\n";
        }
    }
    return 0;
}

```

--------------------------------

### Rust: Create PreboxHeader

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/api-reference/types.md

Constructs a new PreboxHeader from user-facing text. The metadata line is initialized empty and populated by the writer.

```rust
pub fn new(user: impl Into<String>) -> Self
```

--------------------------------

### Compile-Time Static String Constants

Source: https://github.com/lode-org/readcon-core/blob/main/_autodocs/configuration.md

Illustrates the use of static string slices for library constants, ensuring zero runtime cost. These include version information and metadata keys.

```rust
pub const CON_SPEC_VERSION: u32 = 2;
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

pub mod meta {
    pub const ENERGY: &str = "energy";
    pub const FRAME_INDEX: &str = "frame_index";
    // ... etc
}
```