Introduction

open-bcif is a high-performance toolkit for BinaryCIF.

Why open-bcif?

The structural biology community is moving towards BinaryCIF for its superior compression and speed. However, tools for manipulating these files often require loading the entire structure into memory. open-bcif solves this with a streaming-first approach.

Quick Start

Get up and running with open-bcif in 5 minutes.

1. Installation

The easiest way to install is via cargo:

cargo install open-bcif

Alternatively, you can download pre-built binaries from the Releases page.

2. Basic Validation

Check if a BinaryCIF file is valid:

open-bcif validate structure.bcif

3. Extracting a Single Block

If you have a large file with multiple structures and only want the first one:

open-bcif split all_entries.bcif --output-dir ./parts
# This will create block_0_....bcif in the ./parts directory

4. Converting to Text CIF

Need to see the coordinates in a text editor?

open-bcif convert structure.bcif --output structure.cif --format cif

Architecture

open-bcif is built on several key layers:

  1. Streaming MessagePack Parser: Incremental reading of the BCIF hierarchy.
  2. Encoding Chain: A modular system for applying and reversing transformations like Delta, RunLength, and IntegerPacking.
  3. Command Layer: CLI subcommands that orchestrate the streaming engine.

Memory Management

By using a streaming approach, open-bcif maintains a constant memory overhead regardless of the input file size.

Key Design Principles

  • Hybrid Parsing: Uses a custom streaming MessagePack parser to traverse the BCIF hierarchy (DataBlock -> Category -> Column) incrementally.
  • Full Encoding Support: Supports all standard BCIF encodings, including ByteArray, Delta, RunLength, FixedPoint, IntegerPacking, IntervalQuantization, and StringArray.
  • Validation Engine: Parallelized validation using rayon for high-throughput integrity checks.
  • Robust Testing: Comprehensive test suite including unit tests with parameterized matrices (via rstest) and end-to-end integration tests.

BinaryCIF Specification

BinaryCIF is a binary serialization of CIF data using MessagePack.

Data Hierarchy

  • File: Root object.
  • DataBlock: A logical grouping (e.g., a single structure).
  • Category: A table of data (e.g., _atom_site).
  • Column: A single attribute with its associated data and encoding.

Supported Encodings

  • ByteArray
  • Delta
  • RunLength
  • FixedPoint
  • IntegerPacking
  • IntervalQuantization
  • StringArray

CLI Reference

validate

Validates a BCIF file.

open-bcif validate <INPUT>

split

Splits a BCIF file.

open-bcif split <INPUT> [--output-dir <DIR>]

merge

Merges BCIF files.

open-bcif merge <INPUTS>... --output <OUTPUT>

convert

Converts BCIF files.

open-bcif convert <INPUT> --output <OUTPUT> --format <FORMAT>