ASDF-Pybind

C++ bindings for the Advanced Scientific Data Format (ASDF) using pybind11.

Overview

ASDF-Pybind provides C++ bindings to the Python implementation of the Advanced Scientific Data Format (ASDF). It allows C++ applications to read and write ASDF files by leveraging the robust Python implementation through pybind11.

The Advanced Scientific Data Format (ASDF) is a next-generation interchange format for scientific data, built on YAML for human-readable headers and binary data blocks for efficient storage of numerical arrays.

Features

• Read and write ASDF files from C++
• Access and modify ASDF tree structures
• Control array compression and storage options
• Schema validation
• History entry tracking
• Support for different ASDF standard versions

Requirements

• C++17-compatible compiler
• Python 3.7+
• pybind11
• ASDF Python package
• NumPy

Installation

Installing Dependencies

Before building ASDF-Pybind, install the required dependencies:

# Install Python dependencies
pip install pybind11 asdf numpy

# Install system dependencies (Ubuntu/Debian)
sudo apt-get install cmake build-essential

Building from Source

mkdir build
cd build
cmake ..
make

For building with examples:

mkdir build
cd build
cmake .. -DBUILD_EXAMPLES=ON
make

System Installation

To install ASDF-Pybind system-wide:

mkdir build
cd build
cmake ..
make
sudo make install

You can customize the installation directory using the CMAKE_INSTALL_PREFIX variable:

cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install

Versioning

ASDF-Pybind follows Semantic Versioning. The current version can be found in the CMakeLists.txt file.

Basic Usage

#include <iostream>
#include <string>
#include <map>
#include <asdf_wrapper.h>

// Initialize Python interpreter (required when embedding Python)
py::scoped_interpreter guard{};

// Create a new ASDF file with data
std::map<std::string, std::any> tree;
tree["foo"] = 42;
tree["bar"] = std::string("hello world");
tree["baz"] = 3.14159;

// Create AsdfFile object and write to file
AsdfFile asdf(tree);
asdf.write("example.asdf");

// Read from file
AsdfFile reader("example.asdf");
reader.info();  // Display file contents

// Modify and write to new file
reader.addHistoryEntry("Modified by C++ application", 
                       {{"name", "my-app"}, {"version", "1.0.0"}});
reader.write("modified.asdf");

See the examples directory for more detailed examples.

Integrating with C++ Projects

When using asdf-pybind in your C++ projects after installing via pip, you need to:

1. Include the header file: #include "asdf_wrapper.h" (found in the include/ directory)
2. Link against Python and pybind11

With CMake

cmake_minimum_required(VERSION 3.12)
project(my_asdf_project)

# Find Python and pybind11
find_package(Python COMPONENTS Interpreter Development REQUIRED)
find_package(pybind11 REQUIRED)
find_package(asdf_pybind REQUIRED)

# Create your executable
add_executable(my_program main.cpp)

# Link libraries
target_link_libraries(my_program PRIVATE
    asdf_pybind::asdf_pybind
    pybind11::embed
)

Documentation

The documentation for ASDF-Pybind is built using Sphinx and hosted on GitHub Pages:

• Latest Documentation
• Release Documentation

Building Documentation Locally

To build the documentation locally:

cd docs
pip install sphinx sphinx_rtd_theme
make html

The generated documentation will be available in docs/_build/html.

To build the documentation:

mkdir build
cd build
cmake .. -DBUILD_DOCS=ON
make docs

The generated documentation will be in build/docs/build/.

Testing

ASDF-Pybind uses C++ tests with Google Test framework to ensure the functionality of the library. To run the tests:

mkdir build
cd build
cmake .. -DBUILD_TESTING=ON
make
ctest

Or run the test executable directly:

./build/bin/test_asdf_wrapper

Note: While ASDF-Pybind uses Python libraries internally through pybind11, it is designed as a C++ library and all testing is done through C++ interfaces.

License

ASDF-Pybind is licensed under the MIT License. However, it binds to the ASDF Python package which is licensed under the BSD 3-Clause License. The LICENSE file contains both licenses for clarity.

When using this library, you must comply with both:

• The MIT License for the binding code
• The BSD 3-Clause License for the underlying ASDF library functionality

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests to ensure they pass
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Coding Standards

• Follow the existing code style
• Write tests for new features
• Update documentation as needed
• Update the CHANGELOG.md file

Releasing

For maintainers, to create a new release:

1. Update the version in CMakeLists.txt
2. Update CHANGELOG.md with the new version and release notes
3. Create a git tag for the version
4. Push the tag to GitHub
5. Create a GitHub release using the tag
   • This will automatically trigger the documentation build and deployment to GitHub Pages
   • Documentation will be available at https://davetbarr.github.io/asdf-pybind/vX.Y.Z/ where X.Y.Z is the version number

Acknowledgments

• The ASDF team for creating the Python implementation
• The pybind11 team for the excellent C++/Python binding library