API Reference - kirklasalle/SpaceEntropyCompression GitHub Wiki

SpaceEntropyCompression Core (libsec) API Reference

1. Core Header Architecture (sec/core.h)

The core C header defines fundamental types, status codes, configuration structures, and memory allocation interfaces required across all libsec modules.

#ifndef SEC_CORE_H
#define SEC_CORE_H

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Status / Result Codes */
typedef enum sec_status {
    SEC_SUCCESS              =  0,
    SEC_ERROR_INVALID_ARG    = -1,
    SEC_ERROR_OUT_OF_MEMORY  = -2,
    SEC_ERROR_BUFFER_OVERFLOW = -3,
    SEC_ERROR_CORRUPTED_DATA = -4,
    SEC_ERROR_NOT_SUPPORTED  = -5
} sec_status_t;

/* Core Compression Parameters */
typedef struct sec_config {
    uint32_t spatial_dimensions;
    double   error_bound;
    bool     enable_entropy_coding;
    size_t   block_size;
} sec_config_t;

/* Custom Memory Allocator Hooks */
typedef struct sec_allocator {
    void* (*custom_malloc)(size_t size);
    void  (*custom_free)(void* ptr);
    void* (*custom_realloc)(void* ptr, size_t new_size);
} sec_allocator_t;

/* Core Context Handle */
typedef struct sec_context sec_context_t;

/* Global Initialization & Versioning */
const char* sec_version(void);
sec_status_t sec_context_create(const sec_config_t* config, sec_context_t** ctx);
void sec_context_destroy(sec_context_t* ctx);

#ifdef __cplusplus
}
#endif

#endif /* SEC_CORE_H */

2. C++ Core Interfaces (sec/codec.hpp)

High-level C++ abstraction providing modern RAII interfaces, template-based stream wrappers, and exception-safe error handling for space entropy codecs.

#ifndef SEC_CODEC_HPP
#define SEC_CODEC_HPP

#include <vector>
#include <memory>
#include <string>
#include <span>
#include <stdexcept>
#include "sec/core.h"

namespace sec {

class Exception : public std::runtime_error {
public:
    explicit Exception(sec_status_t code) 
        : std::runtime_error("SEC Error Code: " + std::to_string(code)), code_(code) {}
    sec_status_t code() const noexcept { return code_; }
private:
    sec_status_t code_;
};

struct CodecConfig {
    uint32_t dimensions{3};
    double errorBound{1e-5};
    bool entropyCoding{true};
    size_t blockSize{1024};
};

class Codec {
public:
    explicit Codec(const CodecConfig& config = CodecConfig());
    ~Codec();

    Codec(const Codec&) = delete;
    Codec& operator=(const Codec&) = delete;
    Codec(Codec&&) noexcept;
    Codec& operator=(Codec&&) noexcept;

    [[nodiscard]] std::vector<uint8_t> compress(std::span<const double> input);
    [[nodiscard]] std::vector<double>  decompress(std::span<const uint8_t> compressedData);

    void compressStream(const double* input, size_t count, std::vector<uint8_t>& output);
    void decompressStream(const uint8_t* input, size_t count, std::vector<double>& output);

private:
    class Impl;
    std::unique_ptr<Impl> pimpl_;
};

} // namespace sec

#endif // SEC_CODEC_HPP

3. C ABI & FFI Bindings (sec_api.h)

Flat C API suitable for foreign function interface (FFI) integration with Python, Rust, Julia, and C# wrappers.

#ifndef SEC_API_H
#define SEC_API_H

#include "sec/core.h"

#ifdef __cplusplus
extern "C" {
#endif

#if defined(_WIN32) || defined(__CYGWIN__)
  #ifdef SEC_BUILD_DLL
    #define SEC_API __declspec(dllexport)
  #else
    #define SEC_API __declspec(dllimport)
  #endif
#else
  #define SEC_API __attribute__((visibility("default")))
#endif

/* Synchronous Compression Interface */
SEC_API sec_status_t sec_compress_buffer(
    const double* src,
    size_t src_count,
    uint8_t* dst,
    size_t* dst_capacity,
    const sec_config_t* config
);

/* Synchronous Decompression Interface */
SEC_API sec_status_t sec_decompress_buffer(
    const uint8_t* src,
    size_t src_size,
    double* dst,
    size_t* dst_capacity
);

/* Estimate Max Compressed Output Buffer Size */
SEC_API size_t sec_max_compressed_size(size_t src_count, const sec_config_t* config);

#ifdef __cplusplus
}
#endif

#endif /* SEC_API_H */

4. Test Fixtures & Verification Harness

Unit test architecture and synthetic dataset generation for verifying entropy bounds, floating-point precision loss, and stream compliance.

#include <gtest/gtest.h>
#include "sec/codec.hpp"
#include <cmath>
#include <random>

class SpaceEntropyTest : public ::testing::Test {
protected:
    void SetUp() override {
        config_.dimensions = 3;
        config_.errorBound = 1e-4;
        codec_ = std::make_unique<sec::Codec>(config_);
    }

    std::vector<double> generateSyntheticManifold(size_t n) {
        std::vector<double> data(n);
        std::mt19937 rng(42);
        std::uniform_real_distribution<double> dist(-100.0, 100.0);
        for (size_t i = 0; i < n; ++i) {
            data[i] = dist(rng);
        }
        return data;
    }

    sec::CodecConfig config_;
    std::unique_ptr<sec::Codec> codec_;
};

TEST_F(SpaceEntropyTest, RoundTripPrecisionCheck) {
    auto original = generateSyntheticManifold(10000);
    auto compressed = codec_->compress(original);
    auto decompressed = codec_->decompress(compressed);

    ASSERT_EQ(original.size(), decompressed.size());
    for (size_t i = 0; i < original.size(); ++i) {
        EXPECT_NEAR(original[i], decompressed[i], config_.errorBound);
    }
}

5. Implementation & Verification Checklist

  • Core Data Types & Memory Safety
    • Implement sec_allocator_t custom memory management override.
    • Verify non-overflow guarantees for sec_max_compressed_size.
  • Codec API Precision Controls
    • Support adaptive quantization step scaling under error_bound.
    • Implement multi-threaded spatial tiling dispatch.
  • FFI & Cross-Language Support
    • Validate C ABI alignment and packing across GCC, Clang, and MSVC.
    • Export dynamic symbol visibilities via SEC_API.
  • Verification & Benchmarking
    • Execute Google Test suite covering edge cases (NaN, Infinity, zero-variance inputs).
    • Validate entropy coder compression ratios against theoretical Shannon entropy limits.
⚠️ **GitHub.com Fallback** ⚠️