Entropyk/bindings/c/README.md

Entropyk C FFI Bindings

Auto-generated C bindings for the Entropyk thermodynamic simulation library.

Building

# Build the library (generates target/entropyk.h)
cargo build --release -p entropyk-c

# Output files:
# - target/release/libentropyk_ffi.a      (static library)
# - target/release/libentropyk_ffi.dylib  (macOS)
# - target/release/libentropyk_ffi.so     (Linux)
# - target/entropyk.h                     (C header)

Usage

#include "entropyk.h"
#include <stdint.h>

int main() {
    // Create a system
    EntropykSystem* sys = entropyk_system_create();
    
    // Create components
    double compressor_coeffs[10] = {0.85, 2.5, 500.0, 1500.0, -2.5, 1.8, 600.0, 1600.0, -3.0, 2.0};
    EntropykComponent* comp = entropyk_compressor_create(compressor_coeffs, 10);
    EntropykComponent* cond = entropyk_condenser_create(5000.0);
    EntropykComponent* valve = entropyk_expansion_valve_create();
    EntropykComponent* evap = entropyk_evaporator_create(3000.0);
    
    // Add components to system (returns node index, or UINT32_MAX on error)
    unsigned int comp_idx = entropyk_system_add_component(sys, comp);
    unsigned int cond_idx = entropyk_system_add_component(sys, cond);
    unsigned int valve_idx = entropyk_system_add_component(sys, valve);
    unsigned int evap_idx = entropyk_system_add_component(sys, evap);
    
    if (comp_idx == UINT32_MAX || cond_idx == UINT32_MAX || 
        valve_idx == UINT32_MAX || evap_idx == UINT32_MAX) {
        printf("Failed to add component\n");
        return 1;
    }
    
    // Connect components
    EntropykErrorCode err;
    err = entropyk_system_add_edge(sys, comp_idx, cond_idx);
    err = entropyk_system_add_edge(sys, cond_idx, valve_idx);
    err = entropyk_system_add_edge(sys, valve_idx, evap_idx);
    err = entropyk_system_add_edge(sys, evap_idx, comp_idx);
    
    // Finalize the system
    err = entropyk_system_finalize(sys);
    if (err != ENTROPYK_OK) {
        printf("Finalize error: %s\n", entropyk_error_string(err));
        return 1;
    }
    
    // Solve
    EntropykFallbackConfig config = {
        .newton = {100, 1e-6, false, 0},
        .picard = {500, 1e-4, 0.5}
    };
    
    EntropykSolverResult* result = NULL;
    err = entropyk_solve_fallback(sys, &config, &result);
    
    if (err == ENTROPYK_OK) {
        printf("Converged in %u iterations\n", entropyk_result_get_iterations(result));
        printf("Status: %d\n", entropyk_result_get_status(result));
    } else {
        printf("Solve error: %s\n", entropyk_error_string(err));
    }
    
    // Cleanup
    entropyk_result_free(result);
    entropyk_system_free(sys);
    
    return 0;
}

Memory Management

Ownership Rules

1. Create functions (entropyk_*_create) return ownership to caller
2. Add component transfers ownership to the system
3. Solve functions return ownership of result to caller
4. Free functions must be called on all owned pointers

Pairs

Create Function	Free Function
entropyk_system_create	entropyk_system_free
entropyk_compressor_create	entropyk_compressor_free
entropyk_condenser_create	entropyk_component_free
entropyk_evaporator_create	entropyk_component_free
entropyk_expansion_valve_create	entropyk_component_free
entropyk_economizer_create	entropyk_component_free
entropyk_pipe_create	entropyk_component_free
entropyk_solve_*	entropyk_result_free

Error Codes

Code	Description
OK	Success
NON_CONVERGENCE	Solver did not converge
TIMEOUT	Solver timed out
CONTROL_SATURATION	Control variable saturated
FLUID_ERROR	Fluid property error
INVALID_STATE	Invalid thermodynamic state
VALIDATION_ERROR	Validation failed
NULL_POINTER	Null pointer passed
INVALID_ARGUMENT	Invalid argument value
NOT_FINALIZED	System not finalized
TOPOLOGY_ERROR	Graph topology error
COMPONENT_ERROR	Component error

Thread Safety

• Each EntropykSystem* is independent and can be used from different threads
• The library is reentrant: concurrent calls with different systems are safe
• Do NOT share a single system across threads without synchronization

HIL Integration

The library is designed for HIL (Hardware-In-the-Loop) testing with:

• Latency target: < 20ms round-trip
• No dynamic allocation in solve hot path
• C99/C++ compatible headers

License

MIT OR Apache-2.0