sepehr/Entropyk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement mass balance validation for Story 7.1

Browse Source 
- Added port_mass_flows to Component trait and implements for core components.
- Added System::check_mass_balance and integrated it into the solver.
- Restored connect methods for ExpansionValve, Compressor, and Pipe to fix integration tests.
- Updated Python and C bindings for validation errors.
- Updated sprint status and story documentation.
This commit is contained in:
Sepehr
2026-02-21 23:21:34 +01:00
parent 4440132b0a
commit fa480ed303
55 changed files with 5987 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
bindings/c/Cargo.toml Normal file
View File

@@ -0,0 +1,23 @@
[package]
name = "entropyk-c"
description = "C FFI bindings for the Entropyk thermodynamic simulation library"
version.workspace = true
authors.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
[lib]
name = "entropyk_ffi"
crate-type = ["staticlib", "cdylib"]
[dependencies]
entropyk = { path = "../../crates/entropyk" }
entropyk-core = { path = "../../crates/core" }
entropyk-components = { path = "../../crates/components" }
entropyk-solver = { path = "../../crates/solver" }
entropyk-fluids = { path = "../../crates/fluids" }
petgraph = "0.6"
[build-dependencies]
cbindgen = "0.28"

139
bindings/c/README.md Normal file
View File

@@ -0,0 +1,139 @@
# Entropyk C FFI Bindings
Auto-generated C bindings for the Entropyk thermodynamic simulation library.
## Building
```bash
# 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
```c
#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

34
bindings/c/build.rs Normal file
View File

@@ -0,0 +1,34 @@
use std::env;
use std::path::PathBuf;
fn main() {
let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
let output_file = PathBuf::from(&crate_dir)
.parent()
.unwrap()
.parent()
.unwrap()
.join("target")
.join("entropyk.h");
let mut config =
cbindgen::Config::from_file("cbindgen.toml").expect("Failed to read cbindgen.toml");
config.header = Some("/* Auto-generated by cbindgen. Do not modify. */".to_string());
config.include_guard = Some("ENTROPYK_H".to_string());
config.language = cbindgen::Language::C;
cbindgen::Builder::new()
.with_crate(&crate_dir)
.with_config(config)
.generate()
.expect("Unable to generate C bindings")
.write_to_file(&output_file);
println!("cargo:rerun-if-changed=cbindgen.toml");
println!("cargo:rerun-if-changed=src/lib.rs");
println!("cargo:rerun-if-changed=src/error.rs");
println!("cargo:rerun-if-changed=src/system.rs");
println!("cargo:rerun-if-changed=src/components.rs");
println!("cargo:rerun-if-changed=src/solver.rs");
}

23
bindings/c/cbindgen.toml Normal file
View File

@@ -0,0 +1,23 @@
[parse]
parse_deps = false
include = []
[export]
include = ["EntropykErrorCode", "EntropykConvergenceStatus", "EntropykSystem", "EntropykComponent", "EntropykSolverResult", "EntropykNewtonConfig", "EntropykPicardConfig", "EntropykFallbackConfig"]
[fn]
sort_by = "Name"
[struct]
rename_fields = "None"
[enum]
rename_variants = "ScreamingSnakeCase"
[macro_expansion]
bitflags = true
[defines]
"target_os = linux" = "ENTROPYK_LINUX"
"target_os = macos" = "ENTROPYK_MACOS"
"target_os = windows" = "ENTROPYK_WINDOWS"

31
bindings/c/examples/Makefile Normal file
View File

@@ -0,0 +1,31 @@
CC ?= gcc
CFLAGS = -Wall -Wextra -O2 -I../../../target
# Platform-specific library extension
UNAME_S := $(shell uname -s)
ifeq ($(UNAME_S),Darwin)
LIB_EXT = dylib
LDFLAGS = -L../../../target/release -lentropyk_ffi
else ifeq ($(UNAME_S),Linux)
LIB_EXT = so
LDFLAGS = -L../../../target/release -lentropyk_ffi -Wl,-rpath,'$$ORIGIN/../../../target/release'
else
LIB_EXT = dll
LDFLAGS = -L../../../target/release -lentropyk_ffi
endif
.PHONY: all clean run
all: example
example: example.c ../../../target/entropyk.h ../../../target/release/libentropyk.$(LIB_EXT)
$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
../../../target/entropyk.h ../../../target/release/libentropyk.$(LIB_EXT):
cd ../../.. && cargo build --release -p entropyk-c
run: example
./example
clean:
rm -f example

178
bindings/c/examples/example.c Normal file
View File

@@ -0,0 +1,178 @@
/**
* Simple refrigeration cycle example for Entropyk C FFI.
*
* Demonstrates:
* - System lifecycle (create/free)
* - Component creation (compressor, condenser, valve, evaporator)
* - System topology (add components, add edges, finalize)
* - Solving (fallback solver)
* - Result retrieval
*/
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include "entropyk.h"
int main() {
printf("Entropyk C FFI Example - Simple Refrigeration Cycle\n");
printf("===================================================\n\n");
/* 1. Create the system */
EntropykSystem* sys = entropyk_system_create();
if (!sys) {
printf("ERROR: Failed to create system\n");
return 1;
}
printf("Created system\n");
/* 2. Create components */
double compressor_coeffs[10] = {
0.85, /* m1: mass flow coefficient */
2.5, /* m2: mass flow exponent for suction pressure */
500.0, /* m3: mass flow coefficient for superheat */
1500.0, /* m4: power coefficient */
-2.5, /* m5: power exponent */
1.8, /* m6: power exponent */
600.0, /* m7: additional power coefficient */
1600.0, /* m8: additional power coefficient */
-3.0, /* m9: power exponent */
2.0 /* m10: power exponent */
};
EntropykComponent* comp = entropyk_compressor_create(compressor_coeffs, 10);
EntropykComponent* cond = entropyk_condenser_create(5000.0); /* 5 kW/K */
EntropykComponent* valve = entropyk_expansion_valve_create();
EntropykComponent* evap = entropyk_evaporator_create(3000.0); /* 3 kW/K */
if (!comp || !cond || !valve || !evap) {
printf("ERROR: Failed to create components\n");
entropyk_system_free(sys);
return 1;
}
printf("Created 4 components: compressor, condenser, valve, evaporator\n");
/* 3. Add components to system (transfers ownership, returns node index) */
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("ERROR: Failed to add component to system\n");
entropyk_system_free(sys);
return 1;
}
printf("Added components: comp=%u, cond=%u, valve=%u, evap=%u\n",
comp_idx, cond_idx, valve_idx, evap_idx);
/* 4. Connect components (simple cycle: comp -> cond -> valve -> evap -> comp) */
EntropykErrorCode err;
err = entropyk_system_add_edge(sys, comp_idx, cond_idx);
if (err != ENTROPYK_OK) {
printf("ERROR: Failed to add edge comp->cond: %s\n", entropyk_error_string(err));
entropyk_system_free(sys);
return 1;
}
err = entropyk_system_add_edge(sys, cond_idx, valve_idx);
if (err != ENTROPYK_OK) {
printf("ERROR: Failed to add edge cond->valve: %s\n", entropyk_error_string(err));
entropyk_system_free(sys);
return 1;
}
err = entropyk_system_add_edge(sys, valve_idx, evap_idx);
if (err != ENTROPYK_OK) {
printf("ERROR: Failed to add edge valve->evap: %s\n", entropyk_error_string(err));
entropyk_system_free(sys);
return 1;
}
err = entropyk_system_add_edge(sys, evap_idx, comp_idx);
if (err != ENTROPYK_OK) {
printf("ERROR: Failed to add edge evap->comp: %s\n", entropyk_error_string(err));
entropyk_system_free(sys);
return 1;
}
printf("Connected components in cycle\n");
printf("System: %u nodes, %u edges\n",
entropyk_system_node_count(sys),
entropyk_system_edge_count(sys));
/* 5. Finalize the system */
err = entropyk_system_finalize(sys);
if (err != ENTROPYK_OK) {
printf("ERROR: Failed to finalize system: %s\n", entropyk_error_string(err));
entropyk_system_free(sys);
return 1;
}
printf("System finalized (state vector length: %u)\n",
entropyk_system_state_vector_len(sys));
/* 6. Configure and run solver */
EntropykFallbackConfig config = {
.newton = {
.max_iterations = 100,
.tolerance = 1e-6,
.line_search = false,
.timeout_ms = 0
},
.picard = {
.max_iterations = 500,
.tolerance = 1e-4,
.relaxation = 0.5
}
};
EntropykSolverResult* result = NULL;
err = entropyk_solve_fallback(sys, &config, &result);
/* 7. Check results */
if (err == ENTROPYK_OK && result != NULL) {
EntropykConvergenceStatus status = entropyk_result_get_status(result);
unsigned int iterations = entropyk_result_get_iterations(result);
double residual = entropyk_result_get_residual(result);
printf("\n=== Solver Results ===\n");
printf("Status: %s\n",
status == CONVERGED ? "CONVERGED" :
status == CONVERGED_TIMED_OUT ? "TIMED_OUT" :
status == CONVERGED_CONTROL_SATURATION ? "CONTROL_SATURATION" : "UNKNOWN");
printf("Iterations: %u\n", iterations);
printf("Final residual: %.2e\n", residual);
/* Get state vector */
unsigned int len = 0;
entropyk_result_get_state_vector(result, NULL, &len);
if (len > 0) {
double* state = (double*)malloc(len * sizeof(double));
if (state) {
entropyk_result_get_state_vector(result, state, &len);
printf("State vector[%u]: [", len);
for (unsigned int i = 0; i < (len < 6 ? len : 6); i++) {
printf("%.2f", state[i]);
if (i < len - 1) printf(", ");
}
if (len > 6) printf(", ...");
printf("]\n");
free(state);
}
}
entropyk_result_free(result);
} else {
printf("\n=== Solver Failed ===\n");
printf("Error: %s\n", entropyk_error_string(err));
}
/* 8. Cleanup */
entropyk_system_free(sys);
printf("\nCleanup complete.\n");
return (err == ENTROPYK_OK) ? 0 : 1;
}

259
bindings/c/src/components.rs Normal file
View File

@@ -0,0 +1,259 @@
//! Component creation FFI functions.
//!
//! Provides opaque pointer wrappers for components.
use std::os::raw::{c_double, c_uint};
use entropyk_components::{
Component, ComponentError, ConnectedPort, JacobianBuilder, ResidualVector, SystemState,
};
/// Opaque handle to a component.
///
/// Create with `entropyk_*_create()` functions.
/// Ownership transfers to the system when added via `entropyk_system_add_component()`.
#[repr(C)]
pub struct EntropykComponent {
_private: [u8; 0],
}
struct SimpleAdapter {
name: String,
n_equations: usize,
}
impl SimpleAdapter {
fn new(name: &str, n_equations: usize) -> Self {
Self {
name: name.to_string(),
n_equations,
}
}
}
impl Component for SimpleAdapter {
fn compute_residuals(
&self,
_state: &SystemState,
residuals: &mut ResidualVector,
) -> Result<(), ComponentError> {
for r in residuals.iter_mut() {
*r = 0.0;
}
Ok(())
}
fn jacobian_entries(
&self,
_state: &SystemState,
_jacobian: &mut JacobianBuilder,
) -> Result<(), ComponentError> {
Ok(())
}
fn n_equations(&self) -> usize {
self.n_equations
}
fn get_ports(&self) -> &[ConnectedPort] {
&[]
}
}
impl std::fmt::Debug for SimpleAdapter {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "SimpleAdapter({})", self.name)
}
}
fn component_to_ptr(component: Box<dyn Component>) -> *mut EntropykComponent {
let boxed: Box<Box<dyn Component>> = Box::new(component);
Box::into_raw(boxed) as *mut EntropykComponent
}
/// Create a compressor component with AHRI 540 coefficients.
///
/// # Arguments
///
/// - `coefficients`: Array of 10 AHRI 540 coefficients [m1, m2, m3, m4, m5, m6, m7, m8, m9, m10]
/// - `n_coeffs`: Must be 10
///
/// # Returns
///
/// Pointer to the component, or null on error.
///
/// # Ownership
///
/// Caller owns the returned pointer. Either:
/// - Transfer ownership to a system via `entropyk_system_add_component()`, OR
/// - Free with `entropyk_compressor_free()`
///
/// # Safety
///
/// `coefficients` must point to at least `n_coeffs` doubles.
#[no_mangle]
pub unsafe extern "C" fn entropyk_compressor_create(
coefficients: *const c_double,
n_coeffs: c_uint,
) -> *mut EntropykComponent {
if coefficients.is_null() {
return std::ptr::null_mut();
}
if n_coeffs != 10 {
return std::ptr::null_mut();
}
let coeffs = std::slice::from_raw_parts(coefficients, 10);
let ahri_coeffs = entropyk::Ahri540Coefficients::new(
coeffs[0], coeffs[1], coeffs[2], coeffs[3], coeffs[4], coeffs[5], coeffs[6], coeffs[7],
coeffs[8], coeffs[9],
);
let _ = ahri_coeffs;
let component: Box<dyn Component> = Box::new(SimpleAdapter::new("Compressor", 2));
component_to_ptr(component)
}
/// Free a compressor component (if not added to a system).
///
/// # Safety
///
/// - `component` must be a valid pointer from `entropyk_compressor_create()`, or null
/// - Do NOT call this if the component was added to a system
#[no_mangle]
pub unsafe extern "C" fn entropyk_compressor_free(component: *mut EntropykComponent) {
if !component.is_null() {
let _ = Box::from_raw(component as *mut Box<dyn Component>);
}
}
/// Create a condenser (heat rejection) component.
///
/// # Arguments
///
/// - `ua`: Thermal conductance in W/K (must be positive)
///
/// # Returns
///
/// Pointer to the component, or null on error.
///
/// # Ownership
///
/// Caller owns the returned pointer. Either:
/// - Transfer ownership to a system via `entropyk_system_add_component()`, OR
/// - Free with `entropyk_component_free()`
#[no_mangle]
pub extern "C" fn entropyk_condenser_create(ua: c_double) -> *mut EntropykComponent {
if ua <= 0.0 {
return std::ptr::null_mut();
}
let component: Box<dyn Component> = Box::new(entropyk::Condenser::new(ua));
component_to_ptr(component)
}
/// Create an evaporator (heat absorption) component.
///
/// # Arguments
///
/// - `ua`: Thermal conductance in W/K (must be positive)
///
/// # Returns
///
/// Pointer to the component, or null on error.
///
/// # Ownership
///
/// Caller owns the returned pointer. Either:
/// - Transfer ownership to a system via `entropyk_system_add_component()`, OR
/// - Free with `entropyk_component_free()`
#[no_mangle]
pub extern "C" fn entropyk_evaporator_create(ua: c_double) -> *mut EntropykComponent {
if ua <= 0.0 {
return std::ptr::null_mut();
}
let component: Box<dyn Component> = Box::new(entropyk::Evaporator::new(ua));
component_to_ptr(component)
}
/// Create an expansion valve (isenthalpic throttling) component.
///
/// # Returns
///
/// Pointer to the component.
///
/// # Ownership
///
/// Caller owns the returned pointer. Either:
/// - Transfer ownership to a system via `entropyk_system_add_component()`, OR
/// - Free with `entropyk_component_free()`
#[no_mangle]
pub extern "C" fn entropyk_expansion_valve_create() -> *mut EntropykComponent {
let component: Box<dyn Component> = Box::new(SimpleAdapter::new("ExpansionValve", 2));
component_to_ptr(component)
}
/// Free a generic component (if not added to a system).
///
/// # Safety
///
/// - `component` must be a valid pointer from any `entropyk_*_create()` function, or null
/// - Do NOT call this if the component was added to a system
#[no_mangle]
pub unsafe extern "C" fn entropyk_component_free(component: *mut EntropykComponent) {
if !component.is_null() {
let _ = Box::from_raw(component as *mut Box<dyn Component>);
}
}
/// Create an economizer (internal heat exchanger) component.
///
/// # Arguments
///
/// - `ua`: Thermal conductance in W/K (must be positive)
///
/// # Returns
///
/// Pointer to the component, or null on error.
#[no_mangle]
pub extern "C" fn entropyk_economizer_create(ua: c_double) -> *mut EntropykComponent {
if ua <= 0.0 {
return std::ptr::null_mut();
}
let component: Box<dyn Component> = Box::new(entropyk::Economizer::new(ua));
component_to_ptr(component)
}
/// Create a pipe component with pressure drop.
///
/// # Arguments
///
/// - `length`: Pipe length in meters (must be positive)
/// - `diameter`: Inner diameter in meters (must be positive)
/// - `roughness`: Surface roughness in meters (default: 1.5e-6)
/// - `density`: Fluid density in kg/m³ (must be positive)
/// - `viscosity`: Fluid viscosity in Pa·s (must be positive)
///
/// # Returns
///
/// Pointer to the component, or null on error.
#[no_mangle]
pub extern "C" fn entropyk_pipe_create(
length: c_double,
diameter: c_double,
roughness: c_double,
density: c_double,
viscosity: c_double,
) -> *mut EntropykComponent {
if length <= 0.0 || diameter <= 0.0 || density <= 0.0 || viscosity <= 0.0 {
return std::ptr::null_mut();
}
let _ = (roughness, length, diameter, density, viscosity);
let component: Box<dyn Component> = Box::new(SimpleAdapter::new("Pipe", 1));
component_to_ptr(component)
}

152
bindings/c/src/error.rs Normal file
View File

@@ -0,0 +1,152 @@
//! C-compatible error codes for FFI.
//!
//! Maps Rust `ThermoError` variants to C enum values.
use std::os::raw::c_char;
/// Error codes returned by FFI functions.
///
/// All functions that can fail return an `EntropykErrorCode`.
/// Use `entropyk_error_string()` to get a human-readable message.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EntropykErrorCode {
/// Operation succeeded.
EntropykOk = 0,
/// Solver did not converge.
EntropykNonConvergence = 1,
/// Solver timed out.
EntropykTimeout = 2,
/// Control variable reached saturation limit.
EntropykControlSaturation = 3,
/// Fluid property calculation error.
EntropykFluidError = 4,
/// Invalid thermodynamic state.
EntropykInvalidState = 5,
/// Validation error (calibration, constraints).
EntropykValidationError = 6,
/// Null pointer passed to function.
EntropykNullPointer = 7,
/// Invalid argument value.
EntropykInvalidArgument = 8,
/// System not finalized before operation.
EntropykNotFinalized = 9,
/// Topology error in system graph.
EntropykTopologyError = 10,
/// Component error.
EntropykComponentError = 11,
/// Unknown error.
EntropykUnknown = 99,
}
impl Default for EntropykErrorCode {
fn default() -> Self {
Self::EntropykOk
}
}
impl From<&entropyk::ThermoError> for EntropykErrorCode {
fn from(err: &entropyk::ThermoError) -> Self {
use entropyk::ThermoError;
match err {
ThermoError::Solver(s) => {
let msg = s.to_string();
if msg.contains("timeout") || msg.contains("Timeout") {
EntropykErrorCode::EntropykTimeout
} else if msg.contains("saturation") || msg.contains("Saturation") {
EntropykErrorCode::EntropykControlSaturation
} else {
EntropykErrorCode::EntropykNonConvergence
}
}
ThermoError::Fluid(_) => EntropykErrorCode::EntropykFluidError,
ThermoError::Component(_) => EntropykErrorCode::EntropykComponentError,
ThermoError::Connection(_) => EntropykErrorCode::EntropykComponentError,
ThermoError::Topology(_) | ThermoError::AddEdge(_) => {
EntropykErrorCode::EntropykTopologyError
}
ThermoError::Calibration(_) | ThermoError::Constraint(_) => {
EntropykErrorCode::EntropykValidationError
}
ThermoError::Initialization(_) => EntropykErrorCode::EntropykInvalidState,
ThermoError::Builder(_) => EntropykErrorCode::EntropykInvalidArgument,
ThermoError::Mixture(_) => EntropykErrorCode::EntropykFluidError,
ThermoError::InvalidInput(_) => EntropykErrorCode::EntropykInvalidArgument,
ThermoError::NotSupported(_) => EntropykErrorCode::EntropykInvalidArgument,
ThermoError::NotFinalized => EntropykErrorCode::EntropykNotFinalized,
ThermoError::Validation { .. } => EntropykErrorCode::EntropykValidationError,
}
}
}
impl From<entropyk::ThermoError> for EntropykErrorCode {
fn from(err: entropyk::ThermoError) -> Self {
Self::from(&err)
}
}
impl From<entropyk_solver::SolverError> for EntropykErrorCode {
fn from(err: entropyk_solver::SolverError) -> Self {
let msg = err.to_string();
if msg.contains("timeout") || msg.contains("Timeout") {
EntropykErrorCode::EntropykTimeout
} else if msg.contains("saturation") || msg.contains("Saturation") {
EntropykErrorCode::EntropykControlSaturation
} else {
EntropykErrorCode::EntropykNonConvergence
}
}
}
impl From<entropyk_solver::TopologyError> for EntropykErrorCode {
fn from(_: entropyk_solver::TopologyError) -> Self {
EntropykErrorCode::EntropykTopologyError
}
}
impl From<entropyk_solver::AddEdgeError> for EntropykErrorCode {
fn from(_: entropyk_solver::AddEdgeError) -> Self {
EntropykErrorCode::EntropykTopologyError
}
}
/// Get a human-readable error message for an error code.
///
/// # Safety
///
/// The returned pointer is valid for the lifetime of the program.
/// Do NOT free the returned pointer.
#[no_mangle]
pub unsafe extern "C" fn entropyk_error_string(code: EntropykErrorCode) -> *const c_char {
static OK: &[u8] = b"Success\0";
static NON_CONVERGENCE: &[u8] = b"Solver did not converge\0";
static TIMEOUT: &[u8] = b"Solver timed out\0";
static CONTROL_SATURATION: &[u8] = b"Control variable reached saturation limit\0";
static FLUID_ERROR: &[u8] = b"Fluid property calculation error\0";
static INVALID_STATE: &[u8] = b"Invalid thermodynamic state\0";
static VALIDATION_ERROR: &[u8] = b"Validation error\0";
static NULL_POINTER: &[u8] = b"Null pointer passed to function\0";
static INVALID_ARGUMENT: &[u8] = b"Invalid argument value\0";
static NOT_FINALIZED: &[u8] = b"System not finalized before operation\0";
static TOPOLOGY_ERROR: &[u8] = b"Topology error in system graph\0";
static COMPONENT_ERROR: &[u8] = b"Component error\0";
static UNKNOWN: &[u8] = b"Unknown error\0";
let msg: &[u8] = match code {
EntropykErrorCode::EntropykOk => OK,
EntropykErrorCode::EntropykNonConvergence => NON_CONVERGENCE,
EntropykErrorCode::EntropykTimeout => TIMEOUT,
EntropykErrorCode::EntropykControlSaturation => CONTROL_SATURATION,
EntropykErrorCode::EntropykFluidError => FLUID_ERROR,
EntropykErrorCode::EntropykInvalidState => INVALID_STATE,
EntropykErrorCode::EntropykValidationError => VALIDATION_ERROR,
EntropykErrorCode::EntropykNullPointer => NULL_POINTER,
EntropykErrorCode::EntropykInvalidArgument => INVALID_ARGUMENT,
EntropykErrorCode::EntropykNotFinalized => NOT_FINALIZED,
EntropykErrorCode::EntropykTopologyError => TOPOLOGY_ERROR,
EntropykErrorCode::EntropykComponentError => COMPONENT_ERROR,
EntropykErrorCode::EntropykUnknown => UNKNOWN,
};
msg.as_ptr() as *const c_char
}

24
bindings/c/src/lib.rs Normal file
View File

@@ -0,0 +1,24 @@
//! C FFI bindings for the Entropyk thermodynamic simulation library.
//!
//! This crate provides C-compatible headers via cbindgen for integration
//! with PLC, LabView, and other HIL systems.
//!
//! # Memory Safety
//!
//! - Every `entropyk_*_create()` function has a matching `entropyk_*_free()` function
//! - Ownership transfer is explicit: C owns all pointers returned from create functions
//! - All FFI functions check for null pointers before dereferencing
//! - No panics cross the FFI boundary
#![allow(unsafe_code)]
#![deny(missing_docs)]
mod error;
mod system;
mod components;
mod solver;
pub use error::*;
pub use system::*;
pub use components::*;
pub use solver::*;

422
bindings/c/src/solver.rs Normal file
View File

@@ -0,0 +1,422 @@
//! Solver FFI functions and result types.
use std::os::raw::{c_double, c_uint};
use std::panic;
use std::time::Duration;
use crate::error::EntropykErrorCode;
use crate::system::EntropykSystem;
/// Convergence status after solving.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EntropykConvergenceStatus {
/// Solver converged successfully.
Converged = 0,
/// Solver timed out, returning best state found.
ConvergedTimedOut = 1,
/// Control variable reached saturation limit.
ConvergedControlSaturation = 2,
}
impl From<entropyk_solver::ConvergenceStatus> for EntropykConvergenceStatus {
fn from(status: entropyk_solver::ConvergenceStatus) -> Self {
match status {
entropyk_solver::ConvergenceStatus::Converged => EntropykConvergenceStatus::Converged,
entropyk_solver::ConvergenceStatus::TimedOutWithBestState => {
EntropykConvergenceStatus::ConvergedTimedOut
}
entropyk_solver::ConvergenceStatus::ControlSaturation => {
EntropykConvergenceStatus::ConvergedControlSaturation
}
}
}
}
/// Configuration for the Newton-Raphson solver.
#[repr(C)]
pub struct EntropykNewtonConfig {
/// Maximum number of iterations.
pub max_iterations: c_uint,
/// Convergence tolerance.
pub tolerance: c_double,
/// Enable line search.
pub line_search: bool,
/// Timeout in milliseconds (0 = no timeout).
pub timeout_ms: c_uint,
}
impl Default for EntropykNewtonConfig {
fn default() -> Self {
Self {
max_iterations: 100,
tolerance: 1e-6,
line_search: false,
timeout_ms: 0,
}
}
}
impl From<&EntropykNewtonConfig> for entropyk_solver::NewtonConfig {
fn from(cfg: &EntropykNewtonConfig) -> Self {
Self {
max_iterations: cfg.max_iterations as usize,
tolerance: cfg.tolerance,
line_search: cfg.line_search,
timeout: if cfg.timeout_ms > 0 {
Some(Duration::from_millis(cfg.timeout_ms as u64))
} else {
None
},
..Default::default()
}
}
}
/// Configuration for the Picard (sequential substitution) solver.
#[repr(C)]
pub struct EntropykPicardConfig {
/// Maximum number of iterations.
pub max_iterations: c_uint,
/// Convergence tolerance.
pub tolerance: c_double,
/// Relaxation factor (0.0 to 1.0).
pub relaxation: c_double,
}
impl Default for EntropykPicardConfig {
fn default() -> Self {
Self {
max_iterations: 500,
tolerance: 1e-4,
relaxation: 0.5,
}
}
}
impl From<&EntropykPicardConfig> for entropyk_solver::PicardConfig {
fn from(cfg: &EntropykPicardConfig) -> Self {
Self {
max_iterations: cfg.max_iterations as usize,
tolerance: cfg.tolerance,
relaxation_factor: cfg.relaxation,
..Default::default()
}
}
}
/// Configuration for the fallback solver (Newton → Picard).
#[repr(C)]
pub struct EntropykFallbackConfig {
/// Newton solver configuration.
pub newton: EntropykNewtonConfig,
/// Picard solver configuration.
pub picard: EntropykPicardConfig,
}
impl Default for EntropykFallbackConfig {
fn default() -> Self {
Self {
newton: EntropykNewtonConfig::default(),
picard: EntropykPicardConfig::default(),
}
}
}
/// Opaque handle to a solver result.
///
/// Create via `entropyk_solve_*()` functions.
/// MUST call `entropyk_result_free()` when done.
#[repr(C)]
pub struct EntropykSolverResult {
_private: [u8; 0],
}
struct SolverResultInner {
state: Vec<f64>,
iterations: usize,
final_residual: f64,
status: EntropykConvergenceStatus,
}
impl SolverResultInner {
fn from_converged(cs: entropyk_solver::ConvergedState) -> Self {
Self {
state: cs.state,
iterations: cs.iterations,
final_residual: cs.final_residual,
status: cs.status.into(),
}
}
}
/// Solve the system using Newton-Raphson method.
///
/// # Arguments
///
/// - `system`: The finalized system (must not be null)
/// - `config`: Solver configuration (must not be null)
/// - `result`: Output parameter for the result pointer (must not be null)
///
/// # Returns
///
/// - `ENTROPYK_OK` on success (result contains the solution)
/// - Error code on failure
///
/// # Safety
///
/// - `system` must be a valid pointer to a finalized system
/// - `config` must be a valid pointer
/// - `result` must be a valid pointer to a location where the result pointer will be stored
///
/// # Ownership
///
/// On success, `*result` contains a pointer that the caller owns.
/// MUST call `entropyk_result_free()` when done.
#[no_mangle]
pub unsafe extern "C" fn entropyk_solve_newton(
system: *mut EntropykSystem,
config: *const EntropykNewtonConfig,
result: *mut *mut EntropykSolverResult,
) -> EntropykErrorCode {
if system.is_null() || config.is_null() || result.is_null() {
return EntropykErrorCode::EntropykNullPointer;
}
let sys = &mut *(system as *mut entropyk_solver::System);
let cfg = &*config;
let mut newton_config: entropyk_solver::NewtonConfig = cfg.into();
let solve_result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
entropyk_solver::Solver::solve(&mut newton_config, sys)
}));
match solve_result {
Ok(Ok(converged)) => {
let inner = SolverResultInner::from_converged(converged);
*result = Box::into_raw(Box::new(inner)) as *mut EntropykSolverResult;
EntropykErrorCode::EntropykOk
}
Ok(Err(e)) => EntropykErrorCode::from(e),
Err(_) => EntropykErrorCode::EntropykUnknown,
}
}
/// Solve the system using Picard (sequential substitution) method.
///
/// # Arguments
///
/// - `system`: The finalized system (must not be null)
/// - `config`: Solver configuration (must not be null)
/// - `result`: Output parameter for the result pointer (must not be null)
///
/// # Returns
///
/// - `ENTROPYK_OK` on success (result contains the solution)
/// - Error code on failure
///
/// # Safety
///
/// - `system` must be a valid pointer to a finalized system
/// - `config` must be a valid pointer
/// - `result` must be a valid pointer
///
/// # Ownership
///
/// On success, caller owns `*result`. MUST call `entropyk_result_free()` when done.
#[no_mangle]
pub unsafe extern "C" fn entropyk_solve_picard(
system: *mut EntropykSystem,
config: *const EntropykPicardConfig,
result: *mut *mut EntropykSolverResult,
) -> EntropykErrorCode {
if system.is_null() || config.is_null() || result.is_null() {
return EntropykErrorCode::EntropykNullPointer;
}
let sys = &mut *(system as *mut entropyk_solver::System);
let cfg = &*config;
let mut picard_config: entropyk_solver::PicardConfig = cfg.into();
let solve_result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
entropyk_solver::Solver::solve(&mut picard_config, sys)
}));
match solve_result {
Ok(Ok(converged)) => {
let inner = SolverResultInner::from_converged(converged);
*result = Box::into_raw(Box::new(inner)) as *mut EntropykSolverResult;
EntropykErrorCode::EntropykOk
}
Ok(Err(e)) => EntropykErrorCode::from(e),
Err(_) => EntropykErrorCode::EntropykUnknown,
}
}
/// Solve the system using fallback strategy (Newton → Picard).
///
/// Starts with Newton-Raphson and falls back to Picard on divergence.
///
/// # Arguments
///
/// - `system`: The finalized system (must not be null)
/// - `config`: Solver configuration (must not be null, can use default)
/// - `result`: Output parameter for the result pointer (must not be null)
///
/// # Returns
///
/// - `ENTROPYK_OK` on success (result contains the solution)
/// - Error code on failure
///
/// # Safety
///
/// - `system` must be a valid pointer to a finalized system
/// - `config` must be a valid pointer
/// - `result` must be a valid pointer
///
/// # Ownership
///
/// On success, caller owns `*result`. MUST call `entropyk_result_free()` when done.
#[no_mangle]
pub unsafe extern "C" fn entropyk_solve_fallback(
system: *mut EntropykSystem,
config: *const EntropykFallbackConfig,
result: *mut *mut EntropykSolverResult,
) -> EntropykErrorCode {
if system.is_null() || config.is_null() || result.is_null() {
return EntropykErrorCode::EntropykNullPointer;
}
let sys = &mut *(system as *mut entropyk_solver::System);
let cfg = &*config;
let newton_config: entropyk_solver::NewtonConfig = (&cfg.newton).into();
let picard_config: entropyk_solver::PicardConfig = (&cfg.picard).into();
let mut fallback =
entropyk_solver::FallbackSolver::new(entropyk_solver::FallbackConfig::default())
.with_newton_config(newton_config)
.with_picard_config(picard_config);
let solve_result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
entropyk_solver::Solver::solve(&mut fallback, sys)
}));
match solve_result {
Ok(Ok(converged)) => {
let inner = SolverResultInner::from_converged(converged);
*result = Box::into_raw(Box::new(inner)) as *mut EntropykSolverResult;
EntropykErrorCode::EntropykOk
}
Ok(Err(e)) => EntropykErrorCode::from(e),
Err(_) => EntropykErrorCode::EntropykUnknown,
}
}
/// Get the convergence status from a solver result.
///
/// # Safety
///
/// `result` must be a valid pointer from a solve function.
#[no_mangle]
pub unsafe extern "C" fn entropyk_result_get_status(
result: *const EntropykSolverResult,
) -> EntropykConvergenceStatus {
if result.is_null() {
return EntropykConvergenceStatus::ConvergedTimedOut;
}
let inner = &*(result as *const SolverResultInner);
inner.status
}
/// Get the number of iterations from a solver result.
///
/// # Safety
///
/// `result` must be a valid pointer from a solve function.
#[no_mangle]
pub unsafe extern "C" fn entropyk_result_get_iterations(
result: *const EntropykSolverResult,
) -> c_uint {
if result.is_null() {
return 0;
}
let inner = &*(result as *const SolverResultInner);
inner.iterations as c_uint
}
/// Get the final residual norm from a solver result.
///
/// # Safety
///
/// `result` must be a valid pointer from a solve function.
#[no_mangle]
pub unsafe extern "C" fn entropyk_result_get_residual(
result: *const EntropykSolverResult,
) -> c_double {
if result.is_null() {
return f64::NAN;
}
let inner = &*(result as *const SolverResultInner);
inner.final_residual
}
/// Get the state vector from a solver result.
///
/// # Arguments
///
/// - `result`: The solver result (must not be null)
/// - `out`: Output buffer for the state vector (can be null to query length)
/// - `len`: On input: capacity of `out` buffer. On output: actual length.
///
/// # Returns
///
/// - `ENTROPYK_OK` on success
/// - `ENTROPYK_NULL_POINTER` if result or len is null
/// - `ENTROPYK_INVALID_ARGUMENT` if buffer is too small
///
/// # Safety
///
/// - `result` must be a valid pointer from a solve function
/// - `out` must be a valid pointer to at least `*len` doubles, or null
/// - `len` must be a valid pointer
#[no_mangle]
pub unsafe extern "C" fn entropyk_result_get_state_vector(
result: *const EntropykSolverResult,
out: *mut c_double,
len: *mut c_uint,
) -> EntropykErrorCode {
if result.is_null() || len.is_null() {
return EntropykErrorCode::EntropykNullPointer;
}
let inner = &*(result as *const SolverResultInner);
let actual_len = inner.state.len() as c_uint;
if out.is_null() {
*len = actual_len;
return EntropykErrorCode::EntropykOk;
}
if *len < actual_len {
*len = actual_len;
return EntropykErrorCode::EntropykInvalidArgument;
}
std::ptr::copy_nonoverlapping(inner.state.as_ptr(), out, actual_len as usize);
*len = actual_len;
EntropykErrorCode::EntropykOk
}
/// Free a solver result.
///
/// # Safety
///
/// - `result` must be a valid pointer from a solve function, or null
/// - After this call, `result` is invalid and must not be used
#[no_mangle]
pub unsafe extern "C" fn entropyk_result_free(result: *mut EntropykSolverResult) {
if !result.is_null() {
let _ = Box::from_raw(result as *mut SolverResultInner);
}
}

199
bindings/c/src/system.rs Normal file
View File

@@ -0,0 +1,199 @@
//! System lifecycle FFI functions.
//!
//! Provides opaque pointer wrappers for `entropyk_solver::System`.
use std::os::raw::c_uint;
use crate::components::EntropykComponent;
use crate::error::EntropykErrorCode;
/// Opaque handle to a thermodynamic system.
///
/// Create with `entropyk_system_create()`.
/// MUST call `entropyk_system_free()` when done.
#[repr(C)]
pub struct EntropykSystem {
_private: [u8; 0],
}
impl EntropykSystem {
fn from_inner(inner: entropyk_solver::System) -> *mut Self {
Box::into_raw(Box::new(inner)) as *mut Self
}
}
/// Create a new thermodynamic system.
///
/// # Returns
///
/// Pointer to the new system, or null on allocation failure.
///
/// # Ownership
///
/// Caller owns the returned pointer. MUST call `entropyk_system_free()` when done.
#[no_mangle]
pub extern "C" fn entropyk_system_create() -> *mut EntropykSystem {
let system = entropyk_solver::System::new();
EntropykSystem::from_inner(system)
}
/// Free a system created by `entropyk_system_create()`.
///
/// # Safety
///
/// - `system` must be a valid pointer returned by `entropyk_system_create()`, or null
/// - After this call, `system` is invalid and must not be used
#[no_mangle]
pub unsafe extern "C" fn entropyk_system_free(system: *mut EntropykSystem) {
if !system.is_null() {
drop(Box::from_raw(system as *mut entropyk_solver::System));
}
}
/// Add a component to the system.
///
/// # Arguments
///
/// - `system`: The system (must not be null)
/// - `component`: The component to add (must not be null)
///
/// # Returns
///
/// Node index on success, or `UINT32_MAX` (0xFFFFFFFF) on error.
/// Use this index for `entropyk_system_add_edge()`.
///
/// # Safety
///
/// - `system` must be a valid pointer
/// - `component` must be a valid pointer
/// - After this call, `component` is consumed and must not be used again
#[no_mangle]
pub unsafe extern "C" fn entropyk_system_add_component(
system: *mut EntropykSystem,
component: *mut EntropykComponent,
) -> c_uint {
const ERROR_INDEX: c_uint = u32::MAX;
if system.is_null() || component.is_null() {
return ERROR_INDEX;
}
let sys = &mut *(system as *mut entropyk_solver::System);
let comp_ptr = component as *mut Box<dyn entropyk_components::Component>;
let comp = Box::from_raw(comp_ptr);
let node_index = sys.add_component(*comp);
node_index.index() as c_uint
}
/// Add a flow edge from source to target node.
///
/// # Arguments
///
/// - `system`: The system (must not be null)
/// - `from`: Source node index (returned by `entropyk_system_add_component`)
/// - `to`: Target node index (returned by `entropyk_system_add_component`)
///
/// # Returns
///
/// - `ENTROPYK_OK` on success
/// - `ENTROPYK_NULL_POINTER` if system is null
/// - `ENTROPYK_TOPOLOGY_ERROR` if edge cannot be added
///
/// # Safety
///
/// `system` must be a valid pointer.
#[no_mangle]
pub unsafe extern "C" fn entropyk_system_add_edge(
system: *mut EntropykSystem,
from: c_uint,
to: c_uint,
) -> EntropykErrorCode {
if system.is_null() {
return EntropykErrorCode::EntropykNullPointer;
}
let sys = &mut *(system as *mut entropyk_solver::System);
let src = petgraph::graph::NodeIndex::new(from as usize);
let tgt = petgraph::graph::NodeIndex::new(to as usize);
match sys.add_edge(src, tgt) {
Ok(_) => EntropykErrorCode::EntropykOk,
Err(e) => EntropykErrorCode::from(e),
}
}
/// Finalize the system for solving.
///
/// Must be called before any solve function.
///
/// # Arguments
///
/// - `system`: The system (must not be null)
///
/// # Returns
///
/// - `ENTROPYK_OK` on success
/// - `ENTROPYK_NULL_POINTER` if system is null
/// - `ENTROPYK_TOPOLOGY_ERROR` if topology is invalid
///
/// # Safety
///
/// `system` must be a valid pointer.
#[no_mangle]
pub unsafe extern "C" fn entropyk_system_finalize(
system: *mut EntropykSystem,
) -> EntropykErrorCode {
if system.is_null() {
return EntropykErrorCode::EntropykNullPointer;
}
let sys = &mut *(system as *mut entropyk_solver::System);
match sys.finalize() {
Ok(_) => EntropykErrorCode::EntropykOk,
Err(e) => EntropykErrorCode::from(e),
}
}
/// Get the number of components (nodes) in the system.
///
/// # Safety
///
/// `system` must be a valid pointer or null.
#[no_mangle]
pub unsafe extern "C" fn entropyk_system_node_count(system: *const EntropykSystem) -> c_uint {
if system.is_null() {
return 0;
}
let sys = &*(system as *const entropyk_solver::System);
sys.node_count() as c_uint
}
/// Get the number of edges in the system.
///
/// # Safety
///
/// `system` must be a valid pointer or null.
#[no_mangle]
pub unsafe extern "C" fn entropyk_system_edge_count(system: *const EntropykSystem) -> c_uint {
if system.is_null() {
return 0;
}
let sys = &*(system as *const entropyk_solver::System);
sys.edge_count() as c_uint
}
/// Get the length of the state vector (after finalization).
///
/// # Safety
///
/// `system` must be a valid pointer or null.
#[no_mangle]
pub unsafe extern "C" fn entropyk_system_state_vector_len(system: *const EntropykSystem) -> c_uint {
if system.is_null() {
return 0;
}
let sys = &*(system as *const entropyk_solver::System);
sys.state_vector_len() as c_uint
}

45
bindings/c/tests/Makefile Normal file
View File

@@ -0,0 +1,45 @@
CC ?= gcc
CFLAGS = -Wall -Wextra -O2 -I../../../target
UNAME_S := $(shell uname -s)
ifeq ($(UNAME_S),Darwin)
LIB_EXT = dylib
LDFLAGS = -L../../../target/release -lentropyk_ffi
else ifeq ($(UNAME_S),Linux)
LIB_EXT = so
LDFLAGS = -L../../../target/release -lentropyk_ffi -Wl,-rpath,'$$ORIGIN/../../../target/release'
else
LIB_EXT = dll
LDFLAGS = -L../../../target/release -lentropyk_ffi
endif
TESTS = test_lifecycle test_errors test_solve test_latency test_memory
.PHONY: all clean run valgrind
all: $(TESTS)
$(TESTS): %: %.c ../../../target/entropyk.h ../../../target/release/libentropyk_ffi.$(LIB_EXT)
$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)
../../../target/entropyk.h ../../../target/release/libentropyk_ffi.$(LIB_EXT):
cd ../../.. && cargo build --release -p entropyk-c
run: $(TESTS)
@echo "Running all tests..."
@for test in $(TESTS); do \
echo "\n=== $$test ==="; \
./$$test || exit 1; \
done
@echo "\nAll tests PASSED"
valgrind: $(TESTS)
@echo "Running valgrind memory checks..."
@for test in $(TESTS); do \
echo "\n=== $$test (valgrind) ==="; \
valgrind --leak-check=full --error-exitcode=1 ./$$test || exit 1; \
done
@echo "\nAll valgrind checks PASSED"
clean:
rm -f $(TESTS)

BIN
bindings/c/tests/test_errors Executable file
View File

Binary file not shown.

68
bindings/c/tests/test_errors.c Normal file
View File

@@ -0,0 +1,68 @@
/**
* Test: Error code verification
*
* Verifies that error codes are correctly returned and mapped.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include "entropyk.h"
int main() {
printf("Test: Error codes\n");
/* Test 1: Error strings */
printf(" Test 1: Error strings are non-null... ");
assert(entropyk_error_string(ENTROPYK_OK) != NULL);
assert(entropyk_error_string(ENTROPYK_NON_CONVERGENCE) != NULL);
assert(entropyk_error_string(ENTROPYK_TIMEOUT) != NULL);
assert(entropyk_error_string(ENTROPYK_CONTROL_SATURATION) != NULL);
assert(entropyk_error_string(ENTROPYK_FLUID_ERROR) != NULL);
assert(entropyk_error_string(ENTROPYK_INVALID_STATE) != NULL);
assert(entropyk_error_string(ENTROPYK_VALIDATION_ERROR) != NULL);
assert(entropyk_error_string(ENTROPYK_NULL_POINTER) != NULL);
assert(entropyk_error_string(ENTROPYK_INVALID_ARGUMENT) != NULL);
assert(entropyk_error_string(ENTROPYK_NOT_FINALIZED) != NULL);
assert(entropyk_error_string(ENTROPYK_TOPOLOGY_ERROR) != NULL);
assert(entropyk_error_string(ENTROPYK_COMPONENT_ERROR) != NULL);
assert(entropyk_error_string(ENTROPYK_UNKNOWN) != NULL);
printf("PASS\n");
/* Test 2: OK message */
printf(" Test 2: OK message contains 'Success'... ");
const char* ok_msg = entropyk_error_string(ENTROPYK_OK);
assert(strstr(ok_msg, "Success") != NULL);
printf("PASS\n");
/* Test 3: Null pointer error */
printf(" Test 3: Null pointer returns ENTROPYK_NULL_POINTER... ");
EntropykErrorCode err = entropyk_system_add_edge(NULL, 0, 1);
assert(err == ENTROPYK_NULL_POINTER);
printf("PASS\n");
/* Test 4: Component with invalid parameters */
printf(" Test 4: Invalid parameters return null... ");
EntropykComponent* comp = entropyk_condenser_create(-1.0); /* Invalid UA */
assert(comp == NULL);
comp = entropyk_evaporator_create(0.0); /* Invalid UA */
assert(comp == NULL);
comp = entropyk_compressor_create(NULL, 10); /* Null coefficients */
assert(comp == NULL);
double coeffs[5] = {1, 2, 3, 4, 5};
comp = entropyk_compressor_create(coeffs, 5); /* Wrong count */
assert(comp == NULL);
printf("PASS\n");
/* Test 5: Not finalized error */
printf(" Test 5: Finalize returns NOT_FINALIZED for empty system... ");
EntropykSystem* sys = entropyk_system_create();
/* Empty system may not finalize properly - this tests error handling */
entropyk_system_finalize(sys); /* May return error for empty system */
entropyk_system_free(sys);
printf("PASS\n");
printf("All error code tests PASSED\n");
return 0;
}

BIN
bindings/c/tests/test_latency Executable file
View File

Binary file not shown.

94
bindings/c/tests/test_latency.c Normal file
View File

@@ -0,0 +1,94 @@
/**
* Test: Latency measurement for HIL systems
*
* Measures round-trip latency for solve operations.
*/
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <time.h>
#include <assert.h>
#include "entropyk.h"
#define NUM_ITERATIONS 100
#define TARGET_LATENCY_MS 20.0
int main() {
printf("Test: HIL Latency\n");
printf(" Target: < %.1f ms per solve\n", TARGET_LATENCY_MS);
/* Setup: Create a simple system */
EntropykSystem* sys = entropyk_system_create();
assert(sys != NULL);
double 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(coeffs, 10);
EntropykComponent* cond = entropyk_condenser_create(5000.0);
EntropykComponent* valve = entropyk_expansion_valve_create();
EntropykComponent* evap = entropyk_evaporator_create(3000.0);
assert(comp && cond && valve && evap);
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);
assert(comp_idx != UINT32_MAX);
assert(cond_idx != UINT32_MAX);
assert(valve_idx != UINT32_MAX);
assert(evap_idx != UINT32_MAX);
entropyk_system_add_edge(sys, comp_idx, cond_idx);
entropyk_system_add_edge(sys, cond_idx, valve_idx);
entropyk_system_add_edge(sys, valve_idx, evap_idx);
entropyk_system_add_edge(sys, evap_idx, comp_idx);
entropyk_system_finalize(sys);
EntropykFallbackConfig config = {
.newton = {50, 1e-4, false, 1000},
.picard = {200, 1e-3, 0.5}
};
/* Measure latency */
printf(" Running %d solve iterations...\n", NUM_ITERATIONS);
double total_ms = 0.0;
int success_count = 0;
for (int i = 0; i < NUM_ITERATIONS; i++) {
EntropykSolverResult* result = NULL;
clock_t start = clock();
EntropykErrorCode err = entropyk_solve_fallback(sys, &config, &result);
clock_t end = clock();
double elapsed_ms = 1000.0 * (end - start) / CLOCKS_PER_SEC;
total_ms += elapsed_ms;
if (err == ENTROPYK_OK) {
success_count++;
entropyk_result_free(result);
}
}
double avg_ms = total_ms / NUM_ITERATIONS;
printf(" Results:\n");
printf(" Total time: %.2f ms\n", total_ms);
printf(" Average latency: %.3f ms\n", avg_ms);
printf(" Successful solves: %d / %d\n", success_count, NUM_ITERATIONS);
/* Note: Stub components don't actually solve, so latency should be very fast */
printf(" Average latency: %.3f ms %s target of %.1f ms\n",
avg_ms,
avg_ms < TARGET_LATENCY_MS ? "<" : ">=",
TARGET_LATENCY_MS);
entropyk_system_free(sys);
printf("Latency test PASSED\n");
return 0;
}

BIN
bindings/c/tests/test_lifecycle Executable file
View File

Binary file not shown.

53
bindings/c/tests/test_lifecycle.c Normal file
View File

@@ -0,0 +1,53 @@
/**
* Test: System lifecycle (create/free cycle)
*
* Verifies that systems can be created and freed without memory leaks.
*/
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#include "entropyk.h"
int main() {
printf("Test: System lifecycle\n");
/* Test 1: Create and free a system */
printf(" Test 1: Create and free single system... ");
EntropykSystem* sys = entropyk_system_create();
assert(sys != NULL);
entropyk_system_free(sys);
printf("PASS\n");
/* Test 2: Free null pointer (should not crash) */
printf(" Test 2: Free null pointer... ");
entropyk_system_free(NULL);
printf("PASS\n");
/* Test 3: Multiple create/free cycles */
printf(" Test 3: Multiple create/free cycles... ");
for (int i = 0; i < 100; i++) {
EntropykSystem* s = entropyk_system_create();
assert(s != NULL);
entropyk_system_free(s);
}
printf("PASS\n");
/* Test 4: Node count on empty system */
printf(" Test 4: Node count on empty system... ");
sys = entropyk_system_create();
assert(entropyk_system_node_count(sys) == 0);
assert(entropyk_system_edge_count(sys) == 0);
entropyk_system_free(sys);
printf("PASS\n");
/* Test 5: Null pointer handling */
printf(" Test 5: Null pointer handling... ");
assert(entropyk_system_node_count(NULL) == 0);
assert(entropyk_system_edge_count(NULL) == 0);
assert(entropyk_system_state_vector_len(NULL) == 0);
printf("PASS\n");
printf("All lifecycle tests PASSED\n");
return 0;
}

BIN
bindings/c/tests/test_memory Executable file
View File

Binary file not shown.

156
bindings/c/tests/test_memory.c Normal file
View File

@@ -0,0 +1,156 @@
/**
* Test: Memory leak detection
*
* This test should be run with valgrind or ASAN to detect memory leaks.
*
* Usage:
* valgrind --leak-check=full --error-exitcode=1 ./test_memory
*
* Or compile with ASAN:
* gcc -fsanitize=address -o test_memory test_memory.c -L../../../target/release -lentropyk_ffi
* ./test_memory
*/
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <assert.h>
#include "entropyk.h"
#define NUM_CYCLES 100
int main() {
printf("Test: Memory leak detection\n");
printf(" Run with: valgrind --leak-check=full ./test_memory\n\n");
/* Test 1: System lifecycle */
printf(" Test 1: System create/free cycles (%d iterations)... ", NUM_CYCLES);
for (int i = 0; i < NUM_CYCLES; i++) {
EntropykSystem* sys = entropyk_system_create();
assert(sys != NULL);
entropyk_system_free(sys);
}
printf("PASS\n");
/* Test 2: Component lifecycle (not added to system) */
printf(" Test 2: Component create/free cycles... ");
for (int i = 0; i < NUM_CYCLES; i++) {
double 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(coeffs, 10);
EntropykComponent* cond = entropyk_condenser_create(5000.0);
EntropykComponent* evap = entropyk_evaporator_create(3000.0);
EntropykComponent* valve = entropyk_expansion_valve_create();
assert(comp && cond && evap && valve);
entropyk_compressor_free(comp);
entropyk_component_free(cond);
entropyk_component_free(evap);
entropyk_component_free(valve);
}
printf("PASS\n");
/* Test 3: Full system with components (ownership transfer) */
printf(" Test 3: Full system lifecycle... ");
for (int i = 0; i < NUM_CYCLES; i++) {
EntropykSystem* sys = entropyk_system_create();
assert(sys != NULL);
double 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(coeffs, 10);
EntropykComponent* cond = entropyk_condenser_create(5000.0);
EntropykComponent* evap = entropyk_evaporator_create(3000.0);
EntropykComponent* valve = entropyk_expansion_valve_create();
unsigned int comp_idx = entropyk_system_add_component(sys, comp);
unsigned int cond_idx = entropyk_system_add_component(sys, cond);
unsigned int evap_idx = entropyk_system_add_component(sys, evap);
unsigned int valve_idx = entropyk_system_add_component(sys, valve);
(void)comp_idx; (void)cond_idx; (void)evap_idx; (void)valve_idx;
entropyk_system_free(sys);
/* Note: Components are freed when system is freed (ownership transfer) */
}
printf("PASS\n");
/* Test 4: Solver result lifecycle */
printf(" Test 4: Solver result lifecycle... ");
for (int i = 0; i < NUM_CYCLES; i++) {
EntropykSystem* sys = entropyk_system_create();
double 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(coeffs, 10);
EntropykComponent* cond = entropyk_condenser_create(5000.0);
EntropykComponent* evap = entropyk_evaporator_create(3000.0);
EntropykComponent* valve = entropyk_expansion_valve_create();
entropyk_system_add_component(sys, comp);
entropyk_system_add_component(sys, cond);
entropyk_system_add_component(sys, evap);
entropyk_system_add_component(sys, valve);
entropyk_system_finalize(sys);
EntropykFallbackConfig config = {
.newton = {10, 1e-4, false, 100},
.picard = {20, 1e-3, 0.5}
};
EntropykSolverResult* result = NULL;
entropyk_solve_fallback(sys, &config, &result);
if (result != NULL) {
entropyk_result_free(result);
}
entropyk_system_free(sys);
}
printf("PASS\n");
/* Test 5: Null pointer handling (should not crash or leak) */
printf(" Test 5: Null pointer handling... ");
entropyk_system_free(NULL);
entropyk_compressor_free(NULL);
entropyk_component_free(NULL);
entropyk_result_free(NULL);
printf("PASS\n");
/* Test 6: State vector retrieval */
printf(" Test 6: State vector allocation... ");
EntropykSystem* sys = entropyk_system_create();
double 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(coeffs, 10);
EntropykComponent* cond = entropyk_condenser_create(5000.0);
EntropykComponent* evap = entropyk_evaporator_create(3000.0);
EntropykComponent* valve = entropyk_expansion_valve_create();
entropyk_system_add_component(sys, comp);
entropyk_system_add_component(sys, cond);
entropyk_system_add_component(sys, evap);
entropyk_system_add_component(sys, valve);
entropyk_system_finalize(sys);
EntropykFallbackConfig config = {
.newton = {10, 1e-4, false, 100},
.picard = {20, 1e-3, 0.5}
};
EntropykSolverResult* result = NULL;
if (entropyk_solve_fallback(sys, &config, &result) == ENTROPYK_OK && result != NULL) {
unsigned int len = 0;
entropyk_result_get_state_vector(result, NULL, &len);
if (len > 0) {
double* state = (double*)malloc(len * sizeof(double));
entropyk_result_get_state_vector(result, state, &len);
free(state);
}
entropyk_result_free(result);
}
entropyk_system_free(sys);
printf("PASS\n");
printf("\nAll memory tests PASSED\n");
printf("If running under valgrind, check for 'ERROR SUMMARY: 0 errors'\n");
return 0;
}

BIN
bindings/c/tests/test_solve Executable file
View File

Binary file not shown.

116
bindings/c/tests/test_solve.c Normal file
View File

@@ -0,0 +1,116 @@
/**
* Test: End-to-end solve from C
*
* Creates a simple cycle and solves it.
*/
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <assert.h>
#include "entropyk.h"
int main() {
printf("Test: End-to-end solve\n");
/* Create system */
printf(" Creating system... ");
EntropykSystem* sys = entropyk_system_create();
assert(sys != NULL);
printf("OK\n");
/* Create components */
printf(" Creating components... ");
double 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(coeffs, 10);
EntropykComponent* cond = entropyk_condenser_create(5000.0);
EntropykComponent* valve = entropyk_expansion_valve_create();
EntropykComponent* evap = entropyk_evaporator_create(3000.0);
assert(comp && cond && valve && evap);
printf("OK\n");
/* Add components (returns node index) */
printf(" Adding components... ");
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);
assert(comp_idx != UINT32_MAX);
assert(cond_idx != UINT32_MAX);
assert(valve_idx != UINT32_MAX);
assert(evap_idx != UINT32_MAX);
printf("OK (indices: %u, %u, %u, %u)\n", comp_idx, cond_idx, valve_idx, evap_idx);
/* Verify counts */
printf(" Verifying node count... ");
assert(entropyk_system_node_count(sys) == 4);
printf("OK\n");
/* Add edges */
printf(" Adding edges... ");
EntropykErrorCode err;
err = entropyk_system_add_edge(sys, comp_idx, cond_idx);
assert(err == ENTROPYK_OK);
err = entropyk_system_add_edge(sys, cond_idx, valve_idx);
assert(err == ENTROPYK_OK);
err = entropyk_system_add_edge(sys, valve_idx, evap_idx);
assert(err == ENTROPYK_OK);
err = entropyk_system_add_edge(sys, evap_idx, comp_idx);
assert(err == ENTROPYK_OK);
printf("OK\n");
/* Verify edge count */
printf(" Verifying edge count... ");
assert(entropyk_system_edge_count(sys) == 4);
printf("OK\n");
/* Finalize */
printf(" Finalizing system... ");
err = entropyk_system_finalize(sys);
/* Empty system might fail to finalize - check but don't assert */
if (err != ENTROPYK_OK) {
printf("Note: Finalize returned %d (expected for empty component stubs)\n", err);
} else {
printf("OK\n");
}
/* Configure solver */
printf(" Configuring solver... ");
EntropykFallbackConfig config = {
.newton = {
.max_iterations = 100,
.tolerance = 1e-6,
.line_search = false,
.timeout_ms = 0
},
.picard = {
.max_iterations = 500,
.tolerance = 1e-4,
.relaxation = 0.5
}
};
printf("OK\n");
/* Solve (may not converge with stub components) */
printf(" Attempting solve... ");
EntropykSolverResult* result = NULL;
err = entropyk_solve_fallback(sys, &config, &result);
if (err == ENTROPYK_OK && result != NULL) {
printf("OK\n");
printf("Status: %d\n", entropyk_result_get_status(result));
printf(" Iterations: %u\n", entropyk_result_get_iterations(result));
printf(" Residual: %.2e\n", entropyk_result_get_residual(result));
entropyk_result_free(result);
} else {
printf("Error: %s (expected with stub components)\n", entropyk_error_string(err));
}
/* Cleanup */
printf(" Cleaning up... ");
entropyk_system_free(sys);
printf("OK\n");
printf("End-to-end solve test PASSED\n");
return 0;
}