Entropyk/AGENTS.md

Entropyk - Thermodynamic Cycle Simulation

Project: Entropyk Description: A thermodynamic cycle simulation library for refrigeration, heat pumps, and HVAC systems Language: Rust Architecture: Component-based with type-safe APIs

Project Structure

entropyk/
├── crates/
│   ├── core/          # Core types (Pressure, Temperature, Enthalpy, etc.)
│   ├── components/    # Thermodynamic components (Compressor, HeatExchanger, etc.)
│   ├── fluids/        # Fluid property backends (CoolProp, tabular, incompressible)
│   ├── solver/        # Newton-Raphson, Picard, fallback strategies
│   ├── entropyk/      # Main library with System, SystemBuilder APIs
│   ├── cli/           # Command-line interface
│   ├── vendors/       # Vendor data parsers (Copeland, Danfoss, SWEP, Bitzer)
│   └── bindings/      # Python (PyO3), C (cbindgen), WebAssembly
├── _bmad/             # BMAD methodology workflows and artifacts
└── _bmad-output/      # Generated planning and implementation artifacts

Development Commands

# Build
cargo build

# Test
cargo test

# Run specific test
cargo test --package entropyk-components test_name

# Run CLI
cargo run --package entropyk-cli -- validate --config config.json

# Check warnings
cargo build 2>&1 | grep warning

Code Standards

• Language: Rust with strict type safety
• Style: Follow cargo fmt and cargo clippy recommendations
• Errors: All operations return Result<T, E> - zero panic policy
• Documentation: Public APIs must have doc comments with examples
• Tests: Unit tests in each crate, integration tests in tests/ directories

BMAD Workflow Execution - CRITICAL

This project uses BMAD (Build-Measure-Analyze-Deploy) methodology with automated workflows.

MANDATORY WORKFLOW COMPLIANCE

CRITICAL RULE: When executing BMAD workflows from _bmad/bmm/workflows/:

1. ALWAYS LOAD THE WORKFLOW FILE FIRST

   # Read the workflow YAML before starting
   _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml
   

2. FOLLOW EVERY STEP EXACTLY AS SPECIFIED

   • Do NOT skip steps
   • Do NOT combine steps
   • Do NOT improvise or simplify
   • Execute in the order specified

3. DISPLAY ALL MANDATORY OUTPUTS

   • Every <output> tag in the workflow XML MUST be displayed
   • Display messages EXACTLY as specified - do not paraphrase
   • Include ALL status messages, confirmations, and sync messages

4. EXAMPLES OF MANDATORY OUTPUTS

   🔄 Sprint status synced: 12-3-cli-screw-compressor-config → in-progress
   

   ✅ Review Complete!
   
   Story Status: in-progress
   Issues Fixed: 7
   Action Items Created: 0
   

5. NEVER SKIP THESE MESSAGES

   • Sprint status sync messages
   • Workflow completion messages
   • Step completion confirmations
   • Any message in <output> tags

Workflow Locations

• Code Review: _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml
• All Workflows: _bmad/bmm/workflows/
• Configuration: _bmad/bmm/config.yaml
• Sprint Status: _bmad-output/implementation-artifacts/sprint-status.yaml

Workflow Execution Pattern

1. Load workflow file (.yaml or .xml)
2. Parse all steps and requirements
3. Execute each step in order
4. Display ALL <output> messages EXACTLY as specified
5. Update files as required
6. Confirm completion with mandatory messages

Example: Code Review Workflow

When user says "Execute the BMAD 'code-review' workflow":

# Step 1: Load workflow
Read _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml
Read _bmad/bmm/workflows/4-implementation/code-review/instructions.xml

# Step 2: Execute workflow steps
# ... perform review ...

# Step 3: Display MANDATORY outputs (from instructions.xml:192-215)
🔄 Sprint status synced: 12-3-cli-screw-compressor-config → in-progress

✅ Review Complete!

Story Status: in-progress
Issues Fixed: 7
Action Items Created: 0

DO NOT skip the 🔄 Sprint status synced message. It's critical for tracking.

Communication Preferences

• User name: Sepehr
• Communication language: French (respond to user in French)
• Document output language: English (technical docs, comments, commit messages)
• Skill level: Intermediate (can handle technical details)

Component Architecture

Components implement the Component trait:

pub trait Component {
    fn n_equations(&self) -> usize;
    fn compute_residuals(&self, state: &[f64], residuals: &mut ResidualVector) -> Result<(), ComponentError>;
    fn jacobian_entries(&self, state: &[f64], jacobian: &mut JacobianBuilder) -> Result<(), ComponentError>;
    fn get_ports(&self) -> &[ConnectedPort];
    // ... other methods
}

Testing Strategy

• Unit tests in each crate (#[cfg(test)] modules)
• Integration tests in tests/ directories
• CLI tests in crates/cli/tests/
• Example configs in crates/cli/examples/

Git Workflow

• Main branch: main
• Commit messages: English, imperative mood ("Add feature", "Fix bug")
• Pre-commit: Run cargo test and cargo clippy

Common Tasks

Adding a New Component

1. Create struct implementing Component trait in crates/components/src/
2. Add unit tests with at least 80% coverage
3. Export from crates/components/src/lib.rs
4. Re-export from crates/entropyk/src/lib.rs
5. Add CLI support in crates/cli/src/run.rs
6. Create example config in crates/cli/examples/
7. Update documentation

Running a BMAD Workflow

1. Load workflow file from _bmad/bmm/workflows/
2. Execute each step EXACTLY as specified
3. Display ALL mandatory outputs from <output> tags
4. Update sprint status in _bmad-output/implementation-artifacts/sprint-status.yaml
5. Display sync confirmation message

Warnings to Watch For

• Unused imports: Fix immediately
• Deprecated types: Check migration guide in docs/migration/
• Clippy warnings: Address before commit
• Test failures: Never commit with failing tests

External Dependencies

• CoolProp: Thermodynamic property database (compiled as static library)
• Petgraph: Graph data structure for system topology
• Serde: Serialization/deserialization for JSON configs
• Tracing: Logging and diagnostics

Key Files to Know

• crates/entropyk/src/lib.rs - Main library API
• crates/solver/src/system.rs - System topology and solver integration
• crates/cli/src/run.rs - CLI simulation execution
• _bmad-output/implementation-artifacts/sprint-status.yaml - Sprint tracking
• AGENTS.md - This file (OpenCode instructions)

Workflow Compliance Checklist

Before completing ANY BMAD workflow task:

• Loaded workflow YAML/XML file
• Read all steps in order
• Executed each step without skipping
• Displayed ALL <output> messages exactly as specified
• Updated sprint-status.yaml if required
• Displayed sync confirmation message (🔄 Sprint status synced)
• Displayed completion message (✅ Review Complete!)
• Did NOT improvise or simplify any workflow steps

Important Reminders

1. BMAD workflows are not suggestions - they are mandatory processes
2. Output messages are not optional - they're critical for tracking
3. Follow workflows literally - don't reinterpret or simplify
4. When in doubt, read the workflow file - it contains all requirements
5. Sprint status sync is MANDATORY - always display the confirmation message

---

Last Updated: 2026-03-01 BMAD Version: 6.0.1 Project: Entropyk

Component Integration Process - CRITICAL RULE

When adding a new thermodynamic component, it MUST be fully integrated across all supported target interfaces natively. Follow this protocol:

1. Core Rust & Solver Representation (crates/components)

• Implement Trait: Implement entropyk::Component (compute_residuals, jacobian_entries, n_equations, get_ports, signature, energy_transfers).
• Jacobian Accuracy: The Jacobian MUST be exact. Do not use numerical differentiation unless explicitly requested. Verify with tests.
• Type-State APIs: Use Disconnected -> Connected typestate pattern for port connections (new() returns disconnected, connect() returns connected).
• Facade Export: Export in crates/components/src/lib.rs AND re-export in crates/entropyk/src/lib.rs.
• Solver Constraints API: If the component has control variables (e.g., fan speed, opening, frequency), ensure these fields can be manipulated and registered via the embedding / Bounded / Constraint API for inverse calibration/Eurovent rating.

2. CLI Integration (crates/cli)

• Config Parsing: Add a new match arm in crates/cli/src/run.rs inside create_component.
• Parameter Extraction: Extract required and optional parameters from JSON. Provide safe default values (e.g. unwrap_or()).
• Port Resolution: Instantiate the component using make_connected_port for boundaries, or the standard Port::new(...) -> .connect() pattern for N-port components.

3. Python Bindings (crates/bindings/python via PyO3)

• PyClass Wrapper: Define a #[pyclass] structural wrapper mapping Python primitives to Rust's strong types.
• State & Properties: Expose getters (#[getter]) and setters (#[setter]) for variables.
• Registration: Register the wrapper in the PyModule definition.

4. WebAssembly Integration (crates/bindings/wasm)

• Wasm Wrapper: Create a #[wasm_bindgen] wrapper.
• Methods: Expose state mutation methods to JS using #[wasm_bindgen], mapping complex types to strings/f64s.