Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 15 additions & 18 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,29 @@
---
name: Bug report
about: Create a report to help us improve
about: Report a problem to help us improve
title: "[bug]"
labels: bug
assignees: markleader

---

**Describe the bug**
A clear and concise description of what the bug is.

- Interface(s) affected: [e.g. Fortran, C, legacy, Python]

- Is this an issue with backwards-compatibility using the legacy interface? If so, paste the the `.inp` problem file, and the relevant output for inspection.
**Summary**
A clear, concise description of the bug.

**To Reproduce**
Steps to reproduce the behavior:
**Reproduction**
- Interface: [Fortran | C | Python | legacy]
- Minimal input / steps (attach .inp if relevant):
- Command or API call used:

**Expected behavior**
A clear and concise description of what you expected to happen.
What you expected to happen.

**Screenshots**
If applicable, add screenshots to help explain your problem.
**Actual behavior**
What happened (include key error messages/output).

**Build architecture (please complete the following information):**
- OS: [e.g. Mac OS, Windows]
- Fortran compiler [e.g. gfortran, ifort]
- Version [e.g. 3.0.0]
**Environment**
- OS:
- CEA version/commit:
- Compiler or Python version (if relevant):

**Additional context**
Add any other context about the problem here.
Anything else helpful (optional).
13 changes: 6 additions & 7 deletions .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@
---
name: Feature request
about: Suggest an idea for this project
about: Suggest an improvement
title: "[feature]"
labels: enhancement
assignees: ''

---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. It is difficult to [...]
**Problem / use case**
What’s hard or missing today?

**Describe the solution you'd like**
A clear and concise description of what you want to happen.
**Proposed solution**
What would you like to see?

**Additional context**
Add any other context or screenshots about the feature request here.
Examples, references, or alternatives (optional).
10 changes: 10 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
## Summary

## Changes

## Testing
- Not run (explain why)

## Compatibility / Numerical behavior
- [ ] No expected changes to numerical results
- [ ] Expected changes (explain and provide validation)
25 changes: 24 additions & 1 deletion .github/workflows/basic_build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,12 +36,34 @@ jobs:
with:
python-version: "3.12"

- name: Set up Fortran compiler
- name: Set up Fortran compiler (Unix)
if: runner.os != 'Windows'
uses: fortran-lang/setup-fortran@v1
with:
compiler: ${{ matrix.toolchain.compiler }}
version: ${{ matrix.toolchain.version }}

- name: Set up Fortran compiler (Windows)
if: runner.os == 'Windows'
run: |
# Use pre-installed MinGW on Windows runners to avoid Chocolatey issues
# GitHub Actions windows-latest runners include MinGW in C:\ProgramData\chocolatey\lib\mingw\tools\install\mingw64\bin
$mingwPath = "C:\ProgramData\chocolatey\lib\mingw\tools\install\mingw64\bin"
if (Test-Path $mingwPath) {
echo "$mingwPath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
echo "FC=$mingwPath\gfortran.exe" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
} else {
# Fallback: search for gfortran in common locations
$gfortran = Get-Command gfortran -ErrorAction SilentlyContinue
if ($gfortran) {
echo "FC=$($gfortran.Source)" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
} else {
Write-Error "gfortran not found on Windows runner"
exit 1
}
}
shell: pwsh

- name: Install build tools
run: |
python -m pip install --upgrade pip
Expand All @@ -52,6 +74,7 @@ jobs:
git --version
cmake --version
ninja --version
if command -v gfortran &> /dev/null; then gfortran --version; fi
if [ -n "${FC}" ]; then "${FC}" --version; fi

- name: Configure
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ extern/install
*.xlsx
*.pdf
*.bat
*.lib
!sampleThe/*.inp
!test/main_interface/*.inp
!test/main_interface/reference_output/*.out
Expand Down
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Changelog

All notable user-visible changes to this project are documented here.

## [Unreleased]

### Changed

### Fixed

### Added

## [3.0.0] – 2025-12-31
- Initial public release.
146 changes: 133 additions & 13 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,133 @@
# AGENTS

This repository is a scientific computing library (CEA). Follow these rules:

- Do NOT modify `thermo.inp` or `trans.inp` unless explicitly instructed.
- Numerical correctness is paramount; preserve bitwise results and scientific behavior.
- Avoid algorithmic changes unless explicitly requested.
- Prefer clarity over cleverness or micro-optimizations.
- Keep changes small and focused; avoid drive-by formatting or whitespace churn.
- Maintain backward compatibility for the legacy user base.
- If numerical behavior might change, call it out and add validation or tests when possible.
- Respect layer boundaries: Fortran core in `source/`, C bindings in `source/bind/c/`,
Python bindings in `source/bind/python/`.
# CLAUDE.md - AI Agent Instructions for CEA

This repository contains CEA (Chemical Equilibrium with Applications), a NASA scientific computing library for chemical equilibrium calculations. The codebase consists of validated Fortran solvers with C and Python bindings.

## Core Principles

1. **Numerical correctness is paramount** - Preserve bitwise results and scientific behavior
2. **Backward compatibility matters** - Legacy user base depends on stable behavior
3. **Clarity over cleverness** - Prefer readable code over micro-optimizations
4. **Small, focused changes** - One concern per change; avoid bundling unrelated work

## Critical Rules

### Data Files (DO NOT MODIFY)
- **NEVER** modify `thermo.inp` or `trans.inp` unless explicitly instructed by the user
- **NEVER** modify `data/thermo.inp` or `data/trans.inp`
- These files contain validated thermodynamic and transport property databases

### Algorithmic Changes
- **AVOID** changing solver algorithms unless explicitly requested
- **AVOID** modifying convergence logic, tolerances, or loop ordering
- **CALL OUT** any changes that might affect numerical behavior
- **ADD** validation tests when numerical behavior might change

### Code Quality
- **AVOID** drive-by formatting or whitespace changes
- **AVOID** restructuring code for style alone
- **KEEP** diffs minimal and focused
- **PRESERVE** existing naming conventions and patterns

## Architecture & Layer Boundaries

```
source/ - Fortran core (scientific solvers)
source/bind/c/ - C ABI bindings (thin adapters)
source/bind/python/ - Python interface (Cython/NumPy)
data/ - Thermodynamic and transport databases
```

**Respect layer boundaries:**
- Do not mix Fortran solver changes with binding changes
- Do not change scientific logic from binding layers
- Keep C bindings thin (no business logic)
- Python layer may add Pythonic conveniences but not alter solver behavior

## Build System

- **Build tool**: CMake 3.19+
- **Languages**: Fortran (core), C (bindings), Python (bindings)
- **Compilers**: Intel and GNU Fortran are primary targets
- **Python build**: scikit-build-core with Ninja generator
- **Presets available**: `core` (Fortran only), `core-c` (Fortran+C), default (all bindings)

### Python Binding Development
When modifying Python bindings:
1. Changes to `*.pyx` or `*.pxd` files require rebuild
2. Editable installs do not auto-rebuild
3. Rebuild command: `make py-rebuild` (requires Ninja on PATH)
4. Test command: `pytest source/bind/python/tests`
5. Ensure `numpy` is installed in the active Python environment

## Testing

- **Run existing tests** before and after changes
- **Add regression tests** for bug fixes when possible
- **Add validation tests** for new features
- **Verify** no unintended behavior changes occur

Test locations:
- Fortran: Built with `-DCEA_BUILD_TESTING=ON`
- Python: `pytest source/bind/python/tests`
- Legacy CLI validation: `test/main_interface/test_main.py`
- Samples: `samples/` directory contains reference cases

## Common Scenarios

### Bug Fixes
- Identify root cause before fixing
- Add regression test if feasible
- Keep fix minimal and focused
- Document what was broken and how it's fixed

### Documentation
- Improvements always welcome
- Use Markdown or reStructuredText
- Be technically accurate
- Avoid marketing language
- Document assumptions and limitations

### Interface Improvements (C/Python bindings)
- Allowed and encouraged
- Do not change solver behavior
- Add clear docstrings/comments
- Follow language idioms (Pythonic for Python, etc.)

### Refactoring
- Discuss with user first for large refactors
- Prove numerical equivalence
- Provide before/after comparison
- Small, incremental refactors preferred

## What to Call Out

**Always explicitly mention if your change involves:**
- Floating-point arithmetic reordering
- Loop ordering changes
- Tolerance or convergence criterion modifications
- Changes to thermodynamic assumptions
- Database compilation or access patterns
- Changes that might affect bitwise reproducibility

## Dependencies

**Core** (Fortran): No external dependencies
**C bindings**: No additional dependencies
**Python bindings**: Requires:
- Cython
- NumPy
- scikit-build-core
- Ninja (build time)

## References

When in doubt, refer to:
- [CONTRIBUTING.md](CONTRIBUTING.md) - Detailed contribution guidelines
- [README.md](README.md) - Build and usage instructions
- `docs/` - Full documentation

## Summary

Priority order: **Numerical correctness > Backward compatibility > Performance > Style**

When uncertain about a change, ask the user first.
55 changes: 42 additions & 13 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -79,27 +79,56 @@ add_subdirectory(extern/fbasics)
add_subdirectory(source)

# Build the thermodynamic properties database
#configure_file(src/thermo.inp thermo.inp COPYONLY)
#add_custom_target(thermo.lib ALL
# COMMAND cea thermo >/dev/null
# BYPRODUCTS thermo.lib thermo.out
# DEPENDS cea
#)
add_custom_command(
OUTPUT ${CMAKE_BINARY_DIR}/thermo.lib
COMMAND $<TARGET_FILE:cea> --compile-thermo ${CMAKE_SOURCE_DIR}/data/thermo.inp
DEPENDS cea ${CMAKE_SOURCE_DIR}/data/thermo.inp
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
COMMENT "Compiling thermodynamic database from thermo.inp"
)

# Build the transport properties database
#configure_file(src/trans.inp trans.inp COPYONLY)
#add_custom_target(trans.lib ALL
# COMMAND cea trans >/dev/null
# BYPRODUCTS trans.lib trans.out
# DEPENDS cea
#)
add_custom_command(
OUTPUT ${CMAKE_BINARY_DIR}/trans.lib
COMMAND $<TARGET_FILE:cea> --compile-trans ${CMAKE_SOURCE_DIR}/data/trans.inp
DEPENDS cea ${CMAKE_SOURCE_DIR}/data/trans.inp
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
COMMENT "Compiling transport database from trans.inp"
)

# Create a custom target that depends on both database files
add_custom_target(compile_databases ALL
DEPENDS ${CMAKE_BINARY_DIR}/thermo.lib ${CMAKE_BINARY_DIR}/trans.lib
)

if(PROJECT_IS_TOP_LEVEL)
add_custom_command(TARGET compile_databases POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${CMAKE_BINARY_DIR}/thermo.lib ${CMAKE_SOURCE_DIR}/data/thermo.lib
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${CMAKE_BINARY_DIR}/trans.lib ${CMAKE_SOURCE_DIR}/data/trans.lib
COMMAND ${CMAKE_COMMAND} -E make_directory
${CMAKE_SOURCE_DIR}/source/bind/python/cea/data
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${CMAKE_BINARY_DIR}/thermo.lib
${CMAKE_SOURCE_DIR}/source/bind/python/cea/data/thermo.lib
COMMAND ${CMAKE_COMMAND} -E copy_if_different
${CMAKE_BINARY_DIR}/trans.lib
${CMAKE_SOURCE_DIR}/source/bind/python/cea/data/trans.lib
COMMENT "Copying compiled databases to source data directory"
)
endif()


#-----------------------------------------------------------------------
# Installation
#-----------------------------------------------------------------------
install(
FILES data/thermo.lib data/trans.lib
FILES ${CMAKE_BINARY_DIR}/thermo.lib ${CMAKE_BINARY_DIR}/trans.lib
DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/cea
)
install(
FILES ${CMAKE_BINARY_DIR}/thermo.lib ${CMAKE_BINARY_DIR}/trans.lib
DESTINATION ${CMAKE_INSTALL_PREFIX}/data
)
install(EXPORT cea-config
Expand Down
Loading
Loading