cande-wrapper 0.0.1__tar.gz

cande_wrapper-0.0.1/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: cande-wrapper
+Version: 0.0.1
+Summary: Placeholder for the CANDE FEA culvert analysis engine
+Requires-Python: >=3.10

cande_wrapper-0.0.1/README.md

@@ -0,0 +1,130 @@
+# cande-wrapper
+
+Python wrapper for the [CANDE](https://www.fhwa.dot.gov/engineering/hydraulics/software/culvertanalysis.cfm) (Culvert ANalysis and DEsign) finite element engine.
+
+The CANDE-2025 Fortran source is compiled via [f2py](https://numpy.org/doc/stable/f2py/) into a native Python extension module, allowing direct calls from Python without subprocess overhead or DLL wrappers.
+
+## Prerequisites
+
+| Dependency | Version | Purpose |
+|---|---|---|
+| Python | >= 3.10 | Runtime |
+| gfortran | any recent | Compiles the CANDE Fortran engine |
+| NumPy | >= 1.26 | f2py extension building and runtime |
+| Meson | >= 1.1 | Build system |
+| Ninja | any recent | Build backend for Meson |
+
+### Installing gfortran on Windows
+
+The easiest way is via MSYS2:
+
+```bash
+# In MSYS2 terminal
+pacman -S mingw-w64-x86_64-gcc-fortran
+
+# Add to PATH (PowerShell)
+$env:PATH += ";C:\msys64\mingw64\bin"
+```
+
+Or install via conda:
+
+```bash
+conda install -c conda-forge gfortran
+```
+
+### Installing build tools
+
+```bash
+pip install meson-python meson ninja numpy
+```
+
+## Installation
+
+From the project root:
+
+```bash
+pip install -e ".[dev]"
+```
+
+This compiles the Fortran engine via f2py and installs the Python package in editable mode. The `[dev]` extra includes pytest and jupyter for testing and notebooks.
+
+If the build fails, see [Troubleshooting](#troubleshooting) below.
+
+## Quick Start
+
+```python
+from cande_wrapper import CandeEngine
+
+engine = CandeEngine(work_dir="path/to/my/models")
+result = engine.run("EX1")  # reads EX1.cid, writes EX1.out
+print(result.output_text)
+```
+
+## CANDE Input Files
+
+CANDE reads `.cid` input files (CANDE Input Data). These are fixed-format text files with sections:
+
+- **A-1**: Master control line (analysis/design mode, solution level, title)
+- **A-2**: Pipe type and element counts
+- **B-\***: Pipe material properties
+- **C-\***: Mesh, node, and element definitions
+- **D-\***: Soil properties and load steps
+- **STOP**: End-of-problem marker
+
+Multiple problems can be run back-to-back in a single `.cid` file, each terminated by `STOP`.
+
+An example input file is included at `tests/example_data/MGK-IO.cid`.
+
+## Output Files
+
+After running `engine.run("prefix")`, these files are created in the working directory:
+
+| File | Description |
+|---|---|
+| `prefix.out` | Main analysis output report |
+| `prefix.log` | Engine log messages |
+| `prefix.ctc` | Table of contents for the output |
+| `prefix_MeshGeom.xml` | Mesh geometry (for visualization) |
+| `prefix_MeshResults.xml` | Mesh results (for visualization) |
+| `prefix_BeamResults.xml` | Beam element results |
+| `prefix_PLOT1.dat` | Plot data file 1 |
+| `prefix_PLOT2.dat` | Plot data file 2 |
+
+The `CandeResult` object returned by `engine.run()` gives convenient access to the main output files:
+
+```python
+result = engine.run("EX1")
+print(result.output_file)   # Path to EX1.out
+print(result.log_file)      # Path to EX1.log
+print(result.output_text)   # Full contents of EX1.out
+```
+
+## Testing
+
+```bash
+pytest -v                    # unit tests (no build required)
+pytest -m integration -v     # integration tests (requires build)
+pytest -m "" -v              # all tests
+```
+
+## Troubleshooting
+
+### `gfortran: command not found`
+
+gfortran is not on your PATH. Verify with `gfortran --version`. On Windows, ensure the MSYS2/MinGW or conda bin directory is in your PATH.
+
+### Linker errors about missing symbols
+
+The `meson.build` file lists Engine source files explicitly. If you see unresolved symbols like `plasti_` or `prhero_`, the corresponding `.f` file needs to be added to the `engine_sources` list in `meson.build`.
+
+### `ImportError: CANDE Fortran extension not found`
+
+The package was imported but the compiled extension (`_cande.pyd` / `_cande.so`) was not found. Rebuild with:
+
+```bash
+pip install -e . --no-build-isolation
+```
+
+### Large memory usage
+
+The CANDE engine statically allocates ~320 MB for the stiffness matrix (`REAL*8 A(20000,2000)` in `system.fi`). This is normal for FEA solvers and is mapped as virtual memory.

cande_wrapper-0.0.1/pyproject.toml

@@ -0,0 +1,9 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cande-wrapper"
+version = "0.0.1"
+description = "Placeholder for the CANDE FEA culvert analysis engine"
+requires-python = ">=3.10"

cande_wrapper-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cande_wrapper-0.0.1/src/cande_wrapper/__init__.py

@@ -0,0 +1,5 @@
+"""cande-wrapper: Python wrapper for the CANDE FEA culvert analysis engine."""
+print('Hello from cande-wrapper!')
+# from cande_wrapper.engine import CandeEngine, CandeResult
+#
+# __all__ = ["CandeEngine", "CandeResult"]

cande_wrapper-0.0.1/src/cande_wrapper/engine.py

@@ -0,0 +1,165 @@
+"""Python interface to the CANDE Fortran engine."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def _find_gfortran_dirs() -> list[str]:
+    """Find directories containing gfortran runtime DLLs on Windows."""
+    import shutil
+
+    dirs = []
+    # Check if gfortran is on PATH and find its bin directory
+    gfortran = shutil.which("gfortran")
+    if gfortran:
+        dirs.append(str(Path(gfortran).parent))
+    # Common locations
+    for candidate in [
+        r"C:\Strawberry\c\bin",
+        r"C:\msys64\mingw64\bin",
+        r"C:\mingw64\bin",
+    ]:
+        if Path(candidate).is_dir():
+            dirs.append(candidate)
+    # Conda environment
+    conda_prefix = os.environ.get("CONDA_PREFIX")
+    if conda_prefix:
+        lib_dir = Path(conda_prefix) / "Library" / "bin"
+        if lib_dir.is_dir():
+            dirs.append(str(lib_dir))
+    return dirs
+
+
+class CandeEngine:
+    """Wrapper around the CANDE FEA engine compiled via f2py.
+
+    Usage::
+
+        engine = CandeEngine(work_dir="path/to/working/directory")
+        result = engine.run("my_problem")
+        # Reads my_problem.cid, writes my_problem.out in work_dir
+
+    Parameters
+    ----------
+    work_dir : str or Path, optional
+        Working directory where .cid input files live and output files
+        will be written. Defaults to current directory.
+    """
+
+    def __init__(self, work_dir: Optional[str | Path] = None):
+        self.work_dir = Path(work_dir) if work_dir else Path.cwd()
+
+    def run(self, prefix: str) -> "CandeResult":
+        """Run a CANDE analysis.
+
+        Parameters
+        ----------
+        prefix : str
+            File prefix (without extension). The engine will read
+            ``{prefix}.cid`` and produce ``{prefix}.out`` and other
+            output files in the working directory.
+
+        Returns
+        -------
+        CandeResult
+            Object with paths to all output files and the return code.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the input .cid file does not exist.
+        RuntimeError
+            If the Fortran engine returns a nonzero error code.
+        """
+        cid_file = self.work_dir / f"{prefix}.cid"
+        if not cid_file.exists():
+            raise FileNotFoundError(f"Input file not found: {cid_file}")
+
+        # Import the f2py-compiled extension
+        try:
+            from cande_wrapper._cande import run_cande
+        except ImportError:
+            # On Windows, gfortran runtime DLLs may not be on PATH.
+            # Try adding common gfortran bin directories.
+            if os.name == "nt":
+                for gfortran_dir in _find_gfortran_dirs():
+                    os.add_dll_directory(gfortran_dir)
+                try:
+                    from cande_wrapper._cande import run_cande
+                except ImportError as e:
+                    raise ImportError(
+                        "CANDE Fortran extension DLL load failed. "
+                        "Ensure gfortran runtime DLLs (libgfortran-5.dll) "
+                        "are on PATH or install via conda."
+                    ) from e
+            else:
+                raise ImportError(
+                    "CANDE Fortran extension not found. "
+                    "Build it with: pip install -e . "
+                    "(requires gfortran and numpy)"
+                )
+
+        # CANDE reads/writes files relative to CWD, so we chdir
+        original_dir = os.getcwd()
+        try:
+            os.chdir(self.work_dir)
+            ierror = run_cande(prefix)
+        finally:
+            os.chdir(original_dir)
+
+        if ierror != 0:
+            raise RuntimeError(
+                f"CANDE engine returned error code {ierror}. "
+                f"Check {prefix}.out and {prefix}.log for details."
+            )
+
+        return CandeResult(self.work_dir, prefix)
+
+    def check_input(self, prefix: str) -> bool:
+        """Validate that a .cid input file exists and is readable.
+
+        Parameters
+        ----------
+        prefix : str
+            File prefix (without extension).
+
+        Returns
+        -------
+        bool
+            True if the input file exists.
+        """
+        return (self.work_dir / f"{prefix}.cid").exists()
+
+
+class CandeResult:
+    """Container for CANDE analysis output file paths.
+
+    Attributes
+    ----------
+    prefix : str
+        The file prefix used for this run.
+    output_file : Path
+        Path to the main .out output file.
+    log_file : Path
+        Path to the .log file.
+    toc_file : Path
+        Path to the .ctc table-of-contents file.
+    """
+
+    def __init__(self, work_dir: Path, prefix: str):
+        self.prefix = prefix
+        self.work_dir = work_dir
+        self.output_file = work_dir / f"{prefix}.out"
+        self.log_file = work_dir / f"{prefix}.log"
+        self.toc_file = work_dir / f"{prefix}.ctc"
+
+    @property
+    def output_text(self) -> str:
+        """Read and return the full output file contents."""
+        return self.output_file.read_text()
+
+    def __repr__(self) -> str:
+        return f"CandeResult(prefix={self.prefix!r}, output={self.output_file})"

cande_wrapper-0.0.1/src/cande_wrapper.egg-info/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: cande-wrapper
+Version: 0.0.1
+Summary: Placeholder for the CANDE FEA culvert analysis engine
+Requires-Python: >=3.10

cande_wrapper-0.0.1/src/cande_wrapper.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/cande_wrapper/__init__.py
+src/cande_wrapper/engine.py
+src/cande_wrapper.egg-info/PKG-INFO
+src/cande_wrapper.egg-info/SOURCES.txt
+src/cande_wrapper.egg-info/dependency_links.txt
+src/cande_wrapper.egg-info/top_level.txt
+tests/test_engine.py
+tests/test_integration.py
+tests/test_result.py

cande_wrapper-0.0.1/src/cande_wrapper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cande_wrapper-0.0.1/src/cande_wrapper.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+cande_wrapper
+fortran

cande_wrapper-0.0.1/tests/test_engine.py

@@ -0,0 +1,92 @@
+"""Unit tests for CandeEngine."""
+
+import os
+from pathlib import Path
+
+import pytest
+
+from cande_wrapper.engine import CandeEngine
+
+
+class TestCandeEngineInit:
+    def test_default_workdir(self):
+        engine = CandeEngine()
+        assert engine.work_dir == Path.cwd()
+
+    def test_custom_workdir_string(self, tmp_path):
+        engine = CandeEngine(work_dir=str(tmp_path))
+        assert engine.work_dir == tmp_path
+
+    def test_custom_workdir_path(self, tmp_path):
+        engine = CandeEngine(work_dir=tmp_path)
+        assert engine.work_dir == tmp_path
+
+
+class TestCheckInput:
+    def test_exists(self, tmp_workdir):
+        engine = CandeEngine(work_dir=tmp_workdir)
+        assert engine.check_input("MGK-IO") is True
+
+    def test_missing(self, tmp_path):
+        engine = CandeEngine(work_dir=tmp_path)
+        assert engine.check_input("nonexistent") is False
+
+
+class TestRun:
+    def test_missing_cid_raises(self, tmp_path):
+        engine = CandeEngine(work_dir=tmp_path)
+        with pytest.raises(FileNotFoundError, match="Input file not found"):
+            engine.run("nonexistent")
+
+    def test_missing_extension_raises(self, tmp_workdir, monkeypatch):
+        """Simulates missing _cande extension by blocking the import."""
+        import sys
+
+        # Remove cached module and make it unimportable
+        monkeypatch.setitem(sys.modules, "cande_wrapper._cande", None)
+
+        engine = CandeEngine(work_dir=tmp_workdir)
+        with pytest.raises(ImportError):
+            engine.run("MGK-IO")
+
+    def test_success_returns_result(self, tmp_workdir, mock_fortran):
+        # Create the .out file that CandeResult expects
+        (tmp_workdir / "MGK-IO.out").write_text("NORMAL EXIT FROM CANDE")
+        (tmp_workdir / "MGK-IO.log").write_text("")
+        (tmp_workdir / "MGK-IO.ctc").write_text("")
+
+        engine = CandeEngine(work_dir=tmp_workdir)
+        result = engine.run("MGK-IO")
+
+        mock_fortran.run_cande.assert_called_once_with("MGK-IO")
+        assert result.prefix == "MGK-IO"
+        assert result.output_file == tmp_workdir / "MGK-IO.out"
+
+    def test_engine_error_raises(self, tmp_workdir, mock_fortran):
+        mock_fortran.run_cande.return_value = 1
+
+        engine = CandeEngine(work_dir=tmp_workdir)
+        with pytest.raises(RuntimeError, match="error code 1"):
+            engine.run("MGK-IO")
+
+    def test_restores_cwd_on_success(self, tmp_workdir, mock_fortran):
+        original = os.getcwd()
+        engine = CandeEngine(work_dir=tmp_workdir)
+        engine.run("MGK-IO")
+        assert os.getcwd() == original
+
+    def test_restores_cwd_on_error(self, tmp_workdir, mock_fortran):
+        mock_fortran.run_cande.return_value = 1
+        original = os.getcwd()
+        engine = CandeEngine(work_dir=tmp_workdir)
+        with pytest.raises(RuntimeError):
+            engine.run("MGK-IO")
+        assert os.getcwd() == original
+
+    def test_restores_cwd_on_exception(self, tmp_workdir, mock_fortran):
+        mock_fortran.run_cande.side_effect = Exception("boom")
+        original = os.getcwd()
+        engine = CandeEngine(work_dir=tmp_workdir)
+        with pytest.raises(Exception, match="boom"):
+            engine.run("MGK-IO")
+        assert os.getcwd() == original

cande_wrapper-0.0.1/tests/test_integration.py

@@ -0,0 +1,39 @@
+"""Integration tests that require the compiled Fortran extension.
+
+Run with: pytest -m integration
+These are skipped by default in normal test runs.
+"""
+
+import shutil
+from pathlib import Path
+
+import pytest
+
+from cande_wrapper.engine import CandeEngine
+
+EXAMPLE_DATA = Path(__file__).parent / "example_data"
+
+
+@pytest.mark.integration
+class TestIntegration:
+    def test_run_example_problem(self, tmp_path):
+        """Run the MGK-IO example and verify CANDE completes normally."""
+        shutil.copy2(EXAMPLE_DATA / "MGK-IO.cid", tmp_path / "MGK-IO.cid")
+
+        engine = CandeEngine(work_dir=tmp_path)
+        result = engine.run("MGK-IO")
+
+        assert result.output_file.exists()
+        output = result.output_text
+        assert "NORMAL EXIT FROM CANDE" in output
+
+    def test_output_files_created(self, tmp_path):
+        """Verify all expected output files are created."""
+        shutil.copy2(EXAMPLE_DATA / "MGK-IO.cid", tmp_path / "MGK-IO.cid")
+
+        engine = CandeEngine(work_dir=tmp_path)
+        result = engine.run("MGK-IO")
+
+        assert result.output_file.exists()
+        assert result.log_file.exists()
+        assert result.toc_file.exists()

cande_wrapper-0.0.1/tests/test_result.py

@@ -0,0 +1,36 @@
+"""Unit tests for CandeResult."""
+
+from pathlib import Path
+
+from cande_wrapper.engine import CandeResult
+
+
+class TestCandeResult:
+    def test_paths(self, tmp_path):
+        result = CandeResult(tmp_path, "EX1")
+        assert result.output_file == tmp_path / "EX1.out"
+        assert result.log_file == tmp_path / "EX1.log"
+        assert result.toc_file == tmp_path / "EX1.ctc"
+
+    def test_prefix(self, tmp_path):
+        result = CandeResult(tmp_path, "test_problem")
+        assert result.prefix == "test_problem"
+
+    def test_repr(self, tmp_path):
+        result = CandeResult(tmp_path, "EX1")
+        r = repr(result)
+        assert "EX1" in r
+        assert "CandeResult" in r
+
+    def test_output_text(self, tmp_path):
+        (tmp_path / "EX1.out").write_text("line 1\nline 2\n")
+        result = CandeResult(tmp_path, "EX1")
+        assert result.output_text == "line 1\nline 2\n"
+
+    def test_output_text_missing_file(self, tmp_path):
+        result = CandeResult(tmp_path, "EX1")
+        try:
+            _ = result.output_text
+            assert False, "Should have raised FileNotFoundError"
+        except FileNotFoundError:
+            pass