Dev

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Build Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+
+    - name: Install Sphinx
+      run: |
+        python -m pip install --upgrade pip
+        pip install sphinx sphinx-rtd-theme
+
+    - name: Build documentation
+      run: |
+        cd documentation
+        make html
+
+    - name: Upload documentation artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation
+        path: documentation/build/html/
+        retention-days: 7
+
+  deploy-docs:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build-docs
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+
+    - name: Install Sphinx
+      run: |
+        python -m pip install --upgrade pip
+        pip install sphinx sphinx-rtd-theme
+
+    - name: Build documentation
+      run: |
+        cd documentation
+        make html
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./documentation/build/html

.github/workflows/release.yml

@@ -0,0 +1,125 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Setup Conda
+      uses: conda-incubator/setup-miniconda@v3
+      with:
+        auto-update-conda: true
+        python-version: 3.9
+
+    - name: Install dependencies
+      shell: bash -l {0}
+      run: |
+        conda env create -f environment.yml
+        conda activate gulls
+        conda list
+
+    - name: Configure CMake
+      shell: bash -l {0}
+      run: |
+        conda activate gulls
+        cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+
+    - name: Build
+      shell: bash -l {0}
+      run: |
+        conda activate gulls
+        cmake --build build --parallel
+
+    - name: Run smoke tests and generate plots
+      shell: bash -l {0}
+      run: |
+        conda activate gulls
+        # Run smoke tests to generate plots
+        python smoke_test/run_smoke_test.py --ci --exec-timeout 610
+
+        # Create plots directory for release
+        mkdir -p release_plots
+
+        # Copy all generated plots to release directory
+        find smoke_test/output -name "*.png" -exec cp {} release_plots/ \;
+
+        # List what we found
+        echo "Generated plots for release:"
+        ls -la release_plots/
+
+
+    - name: Build documentation
+      shell: bash -l {0}
+      run: |
+        conda activate gulls
+        cd documentation
+        make html
+
+    - name: Create release archive
+      run: |
+        # Create source archive
+        git archive --format=tar.gz --prefix=gulls-${{ github.ref_name }}/ -o gulls-${{ github.ref_name }}.tar.gz HEAD
+
+        # Create binary archive with GSL fallback warning
+        echo "⚠️  WARNING: Binaries include GSL fallback implementations" > BINARY_WARNING.txt
+        echo "These are for testing/CI only and NOT suitable for production science." >> BINARY_WARNING.txt
+        echo "For production use, compile from source with licensed Numerical Recipes." >> BINARY_WARNING.txt
+        echo "" >> BINARY_WARNING.txt
+        echo "See documentation for details on replacing GSL stubs with Numerical Recipes." >> BINARY_WARNING.txt
+
+        tar -czf gulls-${{ github.ref_name }}-binaries.tar.gz bin/ documentation/build/html/ release_plots/ BINARY_WARNING.txt
+
+    - name: Generate plot assets and release notes
+      shell: bash -l {0}
+      run: |
+        # Create a list of plots for the release notes
+        echo "## Smoke Test Results" > PLOT_NOTES.md
+        echo "" >> PLOT_NOTES.md
+        echo "This release was validated with automated smoke tests. The plots below show sample lightcurves generated by the different Gulls executables:" >> PLOT_NOTES.md
+        echo "" >> PLOT_NOTES.md
+
+        # Add each plot to the release notes with full GitHub URLs
+        for plot in release_plots/*.png; do
+          if [ -f "$plot" ]; then
+            plot_name=$(basename "$plot")
+            echo "### $plot_name" >> PLOT_NOTES.md
+            echo "![$plot_name](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/$plot_name)" >> PLOT_NOTES.md
+            echo "" >> PLOT_NOTES.md
+          fi
+        done
+
+        # Show what we generated
+        echo "Generated plot notes:"
+        cat PLOT_NOTES.md
+
+        # Use RELEASE_NOTES.md if it exists, otherwise create default release body
+        if [ -f "RELEASE_NOTES.md" ]; then
+          echo "Using existing RELEASE_NOTES.md file"
+        else
+          echo "No RELEASE_NOTES.md found, falling back to default release body"
+        fi
+        python scripts/build_release_body.py --release-notes RELEASE_NOTES.md --plots PLOT_NOTES.md --output RELEASE_BODY.md
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: |
+          gulls-${{ github.ref_name }}.tar.gz
+          gulls-${{ github.ref_name }}-binaries.tar.gz
+          release_plots/*.png
+        body_path: RELEASE_BODY.md
+        generate_release_notes: false
+        draft: false
+        prerelease: false
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,57 @@
+name: Test Suite
+
+on:
+  push:
+    branches: [ main, dev, feature/documentation-and-testing ]
+  pull_request:
+    branches: [ main, dev ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        build_type: [Debug, Release]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Conda
+      uses: conda-incubator/setup-miniconda@v3
+      with:
+        auto-update-conda: true
+        python-version: 3.9
+
+    - name: Install dependencies
+      shell: bash -l {0}
+      run: |
+        conda env create -f environment.yml
+        conda activate gulls
+        conda list
+
+    - name: Configure CMake
+      shell: bash -l {0}
+      run: |
+        conda activate gulls
+        cmake -S . -B build -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+
+    - name: Build
+      shell: bash -l {0}
+      run: |
+        conda activate gulls
+        cmake --build build --parallel
+
+    - name: Run smoke tests (CI subset)
+      shell: bash -l {0}
+      run: |
+        conda activate gulls
+        python3 smoke_test/run_smoke_test.py --ci --exec-timeout 610
+
+    - name: Upload test artifacts on failure
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: test-outputs-${{ matrix.os }}-${{ matrix.build_type }}
+        path: smoke_test/output/
+        retention-days: 7

.gitignore

@@ -38,9 +38,40 @@ src/classes/random.cpp
 src/classes/zroots2.cpp
 
 # VBM files
-src/ESPL.tbl
+# src/ESPL.tbl  # Now included in repo with Matt's permission
 
 # CMake artifacts
 build/
 build/CMakeFiles/
-build/.cmake
+build/.cmake
+
+# Smoke Tests
+smoke_test/output/
+smoke_test/__pycache__/
+smoke_test/parameterfiles/__generated__/
+
+# Documentation build artifacts
+docs/_build/
+docs/build/
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Documentation build artifacts
+documentation/_build/
+documentation/build/
+
+# PSF files (generated in workflow/smoke tests)
+smoke_test/assets/observatories/WFI_PSF.psf

CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [2.0.0] - 2025-10-20
+
+### Added
+- Comprehensive documentation expansion with Sphinx/Read the Docs
+- Input file format specifications and parameter reference
+- Validation system for input catalogs and configuration files
+- CI/CD pipeline with GitHub Actions
+- Smoke test suite for automated testing
+- CMake build system alongside traditional Makefile (includes `gulls_std`, `gulls_croin`, and `gullsFish`)
+- Contributing guidelines and development workflow
+- Example configurations and troubleshooting guides
+- Missing docs build requirements in the `environment.yml`
+- Smoke test output figures in Release Notes
+- PSF generation utilities (`generateMoffat`, `precompute_psf`, `generateMoffatPSF`) to CMake build
+- On-demand PSF file generation for smoke tests (no more 68MB files in git)
+- Smart PSF caching system that reuses existing files when available
+
+### Changed
+- Improved error handling and user feedback
+- Enhanced input validation with detailed error messages
+- Streamlined installation process with better dependency management
+- Updated documentation from legacy format to modern RST
+- Simplified release workflow: patch > edit changelog > release
+- PSF generation now uses proper subpixel sampling (9×9 = 81 variations)
+- Smoke tests generate PSF files on-demand instead of requiring pre-committed files
+
+### Fixed
+- Buffer overflow issues in path handling
+- Infinite loop bugs in random number generation
+- Uninitialized memory issues in binary source calculations
+- Off-by-one errors in catalog parsing
+- Failure to build docs in the release workflow on GitHub
+- PSF generation in CI environments (removed hardcoded local machine paths)
+- PSF file size issues (now generates proper 68MB files with subpixel sampling)
+- Simulation crashes due to missing or malformed PSF files
+
+### Security
+- Fixed potential buffer overflows in file path construction
+- Improved input validation to prevent malformed data crashes
+
+## [1.0.0] - 2013-2025
+
+### Added
+- Core microlensing simulation framework
+- Support for single and binary sources/lenses
+- Realistic observing conditions and detector effects
+- Multiple observatory and filter system support
+- Photometric signal generation
+- Lens orbital motion
+- Support for low-level VBMicrolensing functions
+- Detection statistics and survey planning tools
+- Fisher uncertainty estimation
+- Many other features, executables, and documentation evolutions
+
+
+
+### Original Development
+- Initial implementation by Matthew Penny and collaborators
+- Published in Penny et al. (2013, 2014, 2019)
+- Core algorithms for gravitational microlensing event simulation