Developer Guide¶
This guide is for developers extending or maintaining GOLIAT. It covers the codebase structure, testing, and contribution process. GOLIAT is modular Python code interfacing with Sim4Life for EMF simulations.
Codebase structure¶
GOLIAT's architecture separates concerns:
- goliat/config.py: Loads JSON configs with inheritance (e.g., base + study-specific).
- goliat/studies/: Orchestrates workflows (NearFieldStudy, FarFieldStudy inherit from BaseStudy).
- goliat/setups/: Builds Sim4Life scenes (PhantomSetup, PlacementSetup, MaterialSetup, etc.). See Sim4Life API snippets for API patterns used.
- goliat/project_manager.py: Handles .smash files (create/open/save/close), including a "Verify and Resume" feature to avoid re-running simulations with unchanged configurations.
- goliat/simulation_runner.py: Executes simulations (local iSolve or oSPARC cloud).
- goliat/results_extractor.py: Extracts SAR/power data post-simulation.
- goliat/analysis/: Aggregates results (Analyzer with strategies for near/far-field). Includes paper generation via
cli/generate_paper.py. - goliat/gui_manager.py: Multiprocessing GUI for progress/ETA.
- goliat/logging_manager.py: Dual loggers (progress/verbose) with colors.
- goliat/profiler.py: Tracks phases (setup/run/extract) for ETAs.
- goliat/utils.py: Helpers (format_time, non_blocking_sleep, simple Profiler).
Key flow: Config → BaseStudy.run() → Setups → Runner → Extractor → Analyzer. For more details on the high-level architecture, see the Technical Guide.
Installation¶
For development, use editable installation from the repository. Users can install from PyPI instead. See the installation guide for both options.
Developer setup:
- Clone the repository:
- Set up Sim4Life Python environment:
- Install GOLIAT package in editable mode (or in a venv):
Always use
python -m pip: Always usepython -m pipinstead ofpipdirectly. This ensures you're using the pip associated with Sim4Life's Python interpreter. The same applies to other Python commands: usepython -m <module>when possible.
- Run the initialization command:
This will: - Verify Sim4Life Python interpreter is being used - Prepare data files (phantoms, antennas)
Benefits of editable install: - Code modifications are immediately reflected (no reinstall needed) - Better IDE support and autocomplete - Full repository access (scripts, tests, docs) - Can contribute to development
Note: If you need to reinstall (e.g., after pulling updates), you can manually run:
GOLIAT uses pytest for testing, with tests located in the tests/ directory.
Handling the s4l_v1 dependency¶
Much of the codebase requires s4l_v1, a proprietary library available only within the Sim4Life Python environment on Windows. This prevents tests that rely on it from running in the Linux-based CI environment.
To manage this, tests requiring s4l_v1 are marked with @pytest.mark.skip_on_ci. The CI pipeline is configured to exclude these marked tests, allowing it to validate platform-independent code while avoiding environment-specific failures.
Local testing setup¶
To run the complete test suite, your local development environment must use the Sim4Life Python interpreter.
VS Code Configuration¶
- Open the Command Palette (
Ctrl+Shift+P). - Run the
Python: Select Interpretercommand. - Select
+ Enter interpreter path...and find thepython.exein your Sim4Life installation directory (e.g.,C:\Program Files\Sim4Life_8.2.0.16876\Python\python.exe). This configures VS Code to use the correct interpreter, which includes thes4l_v1library.
Running tests locally¶
With the interpreter set, run the full test suite from the terminal.
- First-time Setup: Run
goliat initto install dependencies and set up the environment. Alternatively, run any command (e.g.,goliat --help) and accept the dependency installation prompt when asked. - Run Pytest:
Adding new tests¶
- If a new test depends on
s4l_v1(or imports a module that does), it must be decorated with@pytest.mark.skip_on_ci. - If a test is self-contained and has no Sim4Life dependencies, it does not need the marker.
import pytest
from goliat.utils import format_time # This module has s4l_v1 dependencies
# This test requires the Sim4Life environment and will be skipped on CI.
@pytest.mark.skip_on_ci
def test_a_function_that_needs_s4l():
# ... test logic ...
pass
# This test is self-contained and will run everywhere.
def test_a_self_contained_function():
assert 2 + 2 == 4
Extending the framework¶
Adding a new setup¶
To add a custom source (e.g., dipole):
- Create
goliat/setups/dipole_setup.pyinheriting BaseSetup. - Implement
run_full_setup(): Load dipole CAD, position. - Update NearFieldStudy/FarFieldStudy to use it (e.g., if "study_type": "dipole").
- Add to config schema in config.py.
Example in dipole_setup.py:
Contribution workflow¶
- Fork the repo.
- Create branch:
git checkout -b feature/new-setup. - Code: Follow style (Ruff-formatted, type hints).
- Test locally:
pytest. - Commit:
git commit -m "Add dipole setup". - PR to main: Describe changes, reference issues.
PR requirements: - Run pre-commit: pre-commit run --all-files. - Tests: Add for new features. - Docs: Update user_guide.md if user-facing.
Building docs¶
To build the documentation, you first need to install the documentation-specific dependencies.
Then, you can use MkDocs to serve the documentation locally or build the static site.
# Serve the docs locally
mkdocs serve # Local server at http://127.0.0.1:8000
# Build the static site
mkdocs build # Outputs to site/
Code style¶
- Formatting & Linting: Ruff (replaces Black, flake8, isort).
- Type Checking: Pyright.
- Types: Use typing (e.g.,
Dict[str, Any]). - Docs: Google-style docstrings.
Pre-commit hook (install: pre-commit install):
# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.14.2 # Or newer
hooks:
- id: ruff-format
- id: ruff
args: [--fix]
- repo: https://github.com/RobertCraigie/pyright-python
rev: v1.1.407 # Or newer
hooks:
- id: pyright
Run: pre-commit run.
Other notes¶
- Dependencies: Defined in
pyproject.toml(PEP 621 standard). - Gitignore: Ignore logs/, results/, .env.
- License: Apache-2.0 - see LICENSE.
- Changelog: Update CHANGELOG.md for releases.
- Version management: Version is stored in
pyproject.toml([project] version) as the single source of truth. The package reads it viaimportlib.metadatawhen installed, or frompyproject.tomldirectly when running from source.
Analysis system¶
GOLIAT's analysis system aggregates results from multiple simulations and generates reports, plots, and publications. The goliat analyze command processes all simulation outputs in a study, computes statistics, and creates visualizations.
What it does: - Loads SAR data from all completed simulations in a study - Aggregates metrics by frequency, scenario, and tissue group - Generates statistical summaries (mean, median, percentiles, correlations) - Creates publication-ready plots (heatmaps, bar charts, boxplots, 3D visualizations) - Exports CSV files with detailed and summary data - Optionally generates LaTeX papers with all figures organized by section
How it works: The system uses a strategy pattern (BaseAnalysisStrategy) with separate implementations for near-field and far-field analysis. The Analyzer coordinates data loading and processing, while specialized Plotter modules handle visualization. Results are cached to speed up re-plotting. See the Analysis Guide for detailed documentation covering:
- User-facing usage (commands, configuration, output structure)
- Developer-facing architecture (components, data flow, extending the system)
- Paper generation workflow
Generated LaTeX result reports are local analysis artifacts. Curated publication manuscripts and their source packages are kept under papers/.
For more, see Contributing. For a deep dive into all available parameters, refer to the Configuration Guide. For a complete reference of all features, see the Full List of Features.