GOLIAT Configuration Guide¶

GOLIAT uses a hierarchical JSON configuration system to define all aspects of a simulation study. This modular approach allows for flexibility and reproducibility. A study-specific configuration file (e.g., near_field_config.json) inherits settings from a base_config.json file, allowing you to override only the parameters you need for a specific study.

This guide provides a comprehensive reference for all available configuration parameters, their purpose, and valid values.

Configuration Hierarchy¶

The system is designed to avoid repetition by allowing configurations to "extend" a base file. The child's values will always override the parent's.

graph TD
    base[base_config.json<br/>Shared settings]
    nf[near_field_config.json<br/>Near-field specifics]
    ff[far_field_config.json<br/>Far-field specifics]

    base -->|extends| nf
    base -->|extends| ff

    style base fill:#4CAF50
    style nf fill:#2196F3
    style ff fill:#2196F3

To create a custom study, you can copy an existing configuration and modify it. For example, to create my_study.json:

{
  "extends": "near_field_config.json",
  "phantoms": ["thelonious"],
  "frequencies_mhz": [900]
}

1. Core Settings (base_config.json)¶

These are the foundational settings shared across all study types.

2. Execution Control (execution_control)¶

This object controls which phases of the workflow are executed. This is useful for re-running specific parts of a study, such as only extracting results from an already completed simulation.

The do_setup flag directly controls the project file (.smash) handling. Its behavior is summarized below:

Example: Extraction-Only Workflow

"execution_control": {
  "do_setup": false,
  "do_run": false,
  "do_extract": true
}

Example: Aggressive Cleanup in a Serial Workflow

"execution_control": {
  "do_setup": true,
  "do_run": true,
  "do_extract": true,
  "auto_cleanup_previous_results": ["output", "input"]
}

3. Simulation Parameters (simulation_parameters)¶

These settings control the core behavior of the FDTD solver.

4. Gridding Parameters (gridding_parameters)¶

These settings define the spatial discretization of the simulation domain.

5. Solver and Miscellaneous Settings¶

Example: Line Profiling

"line_profiling": {
  "enabled": true,
  "subtasks": {
    "setup_simulation": ["src.setups.base_setup.BaseSetup._finalize_setup"]
  }
}

6. Far-Field Specifics (far_field_config.json)¶

These settings are unique to far-field (environmental exposure) studies.

7. Near-Field Specifics (near_field_config.json)¶

These settings are unique to near-field (device exposure) studies.

Antenna Configuration (antenna_config)¶

This object defines all antenna-specific information, with a separate entry for each frequency.

Placement Scenarios (placement_scenarios)¶

This object defines the different device placements to be simulated.

Phantom Definitions (phantom_definitions)¶

This object contains phantom-specific settings, such as which placements to run and the separation distances.

8. Credentials and Data¶

For security and portability, certain information is handled outside the main configuration files.

oSPARC Credentials¶

oSPARC API credentials should be stored in a .env file in the project root directory.

# .env file
OSPARC_API_KEY=your_osparc_api_key
OSPARC_API_SECRET=your_osparc_api_secret

Phantom Downloads¶

Some phantom models require an email address for download, which can also be set in the .env file. This should be the email associated with your institution's Sim4Life license.

# .env file
DOWNLOAD_EMAIL=your_email@example.com

This comprehensive structure ensures that every aspect of a GOLIAT simulation is controllable, reproducible, and easy to manage. For more workflow-oriented information, please see the User Guide.