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 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
Shared settings]
    nf[near_field_config.json
Near-field specifics]
    ff[far_field_config.json
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: Write input file without running solver

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

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": ["goliat.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.

Alternative orientation format for by_cheek phantom rotation

For the by_cheek scenario, an alternative dictionary format can be used to enable automatic phantom rotation towards the phone. This is useful for precise placement based on contact.

"orientations": {
  "cheek_base": {
    "rotate_phantom_to_cheek": true,
    "angle_offset_deg": 0
  }
}

• rotate_phantom_to_cheek: (boolean) If true, the phantom rotates on its Z-axis to touch the phone.
• angle_offset_deg: (number) An additional angle in degrees to rotate the phantom away from the phone after contact is detected.

Subgridding configuration

Subgridding allows specific antenna components to use a finer grid resolution than the global grid. This is configured in the antenna_config.{freq}.gridding.subgridding object:

{
  "antenna_config": {
    "700": {
      "gridding": {
        "subgridding": {
          "components": ["component1:Battery", "component1:Patch", "Extrude 1", "component1:ShortingPin"],
          "SubGridMode": "Box",
          "SubGridLevel": "x9",
          "AutoRefinement": "AutoRefinementVeryFine"
        }
      }
    }
  }
}

• components: (array of strings) List of component names to apply subgridding to. These components will use the subgrid resolution instead of the global or manual grid settings.
• SubGridMode: (string) The subgrid mode, typically "Box".
• SubGridLevel: (string) The subgrid level multiplier relative to the global grid. Common values: "x9" (9x finer), "x3" (3x finer). Higher values provide finer resolution but increase computation time.
• AutoRefinement: (string) The refinement level for subgridded components. Options: "AutoRefinementVeryFine", "AutoRefinementFine", "AutoRefinementDefault".

Subgridding overrides any manual gridding settings for the specified components. Components not listed in the components array use the global gridding strategy (automatic or manual) as configured.

Phantom definitions (phantom_definitions)¶

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

How reference point coordinates are derived:

The reference point coordinates (nasion, tragus, belly_button) are relative offsets, not absolute positions. They are calculated as offsets from geometrically derived centers:

• nasion: Offset from the center of the eye bounding box (calculated from Eye/Cornea entities)
• tragus: Offset from the center of the ear bounding box (calculated from Ear_skin entity)
• belly_button: Offset from the center of the trunk bounding box (calculated from Trunk_BBox entity)

These offsets are determined through anatomical landmark identification techniques and are added to the calculated geometric centers during placement. The coordinate system is consistent across all phantoms: X-axis extends from inside the head toward the right ear, Y-axis extends outward from the face, and Z-axis extends upward along the head.

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 structure makes every aspect of a GOLIAT simulation controllable, reproducible, and easy to manage. For more workflow-oriented information, please see the User Guide. For a complete list of all GOLIAT features, see the Full List of Features.