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. Extraction Settings (extraction)¶

This object controls which data is extracted from simulation results. All flags default to true except SAPD which defaults to false.

Example:

{
    "extraction": {
        "sar": true,
        "power_balance": true,
        "sapd": false,
        "point_sensors": true
    }
}

Backward Compatibility: Legacy top-level keys (extract_sar, extract_power_balance, extract_sapd) are still supported but deprecated. The new extraction.* structure takes precedence.

3. 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"]
}

4. Simulation Parameters (simulation_parameters)¶

These settings control the core behavior of the FDTD solver.

| sapd_mesh_slicing_side_length_mm | number | 100.0 | Side length in mm for the mesh slicing box around the peak SAR location for faster SAPD calculation. | | sapd_slicing_side_length_mm | number | 100.0 | Side length in mm for the H5 data slicing box around the peak SAR location to optimize extraction speed. |

Overall Field Sensor Configuration (overall_field_sensor)¶

This object controls the overall field sensor that records E-field and H-field data during the simulation. By default, Sim4Life uses its built-in defaults. Configuring this explicitly allows you to control exactly which fields are recorded.

Example: Record only E-field in frequency domain (default, smallest output)

"simulation_parameters": {
    "overall_field_sensor": {
        "enabled": true,
        "record_e_field": true,
        "record_h_field": false,
        "recording_domain": "frequency"
    }
}

Example: Record both E and H fields (needed for Poynting vector / SAPD)

"simulation_parameters": {
    "overall_field_sensor": {
        "enabled": true,
        "record_e_field": true,
        "record_h_field": true,
        "recording_domain": "frequency"
    }
}

5. Gridding Parameters (gridding_parameters)¶

These settings define the spatial discretization of the simulation domain.

[!NOTE] Near-field symmetry reduction: axis depends on placement

For near-field simulations, the symmetry cut adapts to where the phone actually is: - Head placements (by_cheek, front_of_eyes): cuts at x = 0, keeping the positive-x (right) side — the side the phone is on, since the Ear_skin entity sits at positive x. - Trunk placements (by_belly): cuts at y = 0, keeping the positive-y (front) side — where the belly and the phone face.

Far-field always cuts at x = 0 regardless of placement direction.

6. Solver and Miscellaneous Settings¶

Example: Line Profiling

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

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

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

Auto-induced exposure (auto_induced)¶

Auto-induced exposure simulates the worst-case scenario where a MaMIMO base station focuses its beams onto a human through beamforming. After all environmental simulations complete for each (phantom, frequency) pair, GOLIAT can optionally combine the results with optimal phase weights to find the worst-case SAPD.

Example: Enable auto-induced exposure with air-based search

{
    "auto_induced": {
        "enabled": true,
        "top_n": 10,
        "cube_size_mm": 50,
        "search": {
            "mode": "air",
            "n_samples": 10000,
            "shell_size_mm": 10.0,
            "selection_percentile": 95.0,
            "min_candidate_distance_mm": 50.0,
            "random_seed": 42,
            "low_memory_mode": null
        }
    }
}

Example: Legacy skin-based search (for comparison)

{
    "auto_induced": {
        "enabled": true,
        "top_n": 10,
        "cube_size_mm": 100,
        "search_metric": "E_z_magnitude",
        "search": {
            "mode": "skin"
        }
    }
}

Important notes:

• Physical correctness: The "air" mode models how MaMIMO beamforming actually works (beam focused in air, illuminating body). The "skin" mode is legacy and physically incorrect.
• Symmetry reduction incompatibility: Do not use phantom_bbox_reduction.use_symmetry_reduction: true with auto-induced exposure. Symmetry reduction cuts the bounding box at x=0, keeping only one half of the body - you'd miss half the skin surface and cannot find the true worst-case focus point.
• Results location: Auto-induced results are saved to results/far_field/{phantom}/{freq}MHz/auto_induced/auto_induced_summary.json.
• Caching: The analysis is skipped if the summary file exists and is newer than all _Output.h5 files.
• Performance: Air-based search with n_samples=100 typically takes 5-10 minutes per (phantom, freq) pair on a modern CPU.

8. 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.

9. 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

10. Accessing Configuration in Code¶

The Config class supports dictionary-style access with dot-notation for nested paths:

# Simple top-level access
sim_params = config["simulation_parameters"] or {}
antenna_config = config["antenna_config"] or {}

# Nested path access
excitation_type = config["simulation_parameters.excitation_type"] or "Harmonic"
gridding_params = config["gridding_parameters"] or {}

# With fallback values
expansion = config["simulation_parameters.freespace_antenna_bbox_expansion_mm"] or [10, 10, 10]

Note: The or operator provides a fallback when a key doesn't exist (returns None). This is the standard pythonic pattern.

Accessing Complex Structures¶

For accessing nested dictionaries within config values:

# Get a top-level dict, then access nested keys
placement_scenarios = config["placement_scenarios"] or {}
scenario = placement_scenarios.get("by_cheek") if isinstance(placement_scenarios, dict) else None

# Or use dot notation directly
scenario = config["placement_scenarios.by_cheek"]

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.