Running & Analysis#

Run simulations on cloud GPUs and analyze the results.

Simulation#

hyperwave_community.simulate(structure_recipe, source_field, source_offset, freq_band, monitors_recipe, mode_info=None, simulation_steps=20000, check_every_n=1000, source_ramp_periods=5.0, add_absorption=True, absorption_widths=(60, 40, 40), absorption_coeff=0.0001, api_key=None, convergence='default', gpu_type='B200')#

Run FDTD simulation on cloud GPU using structure recipe and monitors recipe.

This function is for the LOCAL WORKFLOW where you create the structure, monitors, and source field locally using JAX, then send them to the cloud for GPU-accelerated FDTD simulation.

Parameters:

  • structure_recipe (Dict[str, Any]) – Recipe dict from structure.extract_recipe().

  • source_field – Source field array (JAX or numpy) of shape (num_freqs, 6, x, y, z).

  • source_offset (Tuple[int, int, int]) – (x, y, z) position offset for source placement.

  • freq_band (Tuple[float, float, int]) – Frequency band tuple (omega_min, omega_max, num_freqs).

  • monitors_recipe (List[Dict]) – Recipe list from monitors.recipe property.

  • mode_info (Optional[Dict]) – Optional mode information dictionary from create_mode_source.

  • simulation_steps (int) – Maximum FDTD time steps (default: 20000).

  • check_every_n (int) – Steps between convergence checks (default: 1000).

  • source_ramp_periods (float) – Source ramp-up periods (default: 5.0).

  • add_absorption (bool) – Whether to add absorbing boundaries (default: True).

  • absorption_widths (Tuple[int, int, int]) – Absorber widths (x, y, z) in pixels (default: (60, 40, 40)).

  • absorption_coeff (float) – Absorption coefficient (default: 1e-4).

  • api_key (Optional[str]) – API key for authentication. If None, uses configured API key.

  • convergence (Optional[str]) – Early stopping preset (“quick”, “default”, “thorough”, “full”).

  • gpu_type (str) – GPU type for simulation (default: “B200”).

Returns:

  • monitor_data: Dict mapping monitor names to field arrays

  • sim_time: GPU simulation time in seconds

  • performance: Grid points × steps per second

  • converged: Whether simulation converged early

  • convergence_step: Step at which convergence was reached (if applicable)

Return type:

Dictionary with simulation results including

Example:

results = hwc.simulate(
    structure_recipe=structure.extract_recipe(),
    source_field=source_field,
    source_offset=source_offset,
    freq_band=freq_band,
    monitors_recipe=monitors.recipe,
    mode_info=mode_info,
    simulation_steps=20000,
    absorption_widths=abs_widths,
    absorption_coeff=abs_coeff,
)

Results I/O#

hyperwave_community.save_results(results, path='results.npz')#

Save simulation results to a compressed .npz file.

Stores all monitor field arrays, monitor names, and simulation metadata so results can be reloaded for analysis without re-running the simulation.

Parameters:

  • results (dict) – Dict returned by simulate() with keys like 'monitor_data', 'monitor_names', 'sim_time', etc.

  • path (str) – Destination file path (default “results.npz”).

Return type:

str

Returns:

Absolute path of the saved file.

Example:

hwc.save_results(results, "quickstart_results.npz")
hyperwave_community.load_results(path)#

Load simulation results from a .npz file saved by save_results.

Reconstructs the same dict structure returned by simulate().

Parameters:

path (str) – Path to the .npz file.

Return type:

dict

Returns:

Dict matching the simulate() return format.

Example:

results = hwc.load_results("quickstart_results.npz")

Analysis#

hyperwave_community.analyze_transmission(results, input_monitor='Input_o1', output_monitors=None, direction='x', print_results=True)#

Analyze transmission from simulation results.

Computes transmission coefficients for each output monitor relative to the input monitor using Poynting vector power flow.

Parameters:

  • results (Dict[str, Any]) – Simulation results from run_simulation()

  • input_monitor (str) – Name of input monitor

  • output_monitors (List[str]) – List of output monitor names. If None, auto-detects monitors starting with Output_

  • direction (str) – Direction of power flow for Poynting vector (‘x’, ‘y’, ‘z’)

  • print_results (bool) – If True, print formatted results table

Returns:

  • ‘power_in’: Input power

  • ’transmissions’: Dict mapping monitor name to transmission value

  • ’total_transmission’: Sum of all output transmissions

  • ’excess_loss_dB’: Excess loss in dB (10*log10(total))

Return type:

Dictionary with

Example:

transmission = hwc.analyze_transmission(
    results, input_monitor="Input_o1", direction="x",
)