fdtdx.SimulationConfig

class fdtdx.SimulationConfig(*, time=null, grid=null, backend='gpu', dtype=<class 'jax.numpy.float32'>, use_complex_fields=None, courant_factor=0.99, gradient_config=None)

Bases: TreeClass

Configuration settings for FDTD simulations.

This class contains all the parameters needed to configure and run an FDTD simulation, including spatial and temporal discretization, hardware backend, and gradient computation settings.

Quick Reference

Attributes

• backend

• courant_factor

• courant_number

• dtype

• gradient_config

• grid

• has_nonuniform_grid

• invertible_optimization

• max_travel_distance

• only_forward

• resolved_grid

• time

• time_step_duration

• time_steps_total

• use_complex_fields

Methods

• aset

• get_class_fields

• get_public_fields

• resolve_grid

• uniform_spacing

Attributes

SimulationConfig.backend: Literal['gpu', 'tpu', 'cpu', 'METAL']

Computation backend (‘gpu’, ‘tpu’, ‘cpu’ or ‘METAL’). Defaults to “gpu”.

SimulationConfig.courant_factor: float

0.99).

Type:

Safety factor for the Courant condition (default

SimulationConfig.courant_number

Calculate the Courant number for the simulation.

The Courant number is a dimensionless quantity that determines stability of the FDTD simulation. It represents the ratio of the physical propagation speed to the numerical propagation speed.

Returns:

The Courant number, scaled by the courant_factor and normalized

for 3D simulations.

Return type:

float

SimulationConfig.dtype: dtype

Data type for numerical computations. Defaults to jnp.float32.

SimulationConfig.gradient_config: GradientConfig | None

Optional configuration for gradient computation.

SimulationConfig.grid: UniformGrid | RectilinearGrid

Spatial grid configuration.

UniformGrid is an unresolved policy used while the final volume shape is still being inferred. RectilinearGrid is the realized solver grid with explicit physical edge coordinates. Placement resolves policies to RectilinearGrid so compiled FDTD code has exactly one metric source.

SimulationConfig.has_nonuniform_grid

Whether the realized solver grid is non-uniform.

SimulationConfig.invertible_optimization

Check if invertible optimization is enabled.

Invertible optimization uses time-reversibility of Maxwell’s equations to compute gradients with reduced memory requirements compared to checkpointing-based methods.

Returns:

True if gradient computation uses invertible differentiation

(recorder is specified), False otherwise.

Return type:

bool

SimulationConfig.max_travel_distance

Calculate the maximum distance light can travel during the simulation.

This represents the theoretical maximum distance that light could travel through the simulation volume, useful for determining if the simulation time is sufficient for light to traverse the entire domain.

Returns:

Maximum travel distance in meters, based on the speed of light

and total simulation time.

Return type:

float

SimulationConfig.only_forward

Check if the simulation is forward-only (no gradient computation).

Forward-only simulations don’t compute gradients and are used when only the forward propagation of electromagnetic fields is needed, without optimization.

Returns:

True if no gradient configuration is specified, False otherwise.

Return type:

bool

SimulationConfig.resolved_grid

Return the concrete solver grid, or None if not yet resolved.

UniformGrid has no edge arrays until the simulation shape is known. Callers that need coordinates, areas, or volumes should use this property and fall back to uniform_spacing when it returns None.

SimulationConfig.time: float

Total simulation time in seconds.

SimulationConfig.time_step_duration

Calculate the duration of a single time step.

The time step duration is determined by the Courant condition to ensure numerical stability. Realized rectilinear grids use their smallest per-axis spacings. Unresolved uniform grids use their configured scalar spacing.

Returns:

Time step duration in seconds, calculated using the Courant

condition and spatial resolution.

Return type:

float

SimulationConfig.time_steps_total

Calculate the total number of time steps for the simulation.

Determines how many discrete time steps are needed to simulate the specified total simulation time, based on the time step duration.

Returns:

Total number of time steps needed to reach the specified

simulation time.

Return type:

int

SimulationConfig.use_complex_fields: bool | None

Whether to use complex-valued field arrays. None (default): auto-detect based on boundary conditions (e.g. Bloch). True: force complex fields (complex64 if dtype=float32, complex128 if dtype=float64). False: force real fields (raises error if Bloch boundaries are present).

Methods

SimulationConfig.aset(attr_name, val, create_new_ok=False)

Sets an attribute of this class. In contrast to the classical .at[].set(), this method updates the class attribute directly and does not only operate on jax pytree leaf nodes. Instead, replaces the full attribute with the new value.

The attribute can either be the attribute name of this class, or for nested classes it can also be the attribute name of a class, which itself is an attribute of this class. The syntax for this operation could look like this: “a->b->[0]->[‘name’]”. Here, the current class has an attribute a, which has an attribute b, which is a list, which we index at index 0, which is an element of type dictionary, which we index using the dictionary key ‘name’.

Note that dictionary keys cannot contain square brackets or single quotes (even if they are escaped).

Parameters:

• attr_name (str) – Name of attribute to set

• val (Any) – Value to set the attribute to

• create_new_ok (bool, optional) – If false (default), throw an error if the attribute does not exist. If true, creates a new attribute if the attribute name does not exist yet.

Returns:

Updated instance with new attribute value

Return type:

Self

SimulationConfig.get_class_fields()

Return type:

list[TreeClassField]

SimulationConfig.get_public_fields()

Return type:

list[TreeClassField]

SimulationConfig.resolve_grid(shape=None)

Return a concrete solver grid.

Parameters:

shape (tuple[int, int, int] | None) – Required when grid is an unresolved UniformGrid.

Return type:

RectilinearGrid

Returns:

A concrete RectilinearGrid.

SimulationConfig.uniform_spacing()

Return the uniform grid spacing.

UniformGrid can answer this before placement. RectilinearGrid answers only when all spacings are equal and raises for non-uniform meshes, making unsupported scalar assumptions explicit.

Return type:

float

If you find any errors in the documentation, please report them in the Github Issues!