Configuration Reference

All configuration for tidy3d lives under a single object:

from tidy3d import config

The tables below list the built-in sections and every option they expose.

How to read this page

• Environment variable overrides always take precedence. Follow the pattern TIDY3D_<SECTION>__<FIELD> (nesting continues with additional __ segments such as TIDY3D_PLUGINS__SAMPLE__ENABLED).

• The Persisted column marks fields written to disk when you call config.save(). Unmarked fields remain in-memory unless you pass include_defaults=True or store them in profiles or environment variables.

• Descriptions call out notable allowed values, defaults, and persistence behavior. Literal values appear in quotes and tuples use the (x, y, z) notation seen throughout the API.

Logging (config.logging)

Controls the verbosity and suppression behavior of the global logger.

Option	Default	Persisted	Description
level	"WARNING"	Yes	Lowest logging level that will be emitted. Accepts "DEBUG", "SUPPORT", "USER", "INFO", "WARNING", "ERROR", and "CRITICAL".
suppression	True	No	Suppress repeated log messages when True so only the first occurrence of identical messages is shown.
warn_once	False	No	Show each unique warning message at most once per process when True.

Simulation (config.simulation)

Optional overrides that tweak solver behavior at runtime.

Option	Default	Persisted	Description
use_local_subpixel	None	No	Controls whether local subpixel averaging is used in Simulation.epsilon, ModeSimulation.run_local, and ModeSolver.solve. Requires the tidy3d-extras package (pip install "tidy3d[extras]"). Set to True to force local subpixel averaging (raises an error if tidy3d-extras is not installed), False to disable it and use permittivity staircasing, or leave None to use subpixel averaging when available and silently fall back to staircasing otherwise. See Extras Plugin ✨ for more details.

Microwave (config.microwave)

Options that apply to the microwave solver add-on.

Option	Default	Persisted	Description
suppress_rf_license_warning	False	No	Skip the warning about RF license availability when set to True.

Adjoint (config.adjoint)

Parameters for adjoint behavior, including local execution settings and numerical tolerances. These overrides apply only when local_gradient is True; otherwise the service uses its remote defaults and emits a warning reminding you to enable local gradients.

Option	Default	Persisted	Description
min_wvl_fraction	0.05	No	Minimum fraction of the smallest wavelength used when discretizing cylinders for autograd derivatives.
points_per_wavelength	10	No	Number of material sample points per wavelength for cylinder discretization (must be positive).
default_wavelength_fraction	0.1	No	Fallback fraction of the minimum wavelength when adaptive spacing is needed (must be >= 0).
minimum_spacing_fraction	0.001	No	Smallest normalized spacing allowed when constructing adaptive finite-difference stencils (must be >= 0).
boundary_snapping_fraction	1.0	No	Fraction of minimum local grid size used to snap coordinates outside of boundaries for shape gradients (must be >= 0.5).
pec_detection_threshold	-100.0	No	Real permittivity threshold below which a material is treated as PEC in shape-gradient boundary integration (must be <= 0).
local_gradient	False	Yes	Enable local gradient evaluation. Remote gradients ignore other adjoint overrides unless this is True.
local_adjoint_dir	"adjoint_data"	Yes	Directory (relative to the working directory) where intermediate gradient artifacts are stored when local_gradient is enabled.
parallel_run	False	Yes	Launch canonical adjoint simulations for supported monitors in parallel with the forward solve when local gradients are enabled. If any unsupported monitors are present, parallel adjoint is disabled and the sequential adjoint pipeline is used.
parallel_adjoint_mode_direction_policy	"assume_outgoing"	Yes	Policy for selecting mode directions when launching parallel adjoint simulations. Accepts "assume_outgoing" or "run_both_directions".
gradient_precision	"single"	No	Floating-point precision used for gradient calculations. Accepts "single" or "double".
monitor_interval_poly	(1, 1, 1)	No	Cell spacing between samples for polynomial autograd monitors.
monitor_interval_custom	(1, 1, 1)	No	Cell spacing between samples for custom autograd monitors.
quadrature_sample_fraction	0.4	No	Fraction of uniform samples reused when building Gauss quadrature nodes (between 0 and 1).
gauss_quadrature_order	7	No	Maximum Gauss–Legendre order used in composite quadrature rules (must be positive).
edge_clip_tolerance	1e-9	No	Padding tolerance used when clipping polygon edges during surface integrations (must be >= 0).
solver_freq_chunk_size	None	No	Upper bound on the number of frequencies processed per chunk during gradient evaluation. Set to a positive integer to enable chunking or leave None to disable it.
memory_allotment_fraction	0.75	Yes	Fraction of reported available RAM reserved for local adjoint postprocessing when auto-selecting frequency chunk sizes (between 0 and 1).
max_traced_structures	500	No	Maximum number of structures whose fields may be traced in an adjoint run (must be positive).
max_adjoint_per_fwd	10	No	Maximum number of adjoint simulations dispatched per forward solve (must be positive).

Web (config.web)

Settings for the cloud API client and related environment overrides.

Option	Default	Persisted	Description
apikey	None	Yes	API key used for authentication. The value is masked when serialized. Also accepts SIMCLOUD_APIKEY as a shortcut environment variable.
ssl_verify	True	No	Verify SSL certificates for API requests.
enable_caching	True	Yes	Allow the web service to return cached simulation results when available.
api_endpoint	"https://tidy3d-api.simulation.cloud"	No	Base URL for API calls. Must be an HTTP or HTTPS URL.
website_endpoint	"https://tidy3d.simulation.cloud"	No	Base URL for the Tidy3D website. Must be an HTTP or HTTPS URL.
s3_region	"us-gov-west-1"	No	AWS region used by the platform’s S3 storage.
timeout	120	No	HTTP request timeout in seconds (between 0 and 300).
default_num_workers	10	No	Default worker count for configurable Batch thread pools when num_workers is not provided (must be positive). Upload/start uses a fixed concurrency of 64 workers.
ssl_version	None	No	Explicit TLS version to enforce. Accepts "TLSv1", "TLSv1_1", "TLSv1_2", or "TLSv1_3". Leave None to let requests negotiate the version.
env_vars	{}	No	Additional environment variables exported before API calls. Useful for proxy or credential helpers.

Local Cache (config.local_cache)

Controls the optional on-disk cache for simulation artifacts.

Option	Default	Persisted	Description
enabled	True	Yes	Turn the local cache on or off. When enabled, results are reused if the inputs match.
directory	Platform-dependent	Yes	Directory where cached artifacts are stored. The path is expanded, resolved, and created if missing. Uses <TIDY3D_BASE_DIR>/cache/simulations when TIDY3D_BASE_DIR is set, otherwise <XDG_CACHE_HOME>/tidy3d/simulations when XDG_CACHE_HOME is set, and otherwise ~/.cache/tidy3d/simulations.
max_size_gb	10.0	Yes	Maximum cache size in gigabytes. 0 disables the size limit.
max_entries	0	Yes	Maximum number of cached simulations retained. 0 means no limit and eviction falls back to size constraints.

Batch Data Cache (config.batch_data_cache)

Controls the optional in-memory cache for loaded batch task data.

Option	Default	Persisted	Description
enabled	True	No	Cache batch results in memory when files are below the size threshold.
max_total_size_gb	1.0	No	Cache batch task data only when the combined size of all task data files is at or below this threshold. 0 disables the cache.

vGPU (config.vgpu)

Defaults used for virtual GPU cloud runs.

Option	Default	Persisted	Description
priority	None	No	Default queue priority for vGPU runs. When set, must be between 1 and 10.
vgpu_allocation	None	No	Default virtual GPU allocation for vGPU runs. When set, must be one of 1, 2, 4, or 8.
ignore_memory_limit	None	No	Default flag to allow vGPU runs above the estimated memory limit.

Plugins (config.plugins)

Container that holds plugin-defined sections. After a plugin calls @register_plugin("name"), its configuration becomes available under config.plugins.<name> and follows the same persistence and environment variable rules described above (for example TIDY3D_PLUGINS__NAME__FIELD).