tidy3d.HeatChargeSimulation#

class HeatChargeSimulation[source]#

Bases: AbstractSimulation

Defines thermoelectric simulations.

Parameters:

• attrs (dict = {}) – Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, attrs are mutable. For example, the following is allowed for setting an attr obj.attrs['foo'] = bar. Also note that Tidy3D` will raise a TypeError if attrs contain objects that can not be serialized. One can check if attrs are serializable by calling obj.json().

• center (Union[tuple[Union[float, autograd.tracer.Box], Union[float, autograd.tracer.Box], Union[float, autograd.tracer.Box]], Box] = (0.0, 0.0, 0.0)) – [units = um]. Center of object in x, y, and z.

• size (Union[tuple[Union[pydantic.v1.types.NonNegativeFloat, autograd.tracer.Box], Union[pydantic.v1.types.NonNegativeFloat, autograd.tracer.Box], Union[pydantic.v1.types.NonNegativeFloat, autograd.tracer.Box]], Box]) – [units = um]. Size in x, y, and z directions.

• medium (Union[MultiPhysicsMedium, Medium, AnisotropicMedium, PECMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude, FullyAnisotropicMedium, CustomMedium, CustomPoleResidue, CustomSellmeier, CustomLorentz, CustomDebye, CustomDrude, CustomAnisotropicMedium, PerturbationMedium, PerturbationPoleResidue, LossyMetalMedium, Medium2D, AnisotropicMediumFromMedium2D, FluidSpec, SolidSpec, SolidMedium, FluidMedium, ChargeConductorMedium, ChargeInsulatorMedium, SemiconductorMedium] = Medium(attrs={}, name=None, frequency_range=None, allow_gain=False, nonlinear_spec=None, modulation_spec=None, viz_spec=None, heat_spec=None, type='Medium', permittivity=1.0, conductivity=0.0)) – Background medium of simulation, defaults to a standard dispersion-less Medium if not specified.

• structures (Tuple[Structure, ...] = ()) – Tuple of structures present in simulation. Note: Structures defined later in this list override the simulation material properties in regions of spatial overlap.

• symmetry (Tuple[Literal[0, 1], Literal[0, 1], Literal[0, 1]] = (0, 0, 0)) – Tuple of integers defining reflection symmetry across a plane bisecting the simulation domain normal to the x-, y-, and z-axis at the simulation center of each axis, respectively. Each element can be 0 (symmetry off) or 1 (symmetry on).

• sources (Tuple[Annotated[Union[tidy3d.components.tcad.source.heat.HeatSource, tidy3d.components.tcad.source.coupled.HeatFromElectricSource, tidy3d.components.tcad.source.heat.UniformHeatSource], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – List of heat and/or charge sources.

• boundary_spec (Tuple[Annotated[Union[tidy3d.components.tcad.boundary.specification.HeatChargeBoundarySpec, tidy3d.components.tcad.boundary.specification.HeatBoundarySpec], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – List of boundary condition specifications.

• monitors (Tuple[Annotated[Union[tidy3d.components.tcad.monitors.heat.TemperatureMonitor, tidy3d.components.tcad.monitors.charge.SteadyPotentialMonitor, tidy3d.components.tcad.monitors.charge.SteadyFreeCarrierMonitor, tidy3d.components.tcad.monitors.charge.SteadyCapacitanceMonitor], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – Monitors in the simulation.

• grid_spec (Union[UniformUnstructuredGrid, DistanceUnstructuredGrid]) – Grid specification for heat-charge simulation.

• version (str = 2.8.0rc2) – String specifying the front end version number.

• plot_length_units (Optional[Literal['nm', 'μm', 'um', 'mm', 'cm', 'm']] = μm) – When set to a supported LengthUnit, plots will be produced with proper scaling of axes and include the desired unit specifier in labels.

• analysis_spec (Optional[IsothermalSteadyChargeDCAnalysis] = None) – The analysis_spec is used to validate that the simulation parameters and tolerance settings are correctly configured as desired by the user.

Notes

A HeatChargeSimulation supports different types of simulations. It solves the heat and conduction equations using the Finite-Volume (FV) method. This solver determines the required computation physics according to the simulation scene definition. This is implemented in this way due to the strong multi-physics coupling.

The HeatChargeSimulation can solve multiple physics and the intention is to enable close thermo-electrical coupling.

Currently, this solver supports steady-state heat conduction where $q$ is the heat flux, $k$ is the thermal conductivity, and $T$ is the temperature.

$$-k\cdot \mathrm{\nabla }(T)=q$$

The steady-state electrical Conduction equation depends on the electric conductivity ($\sigma$) of a medium, and the electric field ($\mathbf{E}=-\mathrm{\nabla }(\psi )$) derived from electrical potential ($\psi$). Currently, in this type of simulation, no current sources or sinks are supported.

$$\text{div}(\sigma \cdot \mathrm{\nabla }(\psi ))=0$$

For further details on what equations are solved in Charge simulations, refer to the SemiconductorMedium.

Let’s understand how the physics solving is determined:

Simulation Type	Example Configuration Settings
Heat	The heat equation is solved with specified heat sources, boundary conditions, etc. Structures should incorporate materials with defined heat properties.
Conduction	The electrical conduction equation is solved with specified boundary conditions such as SteadyVoltageBC, SteadyCurrentBC, …
Charge	Drift-diffusion equations are solved for structures containing a defined SemiconductorMedium. Insulators with a ChargeInsulatorMedium can also be included. For these, only the electric potential field is calculated.

Examples

To run a thermal (Heat 🔥) simulation with a solid conductive structure:

>>> import tidy3d as td
>>> heat_sim = td.HeatChargeSimulation(
...     size=(3.0, 3.0, 3.0),
...     structures=[
...         td.Structure(
...             geometry=td.Box(size=(1, 1, 1), center=(0, 0, 0)),
...             medium=td.Medium(
...                 permittivity=2.0,
...                 heat_spec=td.SolidSpec(
...                     conductivity=1,
...                     capacity=1,
...                 )
...             ),
...             name="box",
...         ),
...     ],
...     medium=td.Medium(permittivity=3.0, heat_spec=td.FluidSpec()),
...     grid_spec=td.UniformUnstructuredGrid(dl=0.1),
...     sources=[td.HeatSource(rate=1, structures=["box"])],
...     boundary_spec=[
...         td.HeatChargeBoundarySpec(
...             placement=td.StructureBoundary(structure="box"),
...             condition=td.TemperatureBC(temperature=500),
...         )
...     ],
...     monitors=[td.TemperatureMonitor(size=(1, 2, 3), name="sample")],
... )

To run a drift-diffusion (Charge ⚡) system: >>> import tidy3d as td >>> Si_n = td.MultiPhysicsMedium(charge=td.SemiconductorMedium( … permittivity=11.7, … N_d=1e15, … N_a=0, … ), name=”Si_n”, … ) >>> Si_p = Si_n.updated_copy(N_d=0, N_p=1e16, name=”Si_p”) >>> n_side = td.Structure( … geometry=td.Box(center=(-0.5, 0, 0), size=(1, 1, 1)), … medium=Si_n, … name=”n_side” … ) >>> p_side = td.Structure( … geometry=td.Box(center=(0.5, 0, 0), size=(1, 1, 1)), … medium=Si_p, … name=”p_side” … ) >>> bc_v1 = td.HeatChargeBoundarySpec( … condition=td.VoltageBC(source=td.DCVoltageSource(voltage=[-1, 0, 0.5])), … placement=td.MediumMediumInterface(mediums=[air.name, Si_n.name]), … ) >>> bc_v2 = td.HeatChargeBoundarySpec( … condition=td.VoltageBC(source=td.DCVoltageSource(voltage=0)), … placement=td.MediumMediumInterface(mediums=[air.name, Si_p.name]), … ) >>> charge_sim = td.HeatChargeSimulation( … structures=[n_side, p_side], … medium=td.Medium(heat_spec=td.FluidSpec(), name=”air”), … monitors=[td.SteadyFreeCarrierMonitor( … center=(0, 0, 0), size=(td.inf, td.inf, 0), name=”charge_mnt”, unstructured=True … )], … center=(0, 0, 0), … size=(3, 3, 3), … grid_spec=td.UniformUnstructuredGrid(dl=0.05), … boundary_spec=[bc_v1, bc_v2], … analysis_spec=td.SteadyChargeDCAnalysis( … tolerance_settings=td.ChargeToleranceSpec(rel_tol=1e5, abs_tol=3e3, max_iters=400), … convergence_dv=10), … )

Coupling between Heat and electrical Conduction simulations is currently limited to 1-way. This is specified by defining a heat source of type HeatFromElectricSource. With this coupling, joule heating is calculated as part of the solution to a Conduction simulation and translated into the Heat simulation.

Two common scenarios can use this coupling definition:

1. One in which BCs and sources are specified for both Heat and Conduction simulations.

   In this case one mesh will be generated and used for both the Conduction and Heat simulations.

2. Only heat BCs/sources are provided. In this case, only the Heat equation will be solved.

   Before the simulation starts, it will try to load the heat source from file so a previously run Conduction simulations must have run previously. Since the Conduction and Heat meshes may differ, an interpolation between them will be performed prior to starting the Heat simulation.

Additional heat sources can be defined, in which case, they will be added on top of the coupling heat source.

Attributes

version	DO NOT EDIT: Modified automatically with .bump2version.cfg
attrs

Methods

check_charge_simulation(values)	Makes sure that Charge simulations are set correctly.
check_coupling_source_can_be_applied(values)	Error if material doesn't have the right specifications
check_medium_specs(values)	Error if no appropriate specs.
check_only_one_voltage_array_provided(val, ...)	Issue error if more than one voltage array is provided.
check_unsupported_geometries(val)	Error if structures contain unsupported yet geometries.
check_voltage_array_if_capacitance(values)	Make sure an array of voltages has been defined if a SteadyCapacitanceMonitor' has been defined
check_zero_dim_domain(val, values)	Error if heat domain have zero dimensions.
estimate_charge_mesh_size(values)	Make an estimate of the mesh size and raise a warning if too big.
from_scene(scene, **kwargs)	Create a simulation from a :class:.`Scene` instance.
names_exist_bcs(val, values)	Error if boundary conditions point to non-existing structures/media.
names_exist_grid_spec(val, values)	Warn if 'UniformUnstructuredGrid' points at a non-existing structure.
names_exist_sources(val, values)	Error if a heat-charge source point to non-existing structures.
not_all_neumann(values)	Make sure not all BCs are of Neumann type
plot_boundaries([x, y, z, property, ax])	Plot each of simulation's boundary conditions on a plane defined by one nonzero x,y,z coordinate.
plot_heat_conductivity([x, y, z, ax, alpha, ...])	DEPRECATED: Method added for backwards compatibility with HeatSimulation.plot_heat_conductivity.
plot_property([x, y, z, ax, alpha, ...])	Plot each of simulation's components on a plane defined by one nonzero x,y,z coordinate.
plot_sources([x, y, z, property, hlim, ...])	Plot each of simulation's sources on a plane defined by one nonzero x,y,z coordinate.
source_bounds([property])	Compute range of heat sources present in the simulation.
warn_if_minimal_mesh_size_override(val, values)	Warn if minimal mesh size limit overrides desired mesh size.

Inherited Common Usage

medium#

Background medium of simulation, defaults to a standard dispersion-less Medium if not specified.

sources#

monitors#

boundary_spec#

grid_spec#

symmetry#

analysis_spec#

classmethod check_unsupported_geometries(val)[source]#

Error if structures contain unsupported yet geometries.

classmethod check_voltage_array_if_capacitance(values)[source]#

Make sure an array of voltages has been defined if a SteadyCapacitanceMonitor’ has been defined

classmethod check_zero_dim_domain(val, values)[source]#

Error if heat domain have zero dimensions.

classmethod names_exist_bcs(val, values)[source]#

Error if boundary conditions point to non-existing structures/media.

classmethod check_only_one_voltage_array_provided(val, values)[source]#

Issue error if more than one voltage array is provided. Currently we only allow to sweep over one voltage array.

classmethod check_charge_simulation(values)[source]#

Makes sure that Charge simulations are set correctly.

classmethod not_all_neumann(values)[source]#

Make sure not all BCs are of Neumann type

classmethod names_exist_grid_spec(val, values)[source]#

Warn if ‘UniformUnstructuredGrid’ points at a non-existing structure.

classmethod warn_if_minimal_mesh_size_override(val, values)[source]#

Warn if minimal mesh size limit overrides desired mesh size.

classmethod names_exist_sources(val, values)[source]#

Error if a heat-charge source point to non-existing structures.

classmethod check_medium_specs(values)[source]#

Error if no appropriate specs.

classmethod check_coupling_source_can_be_applied(values)[source]#

Error if material doesn’t have the right specifications

classmethod estimate_charge_mesh_size(values)[source]#

Make an estimate of the mesh size and raise a warning if too big. NOTE: this is a very rough estimate. The back-end will actually stop execution based on actual node-count.

plot_property(x=None, y=None, z=None, ax=None, alpha=None, source_alpha=None, monitor_alpha=None, property='heat_conductivity', hlim=None, vlim=None)[source]#

Plot each of simulation’s components on a plane defined by one nonzero x,y,z coordinate.

Parameters:

• x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

• y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

• z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

• ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

• alpha (float = None) – Opacity of the structures being plotted. Defaults to the structure default alpha.

• source_alpha (float = None) – Opacity of the sources. If None, uses Tidy3d default.

• monitor_alpha (float = None) – Opacity of the monitors. If None, uses Tidy3d default.

• property (str = "heat_conductivity") – Specified the type of simulation for which the plot will be tailored. Options are [“heat_conductivity”, “electric_conductivity”, “source”]

• hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

• vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

plot_heat_conductivity(x=None, y=None, z=None, ax=None, alpha=None, source_alpha=None, monitor_alpha=None, colorbar='conductivity', hlim=None, vlim=None, **kwargs)[source]#

DEPRECATED: Method added for backwards compatibility with HeatSimulation.plot_heat_conductivity. Plot each of simulation’s components on a plane defined by one nonzero x,y,z coordinate.

Parameters:

• x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

• y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

• z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

• ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

• alpha (float = None) – Opacity of the structures being plotted. Defaults to the structure default alpha.

• source_alpha (float = None) – Opacity of the sources. If None, uses Tidy3d default.

• monitor_alpha (float = None) – Opacity of the monitors. If None, uses Tidy3d default.

• colorbar (str = "conductivity") – Display colorbar for thermal conductivity (“conductivity”) or heat source rate (“source”).

• hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

• vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

plot_boundaries(x=None, y=None, z=None, property='heat_conductivity', ax=None)[source]#

Plot each of simulation’s boundary conditions on a plane defined by one nonzero x,y,z coordinate.

Parameters:

• x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

• y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

• z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

• property (str = None) – Specified the type of simulation for which the plot will be tailored. Options are [“heat_conductivity”, “electric_conductivity”]

• ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

plot_sources(x=None, y=None, z=None, property='heat_conductivity', hlim=None, vlim=None, alpha=None, ax=None)[source]#

Plot each of simulation’s sources on a plane defined by one nonzero x,y,z coordinate.

Parameters:

• x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

• y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

• z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

• property (str = None) – Specified the type of simulation for which the plot will be tailored. Options are [“heat_conductivity”, “electric_conductivity”]

• hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

• vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

• alpha (float = None) – Opacity of the sources, If None uses Tidy3d default.

• ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

source_bounds(property='heat_conductivity')[source]#

Compute range of heat sources present in the simulation.

classmethod from_scene(scene, **kwargs)[source]#

Create a simulation from a :class:.`Scene` instance. Must provide additional parameters to define a valid simulation (for example, size, grid_spec, etc).

Parameters:

• scene (:class:.`Scene`) – Scene containing structures information.

• **kwargs – Other arguments

Example

>>> from tidy3d import Scene, Medium, Box, Structure, UniformUnstructuredGrid
>>> box = Structure(
...     geometry=Box(center=(0, 0, 0), size=(1, 2, 3)),
...     medium=Medium(permittivity=5),
...     name="box"
... )
>>> scene = Scene(
...     structures=[box],
...     medium=Medium(
...         permittivity=3,
...         heat_spec=SolidSpec(
...             conductivity=1, capacity=1,
...         ),
...     ),
... )
>>> sim = HeatChargeSimulation.from_scene(
...     scene=scene,
...     center=(0, 0, 0),
...     size=(5, 6, 7),
...     grid_spec=UniformUnstructuredGrid(dl=0.4),
...     boundary_spec=[
...         HeatChargeBoundarySpec(
...             placement=StructureBoundary(structure="box"),
...             condition=TemperatureBC(temperature=500),
...         )
...     ],
... )

__hash__()#

Hash method.