{
  "title": "PML",
  "public_path": "flex_rf.tidy3d.PML",
  "lookup_path": "tidy3d.PML",
  "slug": "flex_rf/tidy3d/PML",
  "public_url": "/rf/latest/autogenerated/flex_rf/tidy3d/pml/",
  "object_kind": "class",
  "introduction": "Specifies a standard PML along a single dimension.",
  "notes": "**1D Model Illustration**\n\nConsider a transformed wave equation in the $$x$$ dimension below _`[1]`:\n\n$$\n\\left( \\left( \\frac{1}{s(x)} \\frac{\\delta}{\\delta x} \\right)^2 - \\frac{1}{c^2} \\frac{\\delta^2}{\\delta t^2} \\right) E = 0\n$$\n\nwhere the wave stretch factor $$s(x)$$ depends on the PML boundary position in the $$x$$ dimension.\n\n.. TODO what is x at 0?\n\n$$\ns(x) = \\left \\{\n           \\begin{array}{lr}\n               1, & \\text{for } x < 0 \\\\\n               1 - \\frac{\\sigma}{i \\omega \\epsilon_0}, & \\text{for } x > 0\n           \\end{array}\n       \\right \\}\n$$\n\nThe wave equation can be solved and plotted accordingly as a function of the $$x$$ dimension.\n\n$$\nE(x) = \\left \\{\n           \\begin{array}{lr}\n               e^{i(kx - \\omega t)}, & \\text{for } x < 0 \\\\\n               e^{i(kx - \\omega t)} \\times e^{-\\frac{\\sigma x}{c \\epsilon_0}} & \\text{for } x > 0\n           \\end{array}\n       \\right \\}\n$$\n\nHence, we see how this PML stretch factor induces frequency-independent exponential attentation and no\nreflection after the boundary at $$x=0$$.\n\n.. TODO make this image better\n\n**Usage Caveats**\n\nA perfectly matched layer (PML) is the most commonly used boundary condition in FDTD simulations to truncate\na simulation domain and absorb outgoing radiation. However, many divergence issues are associated with the\nuse of PML. One of the most common causes of a diverged simulation is structures inserted into PML at an angle.\n\n.. TODO links to absorber boundaries\n\nIncorporating a dispersive material into the PML can also cause simulation divergence in certain scenarios.\nIf your simulation lacks any structures inserted into the PML at an angle, but includes dispersive material\nin PML, it is advisable to substitute a nondispersive material for the dispersive material. Alternatively,\nif dispersion is necessary, switching from the `PML` to `Absorber` can effectively address the\nissue.\n\nThe PML can effectively absorb outgoing radiation with minimum reflection as if the radiation just propagates\ninto the free space. However, it’s important to keep in mind that the PML only absorbs propagating fields. For\nevanescent fields, the PML can act as an amplification medium and cause a simulation to diverge. In Tidy3D,\na warning will appear if the distance between a structure is smaller than half of a wavelength to prevent\nevanescent fields from leaking into PML. In most cases, the evanescent field will naturally die off within\nhalf a wavelength, but in some instances, a larger distance may be required.",
  "examples": "```python\npml = PML(num_layers=10)\n```",
  "references": "**[1]** W.C. Chew and W.H. Weedon, Microwave and Optical Tech. Lett., 7 (13), 599,1994; S. Johnson, arXiv 2108.05348, 2021\n\n**[2]** Antonios Giannopoulos, IEEE Transactions on Antennas and Propagation, 56(9), 2995, 2008\n\n**Practical Advice**\n\nFor best results, structures that intersect with the PML or simulation edges should extend all the way\nthrough using `td.inf`:\n\n```python\nStructure(geometry=Box(size=(td.inf, width, height)), medium=core)\n```\n\nStructures that terminate inside PML can cause evanescent fields at the interface to be\namplified by the absorber, potentially leading to simulation divergence.",
  "signature": "class PML(AbsorberSpec)",
  "source": {
    "path": "flex/public/tidy3d/tidy3d/components/boundary.py",
    "url": "",
    "lineno": 727,
    "endlineno": 864
  },
  "bases": [
    "AbsorberSpec"
  ],
  "parameter_rows": [
    {
      "name": "num_layers",
      "annotation": "int",
      "default": "12",
      "description": "Number of layers of standard PML.",
      "origin": "declared"
    },
    {
      "name": "parameters",
      "annotation": "PMLParams",
      "default": "DefaultPMLParameters",
      "description": "Parameters of the complex frequency-shifted absorption poles.",
      "origin": "declared"
    },
    {
      "name": "extrude_structures",
      "annotation": "bool",
      "default": "True",
      "description": "Automatically extrude structures into the absorbing region (e.g., PML or adiabatic absorber). Any structure located within 2 cells of a simulation boundary will be extended through the full thickness of the PML/absorber. The extruded region is assigned the material properties of the structure 2 cells from the simulation boundary. Extrusion is performed along the direction normal to the PML/absorber surface.",
      "origin": "declared"
    },
    {
      "name": "attrs",
      "annotation": "dict",
      "default": "factory: dict",
      "description": "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.model_dump_json()`.",
      "origin": "inherited"
    },
    {
      "name": "name",
      "annotation": "str | None",
      "default": "None",
      "description": "Optional unique name for boundary.",
      "origin": "inherited"
    }
  ],
  "members": [],
  "group": "flex_rf.tidy3d"
}