{
  "title": "CustomMedium",
  "public_path": "flex_rf.tidy3d.CustomMedium",
  "lookup_path": "tidy3d.CustomMedium",
  "slug": "flex_rf/tidy3d/CustomMedium",
  "public_url": "/rf/latest/autogenerated/flex_rf/tidy3d/custommedium/",
  "object_kind": "class",
  "introduction": "`Medium` with user-supplied permittivity distribution.",
  "notes": "**Practical Advice**\n\nUse `CustomMedium` when permittivity varies spatially — for example, graded-index\n(GRIN) lenses or topology-optimized design regions. Define the permittivity on a\nrectangular grid using `SpatialDataArray`:\n\n```python\nfrom tidy3d import SpatialDataArray\nimport numpy as np\n\nx = np.linspace(-5, 5, 100)\ny = np.linspace(-5, 5, 100)\nz = [0]  # 2D variation\nX, Y = np.meshgrid(x, y, indexing=\"ij\")\neps_data = 1 + 3 * np.exp(-(X**2 + Y**2) / 4)\neps_data = eps_data[:, :, np.newaxis]\n\npermittivity = SpatialDataArray(eps_data, coords=dict(x=x, y=y, z=z))\ncustom_medium = CustomMedium(permittivity=permittivity)\n```\n\nFor uniform pixelated grids (e.g. topology optimization), consider the convenience method\n`from_permittivity_array`, which creates a `Structure` with a `CustomMedium`\ndirectly from a 3D numpy array and a geometry.\n\nFor wavelength-independent homogeneous materials, use `Medium` instead.\nFor dispersive materials, use `FastDispersionFitter` or an analytical model.",
  "examples": "```python\nNx, Ny, Nz = 10, 9, 8\nX = np.linspace(-1, 1, Nx)\nY = np.linspace(-1, 1, Ny)\nZ = np.linspace(-1, 1, Nz)\ncoords = dict(x=X, y=Y, z=Z)\npermittivity= SpatialDataArray(np.ones((Nx, Ny, Nz)), coords=coords)\nconductivity= SpatialDataArray(np.ones((Nx, Ny, Nz)), coords=coords)\ndielectric = CustomMedium(permittivity=permittivity, conductivity=conductivity)\neps = dielectric.eps_model(200e12)\n```",
  "references": "",
  "signature": "class CustomMedium(AbstractCustomMedium)",
  "source": {
    "path": "flex/public/tidy3d/tidy3d/components/medium.py",
    "url": "",
    "lineno": 1868,
    "endlineno": 2678
  },
  "bases": [
    "AbstractCustomMedium"
  ],
  "parameter_rows": [
    {
      "name": "eps_dataset",
      "annotation": "PermittivityDataset | None",
      "default": "None",
      "description": "[To be deprecated] User-supplied dataset containing complex-valued permittivity as a function of space. Permittivity distribution over the Yee-grid will be interpolated based on `interp_method`.",
      "origin": "declared"
    },
    {
      "name": "permittivity",
      "annotation": "CustomSpatialDataTypeAnnotated | None",
      "default": "None",
      "description": "Spatial profile of relative permittivity.",
      "origin": "declared"
    },
    {
      "name": "conductivity",
      "annotation": "CustomSpatialDataTypeAnnotated | None",
      "default": "None",
      "description": "Spatial profile Electric conductivity. Defined such that the imaginary part of the complex permittivity at angular frequency omega is given by conductivity/omega.",
      "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 medium.",
      "origin": "inherited"
    },
    {
      "name": "frequency_range",
      "annotation": "FreqBound | None",
      "default": "None",
      "description": "Optional range of validity for the medium.",
      "origin": "inherited"
    },
    {
      "name": "allow_gain",
      "annotation": "bool",
      "default": "False",
      "description": "Allow the medium to be active. Caution: simulations with a gain medium are unstable, and are likely to diverge.Simulations where `allow_gain` is set to `True` will still be charged even if diverged. Monitor data up to the divergence point will still be returned and can be useful in some cases.",
      "origin": "inherited"
    },
    {
      "name": "nonlinear_spec",
      "annotation": "NonlinearSpec | NonlinearSusceptibility | None",
      "default": "None",
      "description": "Nonlinear spec applied on top of the base medium properties.",
      "origin": "inherited"
    },
    {
      "name": "modulation_spec",
      "annotation": "ModulationSpec | None",
      "default": "None",
      "description": "Modulation spec applied on top of the base medium properties.",
      "origin": "inherited"
    },
    {
      "name": "viz_spec",
      "annotation": "VisualizationSpec | None",
      "default": "None",
      "description": "Plotting specification for visualizing medium.",
      "origin": "inherited"
    },
    {
      "name": "heat_spec",
      "annotation": "ThermalSpecType | None",
      "default": "None",
      "description": "DEPRECATED: Use `MultiPhysicsMedium`. Specification of the medium heat properties. They are used for solving the heat equation via the `HeatSimulation` interface. Such simulations can beused for investigating the influence of heat propagation on the properties of optical systems. Once the temperature distribution in the system is found using `HeatSimulation` object, `Simulation.perturbed_mediums_copy()` can be used to convert mediums with perturbation models defined into spatially dependent custom mediums. Otherwise, the `heat_spec` does not directly affect the running of an optical `Simulation`.",
      "origin": "inherited"
    },
    {
      "name": "interp_method",
      "annotation": "InterpMethod",
      "default": "'nearest'",
      "description": "Interpolation method to obtain permittivity values that are not supplied at the Yee grids; For grids outside the range of the supplied data, extrapolation will be applied. When the extrapolated value is smaller (greater) than the minimal (maximal) of the supplied data, the extrapolated value will take the minimal (maximal) of the supplied data.",
      "origin": "inherited"
    },
    {
      "name": "subpixel",
      "annotation": "bool",
      "default": "False",
      "description": "If `True`, apply the subpixel averaging method specified by `Simulation`'s field `subpixel` for this type of material on the interface of the structure, including exterior boundary and intersection interfaces with other structures.",
      "origin": "inherited"
    },
    {
      "name": "derived_from",
      "annotation": "PerturbationMediumType | None",
      "default": "None",
      "description": "If not `None`, it records the parent medium from which this medium was derived.",
      "origin": "inherited"
    }
  ],
  "members": [
    {
      "name": "eps_dataarray_freq",
      "kind": "function",
      "signature": "eps_dataarray_freq(frequency: float)",
      "description": "Permittivity array at `frequency`. ()"
    },
    {
      "name": "eps_diagonal",
      "kind": "function",
      "signature": "eps_diagonal(frequency: float)",
      "description": "Main diagonal of the complex-valued permittivity tensor at `frequency`. Spatially, we take max{|eps|}, so that autoMesh generation works appropriately."
    },
    {
      "name": "eps_diagonal_on_grid",
      "kind": "function",
      "signature": "eps_diagonal_on_grid(frequency: float, coords: Coords)",
      "description": "Spatial profile of main diagonal of the complex-valued permittivity at `frequency` interpolated at the supplied coordinates."
    },
    {
      "name": "eps_model",
      "kind": "function",
      "signature": "eps_model(frequency: float)",
      "description": "Spatial and polarizaiton average of complex-valued permittivity as a function of frequency."
    },
    {
      "name": "freqs",
      "kind": "function",
      "signature": "freqs()",
      "description": "float array of frequencies. This field is to be deprecated in v3.0."
    },
    {
      "name": "from_eps_raw",
      "kind": "function",
      "signature": "from_eps_raw(eps: ScalarFieldDataArray | CustomSpatialDataType, freq: float | None = None, interp_method: InterpMethod = 'nearest', **kwargs: Any)",
      "description": "Construct a `CustomMedium` from datasets containing raw permittivity values."
    },
    {
      "name": "from_nk",
      "kind": "function",
      "signature": "from_nk(n: ScalarFieldDataArray | CustomSpatialDataType, k: ScalarFieldDataArray | CustomSpatialDataType | None = None, freq: float | None = None, interp_method: InterpMethod = 'nearest', **kwargs: Any)",
      "description": "Construct a `CustomMedium` from datasets containing n and k values."
    },
    {
      "name": "grids",
      "kind": "function",
      "signature": "grids(bounds: Bound)",
      "description": "Make a `Grid` corresponding to the data in each `eps_ii` component. The min and max coordinates along each dimension are bounded by `bounds`."
    },
    {
      "name": "is_isotropic",
      "kind": "function",
      "signature": "is_isotropic()",
      "description": "Check if the medium is isotropic or anisotropic."
    },
    {
      "name": "is_spatially_uniform",
      "kind": "function",
      "signature": "is_spatially_uniform()",
      "description": "Whether the medium is spatially uniform."
    },
    {
      "name": "n_cfl",
      "kind": "function",
      "signature": "n_cfl()",
      "description": "This property computes the index of refraction related to CFL condition, so that the FDTD with this medium is stable when the time step size that doesn't take material factor into account is multiplied by ``n_cfl```."
    }
  ],
  "group": "flex_rf.tidy3d"
}