# electromagneticSource

Specify current density or charge density for electromagnetic model

## Syntax

``electromagneticSource(emagmodel,"ChargeDensity",rho)``
``electromagneticSource(emagmodel,"CurrentDensity",J)``
``electromagneticSource(___,RegionType,RegionID)``
``emagSource = electromagneticSource(___)``

## Description

example

````electromagneticSource(emagmodel,"ChargeDensity",rho)` specifies the charge density. The solver uses a charge density for an electrostatic analysis.```

example

````electromagneticSource(emagmodel,"CurrentDensity",J)` specifies the current density. The solver uses a current density for magnetostatic or harmonic (time-harmonic) analyses.```

example

````electromagneticSource(___,RegionType,RegionID)` specifies the charge or current density for the specified geometry region. Use this syntax with any of the input argument combinations in the previous syntaxes.```

example

````emagSource = electromagneticSource(___)` returns the electromagnetic source object.```

## Examples

collapse all

Specify charge density on the entire geometry for an electrostatic analysis.

```emagmodel = createpde("electromagnetic","electrostatic"); importGeometry(emagmodel,"PlateHoleSolid.stl"); electromagneticSource(emagmodel,"ChargeDensity",10)```
```ans = ElectromagneticSourceAssignment with properties: RegionType: 'Cell' RegionID: 1 ChargeDensity: 10 CurrentDensity: [] ```

Specify current density on the entire geometry for harmonic analysis.

Create an electromagnetic model for harmonic analysis.

`model = createpde("electromagnetic","harmonic");`

Include a square geometry in the model. Plot the geometry with the edge labels.

```geometryFromEdges(model,@squareg); pdegplot(model,"EdgeLabels","on") xlim([-1.1 1.1]) ylim([-1.1 1.1])``` Specify current density on the entire geometry. For a 2-D harmonic analysis model with the electric field type, the current density must be a column vector of two elements. When solving the model, the toolbox multiplies the specified current density value by `-i` and by frequency.

`electromagneticSource(model,"CurrentDensity",[1;0])`
```ans = ElectromagneticSourceAssignment with properties: RegionType: 'Face' RegionID: 1 ChargeDensity: [] CurrentDensity: [2x1 double] ```

Specify charge density on individual faces in electrostatic analysis.

Create an electromagnetic model for electrostatic analysis.

`emagmodel = createpde("electromagnetic","electrostatic");`

Create a 2-D geometry with two faces. First, import and plot a 2-D geometry representing a plate with a hole.

```gm = importGeometry(emagmodel,"PlateHolePlanar.stl"); pdegplot(gm,"EdgeLabels","on","FaceLabels","on")``` Then, fill the hole by adding a face and plot the resulting geometry.

```gm = addFace(gm,5); pdegplot(gm,"FaceLabels","on")``` Specify charge density values separately for faces 1 and 2.

`sc1 = electromagneticSource(emagmodel,"Face",1,"ChargeDensity",0.3)`
```sc1 = ElectromagneticSourceAssignment with properties: RegionType: 'Face' RegionID: 1 ChargeDensity: 0.3000 CurrentDensity: [] ```
`sc2 = electromagneticSource(emagmodel,"Face",2,"ChargeDensity",0.28)`
```sc2 = ElectromagneticSourceAssignment with properties: RegionType: 'Face' RegionID: 2 ChargeDensity: 0.2800 CurrentDensity: [] ```

Use a function handle to specify a charge density that depends on the coordinates.

Create an electromagnetic model for electrostatic analysis.

`emagmodel = createpde("electromagnetic","electrostatic");`

Create a unit circle geometry and include it in the model.

`geometryFromEdges(emagmodel,@circleg);`

Specify the charge density as a function of the x- and y-coordinates, $\rho =0.3\sqrt{{\mathit{x}}^{2}+{\mathit{y}}^{2}}$.

```rho = @(location,~)0.3.*sqrt(location.x.^2 + location.y.^2); electromagneticSource(emagmodel,"ChargeDensity",rho)```
```ans = ElectromagneticSourceAssignment with properties: RegionType: 'Face' RegionID: 1 ChargeDensity: @(location,~)0.3.*sqrt(location.x.^2+location.y.^2) CurrentDensity: [] ```

## Input Arguments

collapse all

Electromagnetic model, specified as an `ElectromagneticModel` object. The model contains a geometry, a mesh, the electromagnetic properties of the material, the electromagnetic sources, and the boundary conditions.

Charge density, specified as a real number or a function handle. Use a function handle to specify a charge density that depends on the coordinates. For details, see More About.

Data Types: `double` | `function_handle`

Current density, specified as a real number, a column vector, or a function handle. Use a function handle to specify a current density that depends on the coordinates.

For magnetostatic analysis, the current density must be a real number for a 2-D model, a column vector of three elements for a 3-D model, or a function handle for a 2-D or 3-D model.

For harmonic analysis with the electric field type, the current density must be a column vector of two elements for a 2-D model, a column vector of three elements for a 3-D model, or a function handle for a 2-D or 3-D model. The toolbox multiplies the specified current density by `-i` and by frequency.

For harmonic analysis with the magnetic field type, the current density must be a scalar for a 2-D model, a column vector of three elements for a 3-D model, or a function handle for a 2-D or 3-D model. The toolbox uses the curl of the specified current density.

Data Types: `double` | `function_handle`

Geometric region type, specified as `"Face"` for a 2-D model or `"Cell"` for a 3-D model.

Data Types: `char` | `string`

Region ID, specified as a vector of positive integers. Find the face or cell IDs by using `pdegplot` with the `"FaceLabels"` or `"CellLabels"` name-value argument set to `"on"`.

Example: `electromagneticSource(emagmodel,"CurrentDensity",10,"Face",1:3)`

Data Types: `double`

## Output Arguments

collapse all

Handle to the electromagnetic source, returned as an `ElectromagneticSourceAssignment` object. For more information, see ElectromagneticSourceAssignment Properties.

collapse all

### Specifying Nonconstant Parameters of Electromagnetic Model

In Partial Differential Equation Toolbox™, use a function handle to specify these electromagnetic parameters when they depend on the coordinates and, for a harmonic analysis, on the frequency:

• Relative permittivity of the material

• Relative permeability of the material

• Conductivity of the material

• Charge density as source (can depend on space only)

• Current density as source (can depend on space only)

• Voltage on the boundary (can depend on space only)

• Magnetic potential on the boundary (can depend on space only)

• Electric field on the boundary (can depend on space only)

• Magnetic field on the boundary (can depend on space only)

For example, use function handles to specify the relative permittivity, charge density, and voltage on the boundary for `emagmodel`.

```electromagneticProperties(emagmodel, ... "RelativePermittivity", ... @myfunPermittivity) electromagneticSource(emagmodel, ... "ChargeDensity",@myfunCharge, ... "Face",2) electromagneticBC(emagmodel, ... "Voltage",@myfunBC, ... "Edge",2)```

The function must be of the form:

`function emagVal = myfun(location,state)`

The solver computes and populates the data in the `location` and `state` structure arrays and passes this data to your function. You can define your function so that its output depends on this data. You can use any names in place of `location` and `state`.

If you call `electromagneticBC` with `Vectorized` set to `"on"`, then `location` can contain several evaluation points. If you do not set `Vectorized` or set `Vectorized` to `"off"`, then solvers passes just one evaluation point in each call.

• `location` — A structure array containing these fields:

• `location.x` — The x-coordinate of the point or points

• `location.y` — The y-coordinate of the point or points

• `location.z` — For a 3-D or an axisymmetric geometry, the z-coordinate of the point or points

• `location.r` — For an axisymmetric geometry, the r-coordinate of the point or points

Furthermore, for boundary conditions, the solver passes this data in the `location` structure:

• `location.nx` — The x-component of the normal vector at the evaluation point or points

• `location.ny` — The y-component of the normal vector at the evaluation point or points

• `location.nz` — For a 3-D or an axisymmetric geometry, the z-component of the normal vector at the evaluation point or points

• `location.nr` — For an axisymmetric geometry, the r-component of the normal vector at the evaluation point or points

• `state` — A structure array containing this field for a harmonic electromagnetic problem:

• `state.frequency` - Frequency at evaluation points

Relative permittivity, relative permeability, and conductivity get this data from the solver:

• `location.x`, `location.y`, `location.z`, `location.r`

• `state.frequency` for a harmonic analysis

• Subdomain ID

Charge density, current density, electric or magnetic field on the boundary get this data from the solver:

• `location.x`, `location.y`, `location.z`, `location.r`

• Subdomain ID

Voltage or magnetic potential on the boundary get these data from the solver:

• `location.x`, `location.y`, `location.z`, `location.r`

• `location.nx`, `location.ny`, `location.nz`, `location.nr`

When you solve an electrostatic or magnetostatic problem, the output returned by the function handle must be of the following size. Here, `Np = numel(location.x)` is the number of points.

• `1`-by-`Np` if a function specifies the nonconstant relative permittivity, relative permeability, and charge density. For the charge density, the output can also be `Np`-by-`1`.

• `1`-by-`Np` for a 2-D model and `3`-by-`Np` for a 3-D model if a function specifies the nonconstant current density and magnetic potential on the boundary. For the current density, the output can also be `Np`-by-`1` or `Np`-by-`3`.

When you solve a harmonic problem, the output returned by the function handle must be of the following size. Here, `Np = numel(location.x)` is the number of points.

• `1`-by-`Np` if a function specifies the nonconstant relative permittivity, relative permeability, and conductivity.

• `2`-by-`Np` for a 2-D problem and `3`-by-`Np` for a 3-D problem if a function specifies the nonconstant electric or magnetic field.

• `2`-by-`Np` or `Np`-by-`2` for a 2-D problem and `3`-by-`Np` or `Np`-by-`3` for a 3-D problem if a function specifies the nonconstant current density and the field type is electric.

• `1`-by-`Np` or `Np`-by-`1` for a 2-D problem and `3`-by-`Np` or `Np`-by-`3` for a 3-D problem if a function specifies the nonconstant current density and the field type is magnetic.

If relative permittivity, relative permeability, or conductivity for a harmonic analysis depends on the frequency, ensure that your function returns a matrix of `NaN` values of the correct size when `state.frequency` is `NaN`. Solvers check whether a problem is nonlinear or time dependent by passing `NaN` state values and looking for returned `NaN` values.

### Additional Arguments in Functions for Nonconstant Electromagnetic Parameters

To use additional arguments in your function, wrap your function (that takes additional arguments) with an anonymous function that takes only the `location` and `state` arguments. For example:

```emagVal = @(location,state) myfunWithAdditionalArgs(location,arg1,arg2...) electromagneticBC(model,"Edge",3,"Voltage",emagVal) ```

## Version History

Introduced in R2021a