electromagneticSource

Specify current density, charge density, and magnetization for electromagnetic model

Since R2021a

Syntax

``electromagneticSource(emagmodel,"ChargeDensity",rho)``
``electromagneticSource(emagmodel,"CurrentDensity",J)``
``electromagneticSource(emagmodel,"Magnetization",M)``
``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.For a 3-D magnetostatic analysis, you can specify current density by using the DC conduction results. See `ConductionResults`. The toolbox does not support conduction results as a source of current density for a 2-D magnetostatic analysis, in which case current density must be a scalar or a function handle returning a scalar that represents out-of-plane current.```
````electromagneticSource(emagmodel,"Magnetization",M)` specifies the magnetization. The solver uses a magnetization to model permanent magnets in a magnetostatic workflow.```

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: [] Magnetization: [] ```

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] Magnetization: [] ```

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: [] Magnetization: [] ```
`sc2 = electromagneticSource(emagmodel,"Face",2,"ChargeDensity",0.28)`
```sc2 = ElectromagneticSourceAssignment with properties: RegionType: 'Face' RegionID: 2 ChargeDensity: 0.2800 CurrentDensity: [] Magnetization: [] ```

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: [] Magnetization: [] ```

Use a solution obtained by performing DC conduction analysis to specify current density for a magnetostatic model.

Create an electromagnetic model for DC conduction analysis.

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

Import and plot a geometry representing a plate with a hole.

```gm = importGeometry(emagmodel,"PlateHoleSolid.stl"); pdegplot(gm,"FaceLabels","on","FaceAlpha",0.3)```

Specify the conductivity of the material.

`electromagneticProperties(emagmodel,"Conductivity",6e4);`

Apply the voltage boundary conditions on the left, right, and back faces of the plate.

`electromagneticBC(emagmodel,"Voltage",0,"Face",[1 3 5]);`

Specify the surface current density on the front face of the geometry and on the face bordering the hole.

`electromagneticBC(emagmodel,"SurfaceCurrentDensity",100,"Face",[2 7]);`

Generate the mesh.

`generateMesh(emagmodel);`

Solve the model.

`R = solve(emagmodel);`

Change the analysis type of the model to magnetostatic.

`emagmodel.AnalysisType = "magnetostatic";`

This model already has a quadratic mesh that you generated for the DC conduction analysis. For a 3-D magnetostatic model, the mesh must be linear. Generate a new linear mesh. The `generateMesh` function creates a linear mesh by default if the model is 3-D and magnetostatic.

`generateMesh(emagmodel);`

Specify the current density for the entire geometry using the DC conduction solution.

`electromagneticSource(emagmodel,"CurrentDensity",R)`
```ans = ElectromagneticSourceAssignment with properties: RegionType: 'Cell' RegionID: 1 ChargeDensity: [] CurrentDensity: [1x1 pde.ConductionResults] Magnetization: [] ```

Specify magnetization on a face in a magnetostatic analysis.

Create a unit square geometry with a circle in its center. The circle represents a permanent magnet.

```L = 0.8; r = 0.25; sq = [3 4 -L L L -L -L -L L L]'; circ = [1 0 0 r 0 0 0 0 0 0]'; gd = [sq,circ]; sf = "sq + circ"; ns = char('sq','circ'); ns = ns'; g = decsg(gd,sf,ns);```

Plot the geometry with the face labels.

`pdegplot(g,"FaceLabels","on")`

Create a magnetostatic model and include the geometry in the model.

```emagmodel = createpde("electromagnetic","magnetostatic"); geometryFromEdges(emagmodel,g);```

Specify the magnetization magnitude.

`M = 1;`

To make the circle represent a permanent magnet, specify the uniform magnetization in the positive x-direction.

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

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, a function handle, or a `ConductionResults` object. Use a function handle to specify a nonconstant current density.

For magnetostatic analysis, the current density must be

• A real number or a function handle for a 2-D model. The toolbox does not support conduction results as a source of current density for a 2-D magnetostatic analysis.

• A column vector of three elements, a `ConductionResults` object, or a function handle for a 3-D model.

For harmonic analysis with the electric field type, the toolbox multiplies the specified current density by `-i` and by frequency. The current density must be

• A column vector of two elements or a function handle that depends on the coordinates for a 2-D model.

• A column vector of three elements or a function handle that depends on the coordinates for a 3-D model.

For harmonic analysis with the magnetic field type, the toolbox uses the curl of the specified current density. The current density must be

• A scalar or a function handle that depends on the coordinates for a 2-D model.

• A column vector of three elements or a function handle that depends on the coordinates for a 3-D model.

For details, see More About.

Data Types: `double` | `function_handle`

Magnetization, specified as 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. Use a function handle to specify a magnetization that depends on the coordinates. For details, see More About.

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)

• Magnetization (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)

• Surface current density 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 the solver 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, magnetization, surface current density on the boundary, and 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, magnetostatic, or DC conduction 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, or 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`.

• `2`-by-`Np` for a 2-D model and `3`-by-`Np` for a 3-D model if a function specifies the nonconstant magnetization or surface current density on the boundary.

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 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

expand all