electromagneticSource

(To be removed) Specify current density, charge density, and magnetization for electromagnetic model

Since R2021a

electromagneticSource will be removed. Use cellLoad and faceLoad instead. (since R2023a) For more information on updating your code, see Version History.

Syntax

electromagneticSource(emagmodel,"ChargeDensity",rho)

electromagneticSource(emagmodel,"CurrentDensity",J)

electromagneticSource(emagmodel,"Magnetization",M)

electromagneticSource(___,RegionType,RegionID)

emagSource = electromagneticSource(___)

Description

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

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.

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.

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

Examples

Specify Charge Density on Entire Geometry

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

Input Arguments

emagmodel — Electromagnetic model

ElectromagneticModel object

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.

rho — Charge density

real number | function handle

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

J — Current density

real number | column vector | function handle | ConductionResults object

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

M — Magnetization

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

RegionType — Geometric region type

"Face" for a 2-D model | "Cell" for a 3-D model

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

Data Types: char | string

RegionID — Region ID

vector of positive integers

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

emagSource — Handle to electromagnetic source

ElectromagneticSourceAssignment object

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

More About

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

R2025a: To be removed

electromagneticSource will be removed. Use the cellLoad and faceLoad instead.

For example, you can specify charge density on the entire geometry for an electrostatic analysis as follows.

model = femodel(AnalysisType="electrostatic", ...
                Geometry="PlateHoleSolid.stl");
model.CellLoad = cellLoad(ChargeDensity=10);

The unified finite element model workflow defines the type of a problem and all of its parameters as the properties of an femodel object. This object enables you to specify physical parameters for structural, thermal, and electromagnetic types of analyses. The solver in the unified workflow uses only the parameters (properties) appropriate for the current analysis type while ignoring all other properties. If you switch the analysis type by setting the AnalysisType property of the model, the solver uses the appropriate set of properties corresponding to the new analysis type.

For more help migrating your existing code that uses ElectromagneticModel to the unified finite element workflow, see Migration from Domain-Specific to Unified Workflow.

R2023a: Nonlinear magnetostatics

Magnetization and current density can depend on the magnetic flux density, magnetic potential, and its gradients.

R2022b: Magnetization value for permanent magnets

Magnetization can be specified to account for materials generating their own magnetic fields in a magnetostatic analysis workflow.