1. Generalities
2. Initialization
3. Field sources
4. Magnetic materials
5. Space transformations
6. Field computation
7. Utilities

1. Generalities

The current version of Radia is a separate application which is interfaced to Mathematica via MathLink. To run Radia, one needs Mathematica to be installed on one's computer or local network.

The Radia 4.x runs on the following platforms, with the following versions of Mathematica:

  • PowerMac (tested on MacOS 7.5) with Mathematica 3.0 or later;
  • Windows 95/NT (tested on Windows 95 and NT 4.0) with Mathematica 3.0 or later.

Any calculation with Radia consists in preparing and executing cells in a Mathematica notebook, where Radia interface functions are used along with built-in or user-defined Mathematica functions.

The collection of Radia interface functions consists of two parts:

A) Primary functions, defined in Radia.exe file (compiled from C++ source). The names of these functions start with "rad" ("r" in lower case), like radObjRecCur[...].

B) Secondary functions, defined in init.m file written in Mathematica Language. The names of these functions start with "Rad" (capital "R"), like RadObjFullMag[...]. These functions call the Primary Radia functions, as well as built-in Mathematica functions. The aim of the Secondary functions is to allow more convenient usage of the basic Radia functionality for the expense of the possibilities given by Mathematica.

Both the Primary and Secondary functions can (or should) be used directly in Mathematica notebooks.

Normally, the process of magnetostatic calculations with Radia includes the following steps

(x) Installing Radia;
(I) Describing the problem in Mathematica Language in terms of Radia functions:
(I-a) creating initial objects - field sources prototypes;
(I-b) creating and applying appropriate magnetic materials to the objects created at (I-a);
(I-c) grouping objects by placing them in containers;
(I-d) creating and applying necessary transformations (boundary conditions);
(II) Solving the problem:
(II-a) applying any subdivision to the objects created;
(II-b) constructing an interaction matrix corresponding to the problem (I) and particular subdivision (II-a), and executing a relaxation procedure;
(II-c) computing any components (as field induction, field integrals along straight line, potentials or forces) of the magnetic field created by the "relaxed" objects;
(x) Uninstalling Radia.


Steps (I-b) - (I-d) and (II-a) - (II-b) are optional (for example, if one has only current carrying elements, one does not need any relaxation procedure). The order of steps (I-b) - (I-d), (II-a) can be different.

To obtain a solid solution in presence of iron, one may need certain iterations with the steps (II-a) - (II-c).

We strongly recommend to start using Radia from the examples supplied with the package. We also assume that before starting Radia, users have already some experience with Mathematica. In any case, this experience is necessary for performing advanced magnetostatic calculations with Radia.

The current reference mainly explains the Primary Radia functions.

To get help on any Radia function from within a Mathematica notebook, general Mathematica mechanisms can be used. For example, the execution of a notebook cell with the input   ?rad*   gives a list of all the Primary Radia functions   (?Rad*   for the list of all the Secondary functions). Then, to receive help on a particular function, one can copy its name from the above list, paste it into a new cell with the question mark in front, e.g.:  ?radObjRecMag  , and execute the cell. This gives the function template and a usage message for the function.

2. Initialization

The Initialization of Radia is performed by executing the following command in an input cell of a Mathematica notebook:

<<Radia`;

For the above command to be executed well, it is necessary that the Radia package is located in the  ...:AddOns:Applications:Radia directory of the Mathematica installation. It is important that the files Radia.exe and init.m are located in this directory. For detailed instructions on the actions to be performed for the proper installation of  the Radia on a particular platform see the ReadMe file dedicated to that platform.

This command loads all the functions presenting in the Radia.exe and init.m files into memory and starts special process that actually performs all the Radia computations. If this process already exists, it is terminated and re-started. No function starting with "rad" or "Rad" can be executed before <<Radia`; is executed.

3. Field sources

radObjRecCur , radObjArcCur , radObjRaceTrk , radObjFlmCur, radObjRecMag, radObjThckPgn, radObjPolyhdr, radObjMltExtPgn, radObjMltExtRtg, radObjM, radObjBckg, radObjCnt, radObjAddToCnt, radObjCntStuf, radObjDivMag, radObjCutMag, radObjDpl, radObjDegFre, radObjDrwAtr, radObjDrw, radObjDrwQD3D

Open reference guide contents in new window

radObjRecCur[{x,y,z}, {wx,wy,wz}, {jx,jy,jz}]
Action Creates a current carrying rectangular parallelepipedic block.
Return An integer number referencing the object.
Vars {x,y,z}: list of three real numbers specifying Cartesian coordinates of the block's center of gravity (by default in mm).

{wx,wy,wz}: list of three real numbers specifying the block's dimensions (by default in mm).

{jx,jy,jz}: list of three real numbers specifying the vector of current density in the block (by default in A/mm^2).
Notes Orientation: faces parallel to the XY, XZ and YZ planes of the laboratory frame.
radObjArcCur[{x,y,z}, {rmin,rmax}, {phimin,phimax}, h, nseg, j, "man|auto" :"man"]
Action Creates a current carrying finite-length arc of rectangular cross-section.
Return An integer number referencing the object.
Vars {x,y,z}: list of three real numbers specifying Cartesian coordinates of the arc's center (by default in mm).

{rmin,rmax}: list of two real numbers specifying inner and outer radii of curvature of the conductor, respectively (by default in mm).

{phimin,phimax}: list of two real numbers specifying initial and final angles of the arc, respectively (by default in radian).

h: real number specifying height of the arc block (by default in mm).

nseg: circumference segmentation number.

j: real number specifying current density along curved path (by default in A/mm^2).

"man|auto": a string switch for setting manual ("man") or automatic ("auto") mode when computing the field produced by the arc.
Notes Orientation: rotation axis along Z, curved path parallel to the XY plane of the laboratory frame; angles  phimin, phimax are off positive direction of the X axis.

Current flows along the curved path.

The allowed limits for  phimin, phimax  are:  0 < phimin < phimax < 2*Pi.

Circumference segmentation number nseg is used at computing the field from the arc in manual mode ("man|auto" switch set to "man") and at visualization of the arc.

In the automatic mode ("man|auto" switch set to "auto") any computation of the field produced by the arc is made according to the general accuracy levels set up by the function radFldCmpCrt[...].

The function can be used without the "man|auto" switch variable. In this case, the field computation mode for the arc is assumed to be manual.
radObjRaceTrk[{x,y,z}, {rmin,rmax}, {lx,ly}, h, nseg, j, "man|auto" :"man"]
Action Creates a current carrying racetrack coil consisting of four 90-degree bents connected by four straight parts.
Return An integer number referencing the object.
Vars {x,y,z}: list of three real numbers specifying Cartesian coordinates of the racetrack's center (by default in mm).

{rmin,rmax}: list of two real numbers specifying inner and outer radii of curvature of the racetrack's bents, respectively (by default in mm).

{lx,ly}: list of two real numbers specifying lengths of horizontal and longitudinal straight parts of the racetrack, respectively (by default in mm).

h: real number specifying height of the racetrack (by default in mm).

nseg: bent circumference segmentation number.

j: real number specifying current density (by default in A/mm^2).

"man|auto": a string switch for setting manual ("man") or automatic ("auto") mode when computing the field produced by the bents.
Notes Orientation: bents' rotation axes along Z,  curved path parallel to XY plane of the laboratory frame, straight parts along X and Y axes.

Both bents and straight parts of the racetrack have rectangular cross-sections.

Lengths of the straight parts can be zero (lx=0,ly=0).

Bent circumference segmentation number nseg is used when computing the field from the bents in manual mode ("man|auto" switch set to "man") and at visualization of the racetrack.

In the automatic mode ("man|auto" switch set to "auto") any computation of the field produced by the bents is made according to the general accuracy levels set up by the function radFldCmpCrt[...].

The function can be used without the "man|auto" switch variable. In this case, the field computation mode for the bents is assumed to be manual.

The racetrack coil is not an "atomic" object: it is a container with four current carrying arcs and four current-carrying rectangular parallelepipedic blocks.
radObjFlmCur[{{x1,y1,z1}, {x2,y2,z2},...}, i]
Action Creates a  current-carrying filament polygonal line conductor.
Return An integer number referencing the object.
Vars {{x1,y1,z1}, {x2,y2,z2},...}: list of lists of three real numbers specifying Cartesian coordinates of edge points of the polygonal line segments (by default in mm).

i: current (by default in A).
Notes The polygonal line can consist of any number of segments larger than or equal to one, so the minimum number of the edge points should be two.

The polygonal line is open by default; for it to be closed, the last point should be the same as the first one.

The current is directed from the point {x1,y1,z1} to {x2,y2,z2} and so on.
radObjRecMag[{x,y,z}, {wx,wy,wz}, {mx,my,mz} :{0,0,0}]
Action Creates a rectangular parallelepipedic block with magnetization.
Return An integer number referencing the object.
Vars {x,y,z}: list of three real numbers specifying Cartesian coordinates of the block's center of gravity (by default in mm).

{wx,wy,wz}: list of three real numbers specifying the block's dimensions (by default in mm).

{mx,my,mz}: list of three real numbers specifying magnetization vector in the block (by default in Tesla).
Notes Orientation: faces parallel to the XY, XZ and YZ planes of the laboratory frame.

The magnetization of the block is initialized to {mx,my,mz}. If any magnetic material is later applied to the block, it fully overrides this value of the magnetization. At the relaxation, the value of the magnetization will be further modified.

The function can be called without the magnetization vector {mx,my,mz}. In this case it is assumed to be {0,0,0}.
radObjThckPgn[x, lx, {{y1,z1}, {y2,z2},...}, {mx,my,mz} :{0,0,0}]
Action Creates an extruded polygon (or straight prism) block with magnetization.
Return An integer number referencing the object.
Vars x: real number specifying the horizontal Cartesian coordinate of the block's center (by default in mm).

lx: thickness of the extruded polygon (by default in mm).

{{y1,z1}, {y2,z2},...}: list of lists of two real numbers specifying the polygon in 2D (by default in mm).

{mx,my,mz}: list of three real numbers specifying magnetization vector in the block (by default in Tesla).
Notes Orientation: the extruded polygon bases parallel to YZ plane of the laboratory frame, the extrusion axis parallel to X. Horizontal coordinates of the bases are x-lx/2 and x+lx/2.

The magnetization of the block is initialized to {mx,my,mz}. If any magnetic material is later applied to the block, it fully overrides this value of the magnetization. At the relaxation, the value of the magnetization will be further modified.

The function can be used without the magnetization vector {mx,my,mz}. In this case it is assumed to be {0,0,0}.
radObjPolyhdr[{{x1,y1,z1}, {x2,y2,z2},...}, {{f1n1,f1n2,...}, {f2n1,f2n2,...},...}, {mx,my,mz}:{0,0,0}]
Action Creates a magnetized polyhedron (a volume limited by planes).
Return An integer number referencing the object.
Vars {{x1,y1,z1}, {x2,y2,z2},...}: list of lists of three real numbers specifying Cartesian coordinates of the polyhedron vertex points (by default in mm).

{{f1n1,f1n2,...}, {f2n1,f2n2,...},...}: list of lists of integer numbers specifying indexes of the vertex points from the previous list forming the polyhedron faces.

{mx,my,mz}: list of three real numbers specifying magnetization vector inside the polyhedron (by default in Tesla).
Notes Each face of the polyhedron should be defined by listing the points in a clockwise or counterclockwise order of  rounding the face.

Only convex polyhedrons are supported by Radia. If any non-convex shape should be defined, a user has to define it as a group of several convex shapes.

It is recommended to use radObjDrw[...] Radia function and Show[...] and Graphics3D[...] Mathematica functions to visualize the polyhedron in 3D immediately after creation (to make sure that no error is done at the polyhedron definition).

The magnetization of the block is initialized to {mx,my,mz}. If any magnetic material is later applied to the block, it fully overrides this value of the magnetization. At the relaxation, the value of the magnetization will be further modified.

The function can be used without the magnetization vector {mx,my,mz}. In this case it is assumed to be {0,0,0}.

The polyhedron created by the function radObjPolyhdr[...] can be subdivided into number of smaller polyhedrons and / or parallelepipeds by the function radObjDivMag[...].
radObjMltExtPgn[{{{{x11,y11},{x12,y12},...},z1}, {{{x21,y21},{x22,y22},...},z2},...}, {mx,my,mz}:{0,0,0}]
Action Attempts to create a convex polyhedron or a set of convex polyhedrons based on horizontal slices, which are supposed to be convex planar polygons.
Return An integer number referencing the object.
Vars {{{{x11,y11},{x12,y12},...},z1}, {{{x21,y21},{x22,y22},...},z2},...}: a nested list structure describing the horizontal slice polygons the resulting polyhedron(s) should be based on, where {{x11,y11},{x12,y12},...} are 2D Cartesian coordinates of vertex points of a slice polygon, and z1, z2,... are the slice polygons' attitudes (vertical coordinates). The default units are mm.

{mx,my,mz}: list of three real numbers specifying magnetization vector inside the polyhedron(s) (by default in Tesla).
Notes Each horizontal slice polygon should be defined by listing the points in a clockwise or counterclockwise order of the face rounding.

The horizontal slice polygons should be convex. The use of non-convex slice polygons will result in Radia error messages and may lead to the application crash.

The mutual planar orientation of the slice polygons can be arbitrary, with possibly no parallel segments.

The function tries to generate a convex polyhedron by "putting" a minimal possible mantle surface on the horizontal slices specified. If the set of the slice polygons is such that a single convex polyhedron can not be generated, the function produces a group (container) of convex polyhedrons.

The magnetization of the block(s) produced is initialized to {mx,my,mz}. If any magnetic material is later applied to the block(s), it fully overrides this value of the magnetization. At the relaxation, the value of the magnetization will be further modified.

The function can be used without the magnetization vector {mx,my,mz}. In this case it is assumed to be {0,0,0}.

The polyhedron(s) created by the function radObjMltExtPgn[...] can be subdivided into number of smaller polyhedrons and / or parallelepipeds by the functions  radObjDivMag[...] or radObjCutMag[...].
radObjMltExtRtg[{{{x1,y1,z1},{wx1,wy1}}, {{x2,y2,z2},{wx2,wy2}},...}, {mx,my,mz}:{0,0,0}]
Action Attempts to create a convex polyhedron or a set of convex polyhedrons based on horizontal slices of rectangular shape.
Return An integer number referencing the object.
Vars {{{x1,y1,z1},{wx1,wy1}}, {{x2,y2,z2},{wx2,wy2}},...}: a nested list structure describing the horizontal slice rectangles the resulting polyhedron(s) should be based on, where {x1,y1,z1},{x2,y2,z2},... are Cartesian coordinates of center points of the slice rectangles, and {wx1,wy1},{wx2,wy2},... their dimensions (by default in mm).

{mx,my,mz}: list of three real numbers specifying magnetization vector inside the polyhedron(s) (by default in Tesla).
Notes The function tries to generate a convex polyhedron by "putting" a minimal possible mantle surface on the horizontal slices specified. If the set of the slice rectangles is such that a single convex polyhedron can not be generated, the function produces a group (container) of convex polyhedrons.

The magnetization of the block(s) is initialized to {mx,my,mz}. If any magnetic material is later applied to the block(s), it fully overrides this value of the magnetization. At the relaxation, the value of the magnetization will be further modified.

The function can be used without the magnetization vector {mx,my,mz}. In this case it is assumed to be {0,0,0}.

The polyhedron(s) created by the function radObjMltExtRtg[...] can be subdivided into number of smaller polyhedrons and / or parallelepipeds by the functions radObjDivMag[...] or radObjCutMag[...].
radObjM[obj]
Action Gives coordinates of geometrical center point(s) and magnetization(s) of the object obj.
Return If obj is a 3D object with magnetization: {{{x,y,z},{mx,my,mz}}}, where {x,y,z} and {mx,my,mz} is center point of the 3D object and its magnetization respectively.

If obj is a container: {{{x1,y1,z1},{mx1,my1,mz1}}, {{x2,y2,z2},{mx2,my2,mx2}},...},   where {x1,y1,z1},{x2,y2,x2},... are center points of the 3D objects with magnetization which are present in the container, {mx1,my1,mz1},{mx2,my2,mx2},... their magnetization vectors.

If obj is a 3D object without magnetization or a container with no 3D objects with magnetization: {}.
Vars obj: an integer number referencing the magnetic field source object.
Notes The function can be efficiently used for watching the magnetization inside the iron after the relaxation, in order to estimate quality of the relaxation or to analyze which parts of the geometry are strongly saturated, which are not, etc. (the latter being very useful for magnetostatics design works).

To visualize the magnetization vectors as a set of arrows in space, use the function ListPlotVectorField3D[...] from the Mathematica add-on package Graphics`PlotField3D`,  like ListPlotVectorField3D[radObjM[obj],...]. Before that, don't forget to load the add-on package by executing <<Graphics`PlotField3D`. See the Mathematica Standard Add-on Packages documentation for the details of the  ListPlotVectorField3D[...] function.
radObjBckg[{bx,by,bz}]
Action Creates a uniform background magnetic field.
Return An integer number referencing the object.
Vars {bx,by,bz}: list of three real numbers specifying the components of the uniform background magnetic field.
Notes No particular 3D shape is associated with this object.
radObjCnt[{obj1,obj2,...}]
Action Creates a container for objects capable of producing a magnetic field.
Return An integer reference number for the container.
Vars {obj1,obj2,...}: list of integer numbers referencing individual objects to be placed into the container.
Notes Containers are individual objects: at field computation, they can be used the same way as any other individual objects capable of producing magnetic field.

Containers can include any kind of object capable of producing magnetic field: current-carrying objects and/or objects with magnetization or magnetic material applied, and/or other containers.

Containers can be created empty:  radObjCnt[{}]  creates a container with no objects inside.
radObjAddToCnt[cnt, {obj1,obj2,...}]
Action Adds objects to the container referenced by cnt.
Return Value of  cnt.
Vars cnt: an integer number referencing the container.

{obj1,obj2,...}: list of integer numbers referencing individual objects to be added to the container.
Notes Containers can include any kind of object capable of producing magnetic field: current-carrying objects and/or objects with magnetization or magnetic material applied, and/or other containers.
radObjCntStuf[obj]
Action Gives a list of general indexes of the objects in container if obj is a container.
Return If obj is a container: list of integer numbers referencing objects in the container.

If  obj is not a container: {obj}.
Vars obj: an integer number referencing the container.
radObjDivMag[obj, {{k1,q1},{k2,q2},{k3,q3}}, {"pln",{n1x,n1y,n1z},{n2x,n2y,n2z},{n3x,n3y,n3z}} | {"cyl",{{ax,ay,az},{vx,vy,vz}},{px,py,pz},rat}, kxkykz->Numb|Size, Frame->Loc|Lab|LabTot]

or radObjDivMag[obj, {{k1,q1},{k2,q2},{k3,q3}}]

or radObjDivMag[obj, {k1,k2,k3}]
Action Subdivides the object referenced by obj.
Return Value of obj.
Vars obj: an integer number referencing the object, which can be an object with magnetization or magnetic material applied, or a container having such objects.

{{k1,q1},{k2,q2},{k3,q3}}: list of three lists of two numbers giving the main parameters of the subdivision, where k1,k2,k2 are (depending on the value of the option kxkykz->Numb|Size) numbers of parts or average sizes of objects to be produced in different directions; q1,q2,q3 are the corresponding ratios of the last-to-first part sizes.

{"pln", {n1x,n1y,n1z}, {n2x,n2y,n2z}, {n3x,n3y,n3z}}: a nested list structure providing additional specifications for the subdivision by three sets of parallel planes, where "pln" is the string identificator of the subdivision by parallel planes; {n1x,n1y,n1z},{n2x,n2y,n2z} and {n3x,n3y,n3z} are Cartesian coordinates of the vector normals for the three sets of parallel planes.

{"cyl", {{ax,ay,az}, {vx,vy,vz}}, {px,py,pz}, rat}: a nested list structure providing additional specifications for the subdivision according to elliptic cylinder, where "cyl" is the string identificator of this type of subdivision; {{ax,ay,az},{vx,vy,vz}} are, respectively,  Cartesian coordinates of a point and a vector defining the cylinder axis; {px,py,pz} are Cartesian coordinates of a point specifying the orientation of one of the ellipse exes in the cylinder base (the ellipse axis is exactly the perpendicular from the point {px,py,pz} to the cylinder axis), and rat is the ratio of the two exes lengths of the ellipse in the cylinder base.

kxkykz->Numb|Size: an optional parameter specifying whether the k1,k2,k3 from the main subdivision parameters list should be treated as subdivision numbers (kxkykz->Numb, default) or as average dimensions of the objects to be produced by the subdivision (kxkykz->Size).

Frame->Loc|Lab|LabTot: an optional parameter specifying whether the subdivision should be performed in local frames of the objects as they were originally created (Frame->Loc, default) or in the laboratory frame (Frame->Lab or Frame->LabTot).
Notes As a result of the subdivision, a container actually appears in place of the object obj; however, this container is referenced by the old value of the variable obj.

The variables of the function starting from the third one are optional. If the third variable is not used, the subdivision is performed by three sets of parallel planes for which the unit vectors of the Cartesian frame are the normals.

If the third variable is used in the form {"pln",...}, the subdivision is performed by three sets of parallel planes which are normal to the vectors {n1x,n1y,n1z},{n2x,n2y,n2z} and {n3x,n3y,n3z}. The distances between the cutting parallel planes in each of the three sets are defined by the subdivision parameters {k1,q1},{k2,q2} and {k3,q3}.

If the third variable is used in the form {"cyl",...}, the subdivision is performed by a system of coaxial elliptic cylinders. The cylinder axis is defined by the point {ax,ay,az} and vector {vx,vy,vz}. One of two axes of the cylinder base ellipses is exactly the perpendicular from the point {px,py,pz} to the cylinder axis; rat is the ratio of the ellipse axes lengths. In this case of the subdivision, the parameters {k1,q1},{k2,q2} and {k3,q3} correspond to radial, azimuthal and axial directions respectively.

In the present version of Radia, a user has to choose himself the optimal methods of subdivision for different parts of the geometry under simulation. Qualitatively, an efficient segmentation is the segmentation such that the faces of the sub-volumes to be produced appear (after the relaxation!) parallel or perpendicular to the magnetization vector inside the sub-volumes. So, experience of a magnetostatics designer and a good qualitative understanding of the cases under study may strongly help to perform efficient subdivision and, as a sequence, to get more precise and/or fast numerical solution.

The rules for the optional parameters kxkykz->... and Frame->... comply with Mathematica mechanism of options. For example, to specify the subdivision in local frames, one should type Frame->Loc with no any quotation marks.

The action of Frame->Lab and Frame->LabTot is different only for containers. Frame->LabTot means that all the container members are subdivided in the laboratory frame as one entity, by the same planes, whereas Frame->Lab corresponds to separate subdivision of the objects in the container, as they were not the container members.

The subdivision with the options Frame->Lab or Frame->LabTot preserves symmetries (or transformations with multiplicity more than 1) previously applied to the object, so that any mirrors (images) of the original object become mirrors of the objects produced by the subdivision of the original object in the laboratory frame.

For simple uniform subdivision in directions X, Y and Z in local frames, the function can be called as radObjDivMag[obj, {k1,k2,k3},...] or radObjDivMag[obj, {{k1,1},{k2,1},{k3,1}},...].

If obj is a container at the input of radObjDivMag[obj,...], then the subdivision is applied only to the objects with magnetization or magnetic material applied (if they are present in the container), with no effect on any current-carrying objects.
radObjCutMag[obj, {x,y,z}, {nx,ny,nz}, Frame->Loc|Lab]
Action Cuts the object obj by a plane passing through the point {x,y,z} normally to the vector {nx,ny,nz}.
Return A list of two indexes referencing the objects produced by the cutting (if the cutting plane crosses the object obj) or the value of obj (if the cutting plane does not cross the object obj).
Vars obj: an integer number referencing the object to be cutted, which can be an object with magnetization or magnetic material applied, or a container having such objects.

{x,y,z}: list of three real numbers specifying Cartesian coordinates of a point on the cutting plane (by default in mm). {nx,ny,nz}: list of three real numbers specifying Cartesian coordinates the cutting plane normal. Frame->Loc|Lab: an optional parameter specifying whether the subdivision should be performed in local frames of the objects as they were originally created (Frame->Loc) or in the laboratory frame (Frame->Lab, default).
Notes As different from the function radObjDivMag, radObjCutMag does not replace the initial object by a container of objects produced by the cutting.

Cutting a container produces two containers (if the cutting plane crosses the container stuff).
radObjDpl[obj, FreeSym->False|True]
Action Duplicates the object referenced by obj.
Return An integer number referencing the new object - a copy of the one referenced by obj.
Vars obj: an integer number referencing the object to be duplicated.

FreeSym->False|True: an optional parameter specifying whether the symmetries (transformations with multiplicity more than one) previously applied to the object obj should be simply copied at the duplication (FreeSym->False, default), or a container of new independent objects should be created in place of any symmetry previously applied to the object obj. In both cases the final object created by the duplication has exactly the same geometry as the initial object obj.
Notes This function actually duplicates the object referenced by obj together with the materials and/or other properties if they were previously applied to the object obj.

If applied to a container, the function duplicates the container itself and all the objects being present in the container.
radObjDegFre[obj]
Action Gives number of degrees of freedom for the relaxation of the object obj.
Return An integer number specifying number of degrees of freedom.
Vars obj: an integer number referencing the object.
Notes The number of degrees of freedom is:
  • 3 - for a 3D object with magnetic material applied;
  • Sum of degrees of freedom over all the objects present in the container - for a container;
  • 0 - in other cases.
radObjDrwAtr[obj, {r,g,b}, thcn]
Action Applies drawing attributes - an RGB color and line thickness to the object referenced by obj.
Return Value of obj.
Vars obj: an integer number referencing the object.

{r,g,b}: list of three real numbers specifying the RGB color to the object.

thcn: a real number specifying the line thickness when drawing the object.
Notes It should take place for the {r,g,b}:  0<r<1,  0<g<1,  0<b<1.

The initial default is thcn=0.001 for 3D Mathematica graphics.
radObjDrw[obj]
Action Prepares a set of 3D graphical primitives representing the object  obj  in space.
Return A Mathematica expression describing graphical primitives for later use as argument of  Graphics3D Mathematica function.
Vars obj: an integer number referencing the object.
Notes The obj can refer to any Radia object capable of producing magnetic field, including containers.

To get a final 3D plot representing the object  obj, use Show[Graphics3D[radObjDrw[obj]]]. Both Show[...] and Graphics3D[...] built-in Mathematica functions may have options as extra arguments (for more information see Mathematica Books or on-line help of  Mathematica).

The default options for the Radia graphics are set up by the Secondary functions RadPlot3DOptions and RadPlotOptions.

By default, the graphical primitives visualizing the Radia objects are shown in accordance with default Mathematica rules of shading.
radObjDrwQD3D[obj, EdgeLines->True|False, Axes->True|False]
Action Starts an application for active ("live") viewing of 3D geometry of the object obj.
Return A new window of a 3D Viewer application with necessary interface for active viewing of the object's geometry. During the viewing, the Mathematica notebook is in the execution mode. After the Viewer is exited, the value of obj is returned to the notebook output cell.
Vars obj: an integer number referencing the object.

EdgeLines->True|False: an optional parameter specifying whether the edge lines of the object's geometry are outlined in the active drawings or not (default: EdgeLines->True).

Axes->True|False: an optional parameter specifying whether the axes of the (laboratory) Cartesian frame are shown in the active drawings or not (default: Axes->True).
Notes IMPORTANT: For the function to be executed, the QuickDraw 3D graphics library from Apple should be properly installed on your system (i.e., a number of corresponding shared libraries, or DLLs, should be located in your system folder). The versions of QuickDraw 3D for Power Macintosh and Windows 95/NT can be currently downloaded for free from the Apple web site (http:/www.apple.com/quicktime/qd3d/). After downloading the QuickDraw 3D pack, follow the installation instructions supplied by Apple.

Once the QuickDraw 3D is properly installed, the execution of the function radObjDrwQD3D[...] will start a 3D Viewer application with the object obj loaded for active viewing. The 3D Viewer has simple intuitive interface necessary to manipulate the 3D views of the object loaded (on-line changing the camera position, perspective, etc.). A user can save the geometry under observation to a file in 3D Metafile Format (3DMF) for further graphical processing / converting by the applications that support this format ("SaveAs" from the "File" menu of the 3D Viewer). After the viewing is finished, a user has to choose "Exit" (or "Quit") from "File" menu of the Viewer. This will terminate the Viewer and release the cell in the Mathematica notebook from which the function radObjDrwQD3D[...] was executed.

The obj can refer to any Radia object capable of producing magnetic field, including containers. The object can have color attributes applied by the function radObjDrwAtr[...].

4. Magnetic materials

radMatLin ,radMatSatIso ,radMatSatAniso , radMatApl , radMatMvsH

Open reference guide contents in new window

radMatLin[{ksipar,ksiper}, mr] or radMatLin[{ksipar,ksiper}, {mrx,mry,mrz}]
Action Creates a linear anisotropic magnetic material.
Return An integer number referencing the material.
Vars {ksipar,ksiper}: list of two real numbers specifying magnetic susceptibility values in parallel and perpendicular  directions to easy magnetization axis.

mr: a real number with absolute value giving magnitude of the remanent magnetization vector (by default in Tesla).

{mrx,mry,mrz}: list of three real numbers specifying remanent magnetization vector (by default in Tesla).
Notes The function can be used in one of the two forms (see the templates above).

If the function is called in the first form, the orientation of the remanent magnetization vector (giving the orientation of the easy magnetization axis) is specified by the initial magnetization vector in the object to which the material is later applied. If mr>0 (mr<0), the remanent magnetization is set to be parallel (antiparallel) to the initial magnetization vector in the object. The magnitude of the remanent magnetization vector is |mr|.

If the function is called in the second form, the remanent magnetization vector (and thus the orientation of the easy magnetization axis) is explicitly defined by the list argument {mrx,mry,mrz}, with no dependence on the initial magnetization vector in the object to which the material is later applied.

The second form of the function is obsolete.
radMatSatIso[{ksi1,ms1},{ksi2,ms2},{ksi3,ms3}] or radMatSatIso[{ms1,ms2,ms3}, {ks1,ks2,ks3}]
Action Creates a nonlinear isotropic magnetic material.
Return An integer number referencing the material.
Vars ks1,ks2,ks3: three real numbers specifying partial susceptibilities at zero field.

ms1,ms2,ms3: three real numbers specifying partial saturation magnetizations (by default in Tesla).
Notes

For this type of material, the dependence of the magnetization  vector M on the field strength vector H is given by the formula:

M = (H/|H|)*[ms1*tanh(ks1*|H|/ms1) + ms2*tanh(ks2*|H|/ms2) + ms3*tanh(ks3*|H|ms3)].

The second form of the function is obsolete.
radMatSatAniso[{{ksi1par,ms1par}, {ksi2par,ms2par}, {ksi3par,ms3par}, ksi0par, hc}, {{ksi1per,ms1per}, {ksi2per,ms2per}, {ksi3per,ms3per}, ksi0per}] or radMatSatAniso[{{ksi1par,ms1par}, {ksi2par,ms2par}, {ksi3par,ms3par}, ksi0par, hc}, ksi0per]
Action Creates a nonlinear anisotropic magnetic material.
Return An integer number referencing the material.
Vars ksi0par, ksi1par, ksi2par, ksi3par: four real numbers specifying partial susceptibilities at zero field for the magnetization component parallel to the easy magnetization axis.

ms1par, ms2par, ms3par: three real numbers specifying partial saturation for the magnetization component parallel to the easy magnetization axis (by default in Tesla).

hc: a real number specifying coercivity for the component parallel to the easy magnetization axis.

ksi0per, ksi1per, ksi2per, ksi3per: four real numbers specifying partial susceptibilities at zero field for the magnetization component perpendicular to the easy magnetization axis.

ms1per, ms2per, ms3per: three real numbers specifying partial saturation for the magnetization component perpendicular to the easy magnetization axis (by default in Tesla).
Notes For this type of material, the magnetization component parallel to the easy magnetization axis is given by:

Mpar=  ms1par*tanh[ksi1par*(Hpar-hc)/ms1par] + ms2par*tanh[ksi2par*(Hpar-hc)/ms2par] + ms3par*tanh[ksi3par*(Hpar-hc)/ms3par] + ksi0par*(Hpar-hc),

Hpar=H*e,  where e is a unit vector of the easy magnetization axis, and H is the field strength vector.

The magnetization component perpendicular to the easy magnetization axis is given by:

Mper=  [ms1per*tanh[ksi1per*|Hper|/ms1per] + ms2per*tanh[ksi2per*|Hper|/ms2per] + ms3per*tanh[ksi3per*|Hper|/ms3per]]*Hper/|Hper| + ksi0per*Hper

or Mper=  ksi0per*Hper,  where  Hper= H - Hpar*e.

The total magnetization vector is M=  Mpar*e + Mper.
radMatApl[obj, mat]
Action Applies material referenced by mat,  to object referenced by obj.
Return Value of obj.
Vars obj: an integer number referencing an object created by radObjRecMag, radObjThckPgn or radObjPolyhdr, or a container with at least one object created by any of these functions.

mat: an integer number referencing a material.
Notes If  obj  is a container, the material mat is applied only to the objects in the container that were created by radObjRecMag, radObjThckPgn or radObjPolyhdr.
radMatMvsH[obj, mid, {hx,hy,hz}]
Action Computes magnetization from field strength vector for the object or material referenced by obj.
Return The magnetization vector or one of its components, according to the value of variable mid.
Vars obj: an integer number referencing a material or an object to which material was applied.

mid: output magnetization component identification string. The following values of mid are allowed:

  • "mx" (for horizontal magnetization component),
  • "my" (for longitudinal magnetization component),
  • "mz" (for vertical magnetization component),
  • "" (for all three components of the magnetization vector).

{hx,hy,hz}: list of three real numbers specifying components of the  magnetic field strength vector.
Notes If the magnetization component identification string mid is "mxmy" or "mzmx" or "mymz"  etc., the function returns list of two real numbers - components of the magnetization vector, in the order corresponding to the mid string; "mxmymz" is equivalent to "".


5. Space transformations

radTrfTrsl , radTrfRot , radTrfPlSym , radTrfInv , radTrfCmbL , radTrfCmbR , radTrfOrnt , radTrfMlt

Open reference guide contents in new window

radTrfTrsl[{vx,vy,vz}]
Action Creates a translation.
Return An integer number referencing the transformation.
Vars {vx,vy,vz}: list of three real numbers specifying the translation vector.
Notes The translation vector can be {0,0,0}.
radTrfRot[{x,y,z}, {vx,vy,vz}, phi]
Action Creates a rotation.
Return An integer number referencing the transformation.
Vars {x,y,z}: list of three real numbers specifying Cartesian coordinates of a point on the rotation axis.

{vx,vy,vz}: list of three real numbers specifying components of the rotation axis vector.

phi: a real number specifying the rotation angle.
Notes The rotation axis vector can be of any length.

The allowed limit for phi are: 0 < phi < 2*Pi.
radTrfPlSym[{x,y,z}, {nx,ny,nz}]
Action Creates a plane symmetry.
Return An integer number referencing the transformation.
Vars {x,y,z}: list of three real numbers specifying Cartesian coordinates of a point on the symmetry plane.

{nx,ny,nz}: list of three real numbers specifying components of the vector normal to the plane .
Notes The plane normal vector can be of any length.
radTrfInv[]
Action Creates a field inversion. Magnetization and current densities are inverted while the geometry is unchanged.
Return An integer number referencing the transformation.
radTrfCmbL[OrigTrf, trf]
Action Multiplies an original transformation OrigTrf by another transformation trf from left.
Return The value of  OrigTrf,  which references the transformation multiplication result.
Vars OrigTrf: an integer number referencing the original transformation.

trf: an integer number referencing the other transformation (left-multiplier).
Notes The function arguments are not commutative.
radTrfCmbR[OrigTrf, trf]
Action Multiplies an original transformation OrigTrf by another transformation trf from right.
Return The value of OrigTrf,  which references the transformation multiplication result.
Vars OrigTrf: an integer number referencing the original transformation.

trf: an integer number referencing the other transformation (right-multiplier).
Notes The function arguments are not commutative.
radTrfOrnt[obj, trf]
Action Orients the object referenced by obj,  by applying the transformation trf to it once.
Return Value of obj.
Vars obj: an integer number referencing the object.

trf: an integer number referencing the transformation to be applied.
Notes As a result of this function, the object obj obtains different orientation as compared to the initial one described with the   Orientation note for the function which created the object.

The radTrfOrnt  function can be applied to the same object any number of times, with the same or different transformations.
radTrfMlt[obj, trf, mlt]
Action Creates mlt-1  objects with the first one being derived from the  obj  and each subsequent derived from the previous one, by applying the transformation trf. Following this, the object obj becomes equivalent to mlt different objects.
Return Value of obj.
Vars obj: an integer number referencing the object.

trf: an integer number referencing the transformation to be applied.

mlt: an integer number specifying multiplicity of the transformation.
Notes Allthough after execution of this function the object obj is treated as mlt different objects at field computation, the new objects can not be considered (accessed) separately from the object obj.

If  mlt=1,  the actions of  radTrfMlt[obj, trf, mlt] and radTrfOrnt[obj, trf] are equivalent. However, for mlt>1 the action of radTrfMlt[obj, trf, mlt] is not equivalent to any number of successive executions of radTrfOrnt[obj, trf].

Treatment of symmetries: the symmetries created by the function  radTrfMlt[obj, trf, mlt]  with mlt>1,  should be considered as symmetries or boundary conditions  with respect to the magnetic field induction.  Following this, for example, if obj is a current-carrying object, trf is a plane symmetry and mlt=2,  then the resulting field induction distribution corresponds to the symmetry trf,  however, current density vectors in obj and its mirror object are not, generally, related by the same symmetry.

In the case of plane (mirror) symmetry, we recommend using more convenient Secondary functions RadTrfZerPara and   RadTrfZerPerp ("zero parallel" and "zero perpendicular" field induction components with respect to the symmetry plane).


6. Field computation

radRlxPre , radRlxMan , radRlxAuto , radFldCmpPrc , radFldCmpCrt , radFldLenTol , radFld , radFldLst , radFldInt , radFldPtcTrj ,
radFldEnr , radFldEnrFrc , radFldEnrTrq , radFldFrc , radFldFrcShpRtg , radFldFocPot , radFldUnits
 

Open reference guide contents in new window

radRlxPre[obj, srcobj :0]
Action Builds an interaction matrix for the object referenced by obj,  treating the object srcobj as an additional external field source.
Return An integer number referencing the interaction matrix constructed.
Vars obj: an integer number referencing the object for which the interaction matrix should be constructed.

srcobj: an integer number referencing the object to be treated as additional external field source at construction of the interaction matrix for the object obj.
Notes The obj variable can reference a single object with magnetic material applied, or a container having at least one object with magnetic material applied.

Normally, obj should reference a container including both passive objects as blocks with iron material applied and active field sources as current-carrying objects or blocks with magnetic material having non-zero remanent magnetization (the latter being relaxable objects and active field sources at the same time).

The function can be used  with or without the srcobj variable. The srcobj can contain any kind of object producing magnetic field; all of these objects will be treated as external field sources and will not change their parameters during the relaxation. This is done in order to provide the possibility of solving a complicated problem iteratively by parts, thus requiring less memory for the interaction matrices to be constructed.

Use of field symmetries: In most cases, if the problem has any intrinsic symmetries with respect to the general field distribution, it can be described both by creating and applying necessary symmetries to some initial objects, or by creating all the objects as independent ones, without any symmetries. We recommend using the former, since it enables saving memory and, in some cases, CPU-time of the solution. However, it is easy to obtain an incorrect solution by applying a field symmetry which does not take place in reality. The safe way to use the symmetries is to apply them at the upper level, i.e., to the container obj for which the interaction matrix is constructed. If an additional external field source srcobj is used, it should have the same field symmetry properties as obj.
radRlxMan[intrc, meth, iternum, rlxpar]
Action Implements a manual relaxation procedure.
Return A list of three real numbers specifying (1) overage absolute change in   magnetization after previous iteration over all the objects participating in the relaxation, (2) maximum absolute value of magnetization over all the objects participating in the relaxation, (3) maximum absolute value of magnetic field strength over the central points of all the objects participating in the relaxation. All three values are given for the last iteration.
Vars intrc: an integer number referencing the interaction matrix.

meth: an integer number specifying relaxation method; can be 0, 1, 2, 3 or 4.

iternum: an integer number specifying number of iterations to do.

rlxpar: a real number specifying a relaxation parameter (not used in relaxation methods 3 and 4).
Notes After executing the relaxation procedure, each of the relaxable objects participating in the container for which the interaction matrix was built, receives a magnetization value corresponding to the general minimum of the interaction energy.

Relaxation method meth=0 simply resets magnetization in all relaxable objects to zero; meth=1 and meth=2 are methods using a relaxation parameter, 0<rlxpar<1; meth=3 and meth=4 do not use any relaxation parameter (their action does not depend on the value of rlxpar).

In most cases, the relaxation method meth=3 appears more suitable in comparison to other methods.
radRlxAuto[intrc, prec, maxiter, meth :3]
Action Executes an automatic relaxation procedure.
Return A list of four numbers specifying (1) average absolute change in magnetization after previous iteration over all the objects participating in the relaxation, (2) maximum absolute value of magnetization over all the objects participating in the relaxation, (3) maximum absolute value of magnetic field strength over central points of all the objects participating in the relaxation, and (4) actual number of iterations done. The values (1)-(3) given, are those of last iteration.
Vars intrc: an integer number referencing the interaction matrix.

prec: a real number specifying an absolute precision value for magnetization (by default in Tesla), to be reached by the end of the relaxation.

maxiter: maximum number of iterations permitted to reach the specified precision.

meth: an integer number specifying relaxation method; the automatic relaxation is only available with meth=3 and meth=4.
Notes The automatic relaxations stops whenever the change in magnetization (averaged over all the objects participating in the relaxation) between two successive iterations is smaller than prec, or the number of iterations is larger than maxiter.

The signs of successful relaxation are: (1) average absolute change in magnetization between the last two iterations over all the objects participating in the relaxation (the first number in the function return list) is smaller then the value of the prec variable; (2) actual number of iterations done (the last number in the function return list) is smaller than the value of the maxiter variable.

This function can be used without the last variable, as radRlxAuto[intrc, prec, maxiter]. In this case the meth=3 is used by default.

The relaxation methods meth=3 and meth=4 treat subdivided blocks (i.e. blocks to which radObjDivMag[obj, {kx,ky,kz}] function was applied) differently during the relaxation. The method meth=4 looks more stable, however, in the case of strong subdivision (kx>3, ky>3, kz>3) it may work more slowly than meth=3.
radFldCmpPrc[PrcB->prb, PrcA->pra, PrcBInt->prbint, PrcForce->prfrc, PrcTorque->prtrq, PrcEnergy->pre, PrcCoord->prcrd, PrcAngle->prang]
Action Sets absolute accuracy levels for computation of field induction (strength), vector potential, induction integrals along straight lines, force,  torque, energy, relativistic particle trajectory coordinates and angles.
Return 1
Vars prb: a real number specifying an absolute precision value for magnetic field induction and strength (by default in Tesla).

pra: a real number specifying an absolute precision value for magnetic field vector potential (by default in Tesla*mm).

prbint: a real number specifying an absolute precision value for magnetic field induction integral along a straight line (by default in Tesla*mm).

prfrc: a real number specifying an absolute precision value for force computation (by default in Newton).

prtrq: a real number specifying an absolute precision value for torque computation (by default in Newton*mm).

pre: a real number specifying an absolute precision value for energy computation (by default in Joule).

prcrd: a real number specifying an absolute precision value for computation of relativistic particle trajectory coordinates (by default in mm).

prang: a real number specifying an absolute precision value for computation of relativistic particle trajectory angles (by default in radian).
Notes The function works in line with Mathematica mechanism of options, with PrcB->, PrcA->, PrcBInt->, PrcForce->, PrcTorque->, PrcEnergy->, PrcCoord->, PrcAngle-> being predefined words (option names). The function can be called with any number of parameters placed in arbitrary order, for example: radFldCmpPrc[PrcBInt->0.001] for setting-in absolute accuracy level for field integral to 0.001 Tesla*mm; radFldCmpPrc[PrcEnergy->0.1, PrcForce->5.] for setting-in absolute accuracy level for energy to 0.1 Joule and absolute accuracy level for force to 5. Newton.

This function only concerns direct field computation methods and has no effect on the accuracy of relaxation procedure. The latter is specified in the relaxation functions.

The method for computation  of a relativistic particle trajectory  is switched from manual to automatic mode by setting-in any positive value for the corresponding absolute precision level.

In all cases for setting-in absolute accuracy levels for particular physical values we recommend to use the function radFldCmpPrc[...] rather than radFldCmpCrt[...] (the latter being obsolete).
radFldCmpCrt[prcB, prcA, prcBint, prcFrc, prcTrjCrd, prcTrjAng]
Action Sets absolute accuracy levels for computation of field induction (strength), vector potential, induction integrals along straight line, force, relativistic particle trajectory coordinates and angles.
Return 1
Vars prcB: a real number specifying an absolute precision value for magnetic field induction and strength (by default in Tesla).

prcA: a real number specifying an absolute precision value for magnetic field vector potential (by default in Tesla*mm).

prcBint: a real number specifying an absolute precision value for magnetic field induction integral along a straight line (by default in Tesla*mm).

prcFrc: a real number specifying an absolute precision value for force computation (by default in Newton).

prcTrjCrd: a real number specifying an absolute precision value for computation of relativistic particle trajectory coordinates (by default in mm).

prcTrjAng: a real number specifying an absolute precision value for computation of relativistic particle trajectory angles (by default in radian).
Notes This function is obsolete. Instead of it, we recommend to use the function radFldCmpPrc[...].

This function only concerns direct field computation methods and has no effect on the accuracy of relaxation procedure. The latter is specified in the relaxation functions.

The method for computation  of a relativistic particle trajectory  is switched from manual to automatic mode by setting-in any positive value for the corresponding absolute precision level.
radFldLenTol[abs, rel, zero :0]
Action Sets absolute and relative randomization magnitudes for all the length values, including coordinates and dimensions of the objects producing magnetic field, and coordinates of points where the field is computed.
Return 1
Vars abs: a real number specifying an absolute randomization magnitude for all the length values (by default in mm).

rel: a real number specifying a relative randomization magnitude for all the length values.

zero: a real number specifying zero tolerance for all the length values (by default in mm).
Notes The randomization of any length value x is done according to the formula (in C language notation):

x' = (x + abs*g1)*(1 + rel*g2) + ((x + abs*g1 == 0)? zero*g3 : 0);

where g1, g2 and g3 are real random numbers evenly distributed within the interval [-0.5, 0.5].

Optimal values of the variables can be: rel=10^(-10), abs=L*rel, zero=abs,  where L is the distance scale value (in mm) for the problem to be solved. Randomization magnitudes which are too small can result in run-time code errors; if they are too large, this can influence accuracy of the field computation.
radFld[obj, fid, {x,y,z}]
Action Computes magnetic field created by the object referenced by obj in the point with Cartesian coordinates {x,y,z}.
Return A list of real numbers or single real number representing the magnetic field component(s), according to the value of variable fid.
Vars obj: an integer number referencing the object producing the field to be computed.

fid: output field component identification string. The following values of fid are allowed:

  • "bx" or "by" or "bz" or "b" for horizontal or longitudinal or vertical component or the total vector of field induction (to be computed by default in Tesla),
  • "hx" or "hy" or "hz" or "h" for horizontal or longitudinal or vertical component or the total vector of field strength (to be computed by default in Tesla),
  • "ax" or "ay" or "az" or "a" for horizontal or longitudinal or vertical component or the total vector of the field vector-potential (to be computed by default in Tesla*mm),
  • "mx" or "my" or "mz" or "m" for horizontal or longitudinal or vertical component or the total vector of magnetization (to be computed by default in Tesla),
  • "" for the field induction, field strength, vector-potential and magnetization.

{x,y,z}: list of three real numbers specifying Cartesian coordinates of the point where the field should be computed (by default in mm).
Notes The output field component identification string  fid can be "bxby" or "bxbyhxhy", etc. In such cases the function returns a list of the field components in the order specified by the fid string. The fid="" gives vectors of the field induction, strength, vector potential and magnetization in the form  {{bx,by,bz}, {hx,hy,hz}, {ax,ay,az}, {mx,my,mz}}.
radFldLst[obj, fid, {x1,y1,z1}, {x2,y2,z2}, np, "arg|noarg", strt]
Action Computes magnetic field created by the object referenced by obj in np points evenly positioned along a straight line segment with edge points having Cartesian coordinates {x1,y1,z1} and {x2,y2,z2}.
Return np-element list of real numbers representing the magnetic field component(s), according to the value of variable fid.
Vars obj: an integer number referencing the object producing the field to be computed.

fid: output field characteristics identification string. The following values of  fid are allowed:

  • "bx" or "by" or "bz" or "b" for horizontal or longitudinal or vertical component or the total vector of field induction (to be computed by default in Tesla),
  • "hx" or "hy" or "hz" or "h" for horizontal or longitudinal or vertical component or the total vector of field strength (to be computed by default in Tesla),
  • "ax" or "ay" or "az" or "a" for horizontal or longitudinal or vertical component or the total vector of the field vector-potential (to be computed by default in Tesla*mm),
  • "mx" or "my" or "mz" or "m" for horizontal or longitudinal or vertical component or the total vector of magnetization (to be computed by default in Tesla),
  • "" for the field induction, field strength, vector-potential and magnetization.

{x1,y1,z1}: list of three real numbers specifying Cartesian coordinates of the first edge point of the line segment along which the field should be computed (by default in mm).

{x2,y2,z2}: list of three real numbers specifying Cartesian coordinates of the second edge point of the line segment along which the field should be computed (by default in mm).

np: an integer number specifying amount of points where the field component(s) should be computed.

"arg|noarg": a string switch for setting the output format with or without the  argument ("arg" or "noarg"), which is an offset of a point from {x1,y1,z1}, added to the value of the variable strt.

strt: a real number specifying a start-value for the output argument.
Notes The output field component identification string  fid can be "bxby" or "bxbyhxhy", etc.

If "arg|noarg" switch is set to "arg", the output is a list of np two-element lists with the first element being the argument (the offset of a point from {x1,y1,z1}, added to the value of the variable strt) and the second one being a list or a single real number giving the field component(s) according to the value of the variable fid.  If "arg|noarg" switch is set to "noarg", the output is a list of np lists or real numbers giving the field component(s) according to the value of the variable fid.

We suggest using this function in cases when the field should be computed at a large number of points (for example for 2D or 3D field plots): in such cases the radFldLst[...] may work much faster then the radFld[...] (being called many times).
radFldInt[obj, "inf|fin", fid, {x1,y1,z1}, {x2,y2,z2}]
Action Computes magnetic field induction integral along a straight line specified by two points with Cartesian coordinates {x1,y1,z1} and {x2,y2,z2}.
Return The magnetic field induction integral vector or one of its components (computed by default in Tesla*mm), according to the value of variable fid.
Vars obj: an integer number referencing the object producing the field to be integrated.

"inf|fin": a string switch for setting the type of field induction integral: "inf" means integral along the straight line from minus to plus infinity, "fin" means integral along the straight line from the point {x1,y1,z1} to the point {x2,y2,z2}.

fid: output field integral component identification string. The following values of fid are allowed: "ibx" or "iby" or "ibz", or "" for horizontal or longitudinal or vertical field induction integral, or all of the three components.

{x1,y1,z1}: list of three real numbers specifying Cartesian coordinates of one point on the line along which the field integral should be computed (by default in mm).

{x2,y2,z2}: list of three real numbers specifying Cartesian coordinates of the other point on the line along which the field integral should be computed (by default in mm).
Notes If the field integral component identification string fid is "ibxiby" or "bxby" or "xy" or "mzmx", etc., the function returns a list of two real numbers - components of the field integral vector (in the order corresponding to the fid string); "ibxibyibz" and "bxbybz" and "xyz"is equivalent to "".

The finite field integral from the point {x1,y1,z1} to the point {x2,y2,z2} ("fin") is computed numerically, whereas the infinite one ("inf") analytically (much faster in most cases).

The absolute precision level for the numerical computation of the finite integral can be set by the function radFldCmpCrt[...]. The default precision is 0.001 Tesla*mm.
radFldPtcTrj[obj, E, {x0,dxdy0,z0,dzdy0}, {y0,y1}, np]
Action Computes trajectory of a relativistic charged particle in the magnetic field created by the object referenced by obj.
Return np-element list of lists of four real numbers giving horizontal coordinate, horizontal angle, vertical coordinate and vertical angle of the particle trajectory at np points with longitudinal coordinates distributed from y0 to y1 with a constant step (the default units are mm for the coordinates and radians for the angles).
Vars obj: an integer number referencing the object producing the field.

E: a real number specifying the particle energy (by default in GeV).

{x0,dxdy0,z0,dzdy0}: list of four real numbers specifying the initial transverse coordinates (by default in mm) and angles (by default in radian).

{y0,y1}: list of two real numbers specifying the initial and final longitudinal coordinate values.

np: an integer number specifying amount of points where the particle trajectory characteristics should be computed,  np >= 2.
Notes The particle is assumed to have a charge equal to the charge of electron by absolute value.

If an absolute precision is specified for the trajectory coordinate or/and angle (with the function  radFldCmpCrt[...]),  then the trajectory is computed with this precision in each of the np points.
radFldEnr[objdst, objsrc] or radFldEnr[objdst, objsrc, {kx,ky,kz}]
Action Computes potential energy of the object objdst in magnetic field produced by the object objsrc.
Return The energy value (by default in Joule).
Vars objdst: an integer number referencing the object which potential energy should be computed.

objsrc: an integer number referencing the object producing magnetic field in which the potential energy of the object objdst should be computed.

{kx,ky,kz}: list of three integer numbers specifying subdivision of the destination object objdst at the energy computation.
Notes The function can be called with or without the destination subdivision list {kx,ky,kz}. If called with the destination  object subdivision list, the function performs the energy computation based on subdivision of the object objdst according to {kx,ky,kz}. If called without the destination subdivision list, the function performs the energy computation in automatic mode, based on absolute accuracy level for the energy, with automatic subdivision of the destination object objdst.

The absolute accuracy level for the energy computation in automatic mode can be set by the function radFldCmpPrc[...]. The default accuracy is 10 Joule.
radFldEnrFrc[objdst, objsrc, fid] or radFldEnrFrc[objdst, objsrc, fid, {kx,ky,kz}]
Action Computes force acting on the object objdst in magnetic field produced by the object objsrc.
Return The force vector or one of its components (computed by default in Newton), according to the value of variable fid.
Vars objdst: an integer number referencing the object on which the force (to be computed) is acting.

objsrc: an integer number referencing the object producing the magnetic field.

fid: output force component identification string. The following values of fid are allowed: "fx" or "fy" or "fz", or "" for particular component or all of the three components of the force vector.

{kx,ky,kz}: list of three integer numbers specifying subdivision of the destination object objdst at the force computation.
Notes The function can be called with or without the destination subdivision list {kx,ky,kz}. If called with the destination  object subdivision list, the function performs the force computation based on subdivision of the object objdst according to {kx,ky,kz}. If called without the destination subdivision list, the function performs the force computation in automatic mode, based on absolute accuracy level for the force, with automatic subdivision of the destination object objdst.

The absolute accuracy level for the force computation in automatic mode can be set by the function radFldCmpPrc[...]. The default accuracy is 10 Newton.

The function computes a force acting on a magnetized or current-carrying object, as a gradient of potential energy the object possesses in an external magnetic field. In many cases this method for the force computation appears advantageous as compared to the one based on the Maxwell stress tensor implemented in the function radFldFrc[...].
radFldEnrTrq[objdst, objsrc, tid, {x,y,z}] or radFldEnrTrq[objdst, objsrc, tid, {x,y,z}, {kx,ky,kz}]
Action Computes torque acting on the object objdst with respect to point {x,y,z} in magnetic field produced by the object objsrc.
Return The torque vector or one of its components (computed by default in Newton*mm), according to the value of variable tid.
Vars objdst: an integer number referencing the object on which the torque (to be computed) is acting.

objsrc: an integer number referencing the object producing the magnetic field.

tid: output force component identification string. The following values of tid are allowed: "tx" or "ty" or "tz", or "" for particular component or all of the three components of the torque vector.

{x,y,z}: list of three real numbers specifying Cartesian coordinates (by default in mm) of a point with respect to which the torque is computed.

{kx,ky,kz}: list of three integer numbers specifying subdivision of the destination object objdst at the torque computation.
Notes The function can be called with or without the destination subdivision list {kx,ky,kz}. If called with the destination object subdivision list, the function performs the torque computation based on subdivision of the object objdst according to {kx,ky,kz}. If called without the destination subdivision list, the function performs the torque computation in automatic mode, based on absolute accuracy level for the torque, with automatic subdivision of the destination object objdst.

The absolute accuracy level for the torque computation in automatic mode can be set by the function radFldCmpPrc[...]. The default accuracy is 10 Newton*mm.

The function computes a torque acting on a magnetized or current-carrying object in an external magnetic field through potential energy of the object in this field.
radFldFrc[obj, shape]
Action Computes force of the field produced by the object obj into the objects located within the space region defined by the object shape.
Return The force vector (computed by default in Newton).
Vars obj: an integer number referencing the object creating the magnetic field.

shape: an integer number referencing the object defining the space region where the object(s) on which the force is acting, are located.
Notes The shape can be the result of radObjRecMag[...] (parallelepiped) or radFldFrcShpRtg[...] (rectangular surface).

The absolute precision level for the force computation can be set by the function radFldCmpCrt[...]. The default precision is 1 Newton.

If no objects with magnetization or magnetic material applied, or current-carrying objects are geometrically located within the shape, the force should be zero (with the absolute precision specified for the force computation).

The function uses the force computation method based on the Maxwell stress tensor. Another Radia function  radFldEnrFrc[...] computes forces through potential energy of the object in external magnetic field. The later method may work faster in some cases.
radFldFrcShpRtg[{x,y,z}, {wx,wy}]
Action Creates a rectangle to be used for field force computation.
Return An integer number referencing the object.
Vars {x,y,z}: list of three real numbers specifying Cartesian coordinates of the rectangle's center (by default in mm).

{wx,wy}: list of two real numbers specifying the rectangle's dimensions.
Notes The objects created by this function are only used at force computation.
radFldFocPot[obj, {x1,y1,z1}, {x2,y2,z2}, np]
Action Computes the potential for the trajectory of relativistic charged particle in magnetic field produced by the object obj. The integration is made from {x1,y1,z1} to {x2,y2,z2} with np equidistant points.
Return A real number representing the value of the potential (by default in Tesla^2*mm^3).
Vars obj: an integer number referencing the object producing the magnetic field.

{x1,y1,z1}: list of three real numbers specifying Cartesian coordinates of the integration start point.

{x2,y2,z2}: list of three real numbers specifying Cartesian coordinates of the integration end point.

np: number of points to be used at the potential computation.
Notes The potential is used to describe electron dynamics in the field of an Insertion Device. Exact definition and the theory of the potential can be found in the paper:

P. Elleaume, "A New Approach to the Electron Beam Dynamics in Undulators and Wigglers", Proc. of the EPAC92, Berlin, March 22-28, 1992.
radFldUnits[]
Action Shows the physical units currently in use.
Return A string of information on physical units currently used by Radia.
Notes In the current version of Radia, this function can not modify the physical units; it only shows the default Radia units for the main physical quantities under operation.


7. Utilities

radUtiDel , radUtiDelAll , radUtiDmp , radUtiVer

Open reference guide contents in new window

radUtiDel[elem]
Action Deletes the element referenced by elem.
Return 0
Vars elem: an integer number referencing the element to be deleted.
Notes The elem can be any element previously created, including objects producing magnetic field, magnetic materials, transformations and interaction matrices.
radUtiDelAll[]
Action Deletes all the previously created elements.
Return 0
Notes This function actually deletes all the previously created elements, including objects producing magnetic field, magnetic materials, transformations and interaction matrices.
radUtiDmp[elem]
Action Gives information on the element referenced by elem.
Return A string of information on element elem.
Vars elem: an integer number referencing the element.
radUtiVer[]
Action Gives the identification number of the Radia version in use.
Return A real number specifying the Radia version.