Skip to content

Commit 3314deb

Browse files
biergaizithliebig
biergaizi
authored and
thliebig
committed
matlab: reformat all docstrings as legal Markdown.
This commit reformats all docstrings in the Matlab/Octave code as legal Markdown text, which can be used for automatic generation of online documentation, while still being human-readable as plaintext. Signed-off-by: Yifeng Li <tomli@tomli.me>
1 parent 038c99a commit 3314deb

50 files changed

Lines changed: 587 additions & 523 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎matlab/AddBox.m‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,24 @@
33
%
44
% Add a box to CSX and assign to a property with name <propName>.
55
%
6-
% start: box start coordinates
7-
% stop : box stop coordinates
8-
% prio : primitive priority
6+
% - start: box start coordinates
7+
% - stop : box stop coordinates
8+
% - prio : primitive priority
99
%
1010
% optional:
11-
% Transformation: perform a transformation on a primitive by adding
12-
% e.g.: 'Transform', {'Scale','1,1,2','Rotate_X',pi/4,'Translate','0,0,100'}
13-
% Note: This will only affect the 3D material/metal discretisation
11+
% - Transformation: perform a transformation on a primitive by adding
12+
% e.g.: 'Transform', {'Scale','1,1,2','Rotate_X',pi/4,'Translate','0,0,100'}
13+
% Note: This will only affect the 3D material/metal discretisation
1414
%
15-
% example:
16-
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
17-
% CSX = AddBox(CSX,'metal',10,[0 0 0],[100 100 200]); %assign box
15+
% example:
1816
%
19-
% with transformation:
20-
% CSX = AddBox(CSX,'metal',10,[0 0 0],[100 100 200], ...
21-
% 'Transform', {Rotate_Z, pi/4});
17+
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
18+
% CSX = AddBox(CSX,'metal',10,[0 0 0],[100 100 200]); %assign box
19+
%
20+
% with transformation:
21+
%
22+
% CSX = AddBox(CSX,'metal',10,[0 0 0],[100 100 200], ...
23+
% 'Transform', {Rotate_Z, pi/4});
2224
%
2325
% See also AddCylinder, AddCylindricalShell, AddSphere, AddSphericalShell,
2426
% AddCurve, AddWire, AddMetal
@@ -39,4 +41,4 @@
3941

4042
box = AddPrimitiveArgs(box,varargin{:});
4143

42-
CSX = Add2Property(CSX,propName, box, 'Box');
44+
CSX = Add2Property(CSX,propName, box, 'Box');

‎matlab/AddConductingSheet.m‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@
88
% Hint:
99
% Set the thickness to 0 to fall back to a perfect metal (AddMetal)
1010
%
11-
% example:
12-
% % create the conducting material peroperty, e.g. 40um thick copper
13-
% CSX = AddConductingSheet(CSX,'copper',56e6,40e-6);
14-
% % assign box the 2D box --> 40um thick sheet
15-
% CSX = AddBox(CSX,'copper',10,[0 -50 200],[1000 50 200]);
11+
% example:
12+
%
13+
% % create the conducting material peroperty, e.g. 40um thick copper
14+
% CSX = AddConductingSheet(CSX,'copper',56e6,40e-6);
15+
% % assign box the 2D box --> 40um thick sheet
16+
% CSX = AddBox(CSX,'copper',10,[0 -50 200],[1000 50 200]);
1617
%
1718
% See also AddMaterial, AddMetal, AddExcitation, AddBox
1819
%

‎matlab/AddCurve.m‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,23 @@
66
% Warning: This is a 1D object, not all properties may be compatible with a
77
% 1D object, e.g. a material property.
88
%
9-
% points: curve coordinates array
10-
% prio : primitive priority
9+
% - points: curve coordinates array
10+
% - prio : primitive priority
1111
%
12-
% example:
13-
% %first point
14-
% points(1,1) = 0;
15-
% points(2,1) = 5;
16-
% points(3,1) = 10;
17-
% %second point
18-
% points(1,2) = 0;
19-
% points(2,2) = 10;
20-
% points(3,2) = 10;
21-
% %third point ...
22-
% % create a thin metal wire...
23-
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
24-
% CSX = AddCurve(CSX,'metal',10, points);
12+
% example:
13+
%
14+
% %first point
15+
% points(1,1) = 0;
16+
% points(2,1) = 5;
17+
% points(3,1) = 10;
18+
% %second point
19+
% points(1,2) = 0;
20+
% points(2,2) = 10;
21+
% points(3,2) = 10;
22+
% %third point ...
23+
% % create a thin metal wire...
24+
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
25+
% CSX = AddCurve(CSX,'metal',10, points);
2526
%
2627
% See also AddBox, AddCylindricalShell, AddCylinder, AddSphere,
2728
% AddSphericalShell, AddWire, AddMetal
@@ -41,4 +42,4 @@
4142

4243
curve = AddPrimitiveArgs(curve,varargin{:});
4344

44-
CSX = Add2Property(CSX,propName, curve, 'Curve');
45+
CSX = Add2Property(CSX,propName, curve, 'Curve');

‎matlab/AddCylinder.m‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,15 @@
33
%
44
% Add a cylinder to CSX and assign to a property with name <propName>.
55
%
6-
% start: cylinder axis start coordinates
7-
% stop : cylinder axis box stop coordinates
8-
% rad : cylinder radius
9-
% prio : primitive priority
6+
% - start: cylinder axis start coordinates
7+
% - stop : cylinder axis box stop coordinates
8+
% - rad : cylinder radius
9+
% - prio : primitive priority
1010
%
11-
% example:
12-
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
13-
% CSX = AddCylinder(CSX,'metal',10,[0 0 0],[0 0 200],50);
11+
% example:
12+
%
13+
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
14+
% CSX = AddCylinder(CSX,'metal',10,[0 0 0],[0 0 200],50);
1415
%
1516
% See also AddBox, AddCylindricalShell, AddSphere, AddSphericalShell,
1617
% AddCurve, AddWire, AddMetal
@@ -32,4 +33,4 @@
3233

3334
cylinder = AddPrimitiveArgs(cylinder,varargin{:});
3435

35-
CSX = Add2Property(CSX,propName, cylinder, 'Cylinder');
36+
CSX = Add2Property(CSX,propName, cylinder, 'Cylinder');

‎matlab/AddCylindricalShell.m‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,20 @@
33
%
44
% Add a cylinder shell to CSX and assign to a property with name <propName>.
55
%
6-
% start: cylinder axis start coordinates
7-
% stop : cylinder axis box stop coordinates
8-
% rad : cylinder radius
9-
% shell_width: cylinder shell width
10-
% prio : primitive priority
6+
% - start: cylinder axis start coordinates
7+
% - stop : cylinder axis box stop coordinates
8+
% - rad : cylinder radius
9+
% - shell_width: cylinder shell width
10+
% - prio : primitive priority
1111
%
12-
% Note:
13-
% the inner radius of this shell is rad-shell_width/2
14-
% the outer radius of this shell is rad+shell_width/2
12+
% Note:
13+
% - the inner radius of this shell is rad-shell_width/2
14+
% - the outer radius of this shell is rad+shell_width/2
1515
%
16-
% example:
17-
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
18-
% CSX = AddCylindricalShell(CSX,'metal',10,[0 0 0],[0 0 200],50,10);
16+
% example:
17+
%
18+
% CSX = AddMetal(CSX,'metal'); %create PEC with propName 'metal'
19+
% CSX = AddCylindricalShell(CSX,'metal',10,[0 0 0],[0 0 200],50,10);
1920
%
2021
% See also AddBox, AddCylinder, AddSphere, AddSphericalShell,
2122
% AddCurve, AddWire, AddMetal

‎matlab/AddDebyeMaterial.m‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,19 @@
44
% Add a Debye type dispersive material model.
55
%
66
% The Debye type frequency dependent material:
7-
% eps_r(w) = eps_r + sum_p ( eps_r_delta,p / (1+jw*t_relex,p) ) - j*kappa/w
7+
%
8+
% eps_r(w) = eps_r + sum_p ( eps_r_delta,p / (1+jw*t_relex,p) ) - j*kappa/w
89
%
910
% with
10-
% eps_r_delta,p: the delta electric relative permitivity
11-
% t_relex,p: the electric relaxation time
11+
% - eps_r_delta,p: the delta electric relative permitivity
12+
% - t_relex,p: the electric relaxation time
1213
%
1314
% Use SetMaterialProperty to define the material constants:
14-
% 'EpsilonDelta_p': p-th eps_r_delta,p
15-
% 'EpsilonRelaxTime_p': p-th t_relex,p
15+
% - 'EpsilonDelta_p': p-th eps_r_delta,p
16+
% - 'EpsilonRelaxTime_p': p-th t_relex,p
1617
%
1718
% example:
19+
%
1820
% CSX = AddDebyeMaterial(CSX,'debye');
1921
% CSX = SetMaterialProperty(CSX,'debye','Epsilon',5,'EpsilonDelta_1',0.1,'EpsilonRelaxTime_1',1e-9);
2022
% [..]

‎matlab/AddDiscMaterial.m‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,22 @@
66
% Use Transform option to perfom some transformation actions.
77
%
88
% variable arguments (key/value)
9-
% 'File' (mandatory): define the filename of the discrete material
10-
% 'Scale': scale the discrete material
11-
% e.g. to your drawing units: 'Scale', 1/unit
12-
% 'Transform': Apply a transformation, see AddBox for more infos
13-
% 'UseDBBackground': set to 0, to use the properties background material
9+
% - 'File' (mandatory): define the filename of the discrete material
10+
% - 'Scale': scale the discrete material
11+
% e.g. to your drawing units: 'Scale', 1/unit
12+
% - 'Transform': Apply a transformation, see AddBox for more infos
13+
% - 'UseDBBackground': set to 0, to use the properties background material
1414
% instead of the database material with index 0 (default)
1515
%
1616
% examples:
17-
% %add human body model
18-
% CSX = AddDiscMaterial(CSX, 'Ella', 'Scale', 1/unit, ...
19-
% 'Transform', {'Rotate_Z',pi/2,'Translate','300,300,500'}, ...
20-
% 'File', 'model_file_name.h5' );
21-
% start = [mesh.x(1) mesh.y(1) mesh.z(1)];
22-
% stop = [mesh.x(end) mesh.y(end) mesh.z(end)];
23-
% CSX = AddBox(CSX,'Ella', 0 ,start,stop);
17+
%
18+
% %add human body model
19+
% CSX = AddDiscMaterial(CSX, 'Ella', 'Scale', 1/unit, ...
20+
% 'Transform', {'Rotate_Z',pi/2,'Translate','300,300,500'}, ...
21+
% 'File', 'model_file_name.h5' );
22+
% start = [mesh.x(1) mesh.y(1) mesh.z(1)];
23+
% stop = [mesh.x(end) mesh.y(end) mesh.z(end)];
24+
% CSX = AddBox(CSX,'Ella', 0 ,start,stop);
2425
%
2526
% See also AddBox, AddMetal, AddExcitation, AddProbe, AddDump
2627
%

‎matlab/AddDump.m‎

Lines changed: 56 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -4,69 +4,78 @@
44
% Add a dump property to CSX with the given name.
55
%
66
% possible arguments for useage with openEMS:
7-
% DumpType: 0 for E-field time-domain dump (default)
8-
% 1 for H-field time-domain dump
9-
% 2 for electric current time-domain dump
10-
% 3 for total current density (rot(H)) time-domain dump
11-
% 4 for D-field (electric flux density) time-domain dump
12-
% 5 for B-field (magnetic flux density) time-domain dump
7+
% - DumpType:
8+
% - 0 for E-field time-domain dump (default)
9+
% - 1 for H-field time-domain dump
10+
% - 2 for electric current time-domain dump
11+
% - 3 for total current density (rot(H)) time-domain dump
12+
% - 4 for D-field (electric flux density) time-domain dump
13+
% - 5 for B-field (magnetic flux density) time-domain dump
1314
%
14-
% 10 for E-field frequency-domain dump
15-
% 11 for H-field frequency-domain dump
16-
% 12 for electric current frequency-domain dump
17-
% 13 for total current density (rot(H)) frequency-domain dump
18-
% 14 for D-field (electric flux density) frequency-domain dump
19-
% 15 for B-field (magnetic flux density) frequency-domain dump
15+
% - 10 for E-field frequency-domain dump
16+
% - 11 for H-field frequency-domain dump
17+
% - 12 for electric current frequency-domain dump
18+
% - 13 for total current density (rot(H)) frequency-domain dump
19+
% - 14 for D-field (electric flux density) frequency-domain dump
20+
% - 15 for B-field (magnetic flux density) frequency-domain dump
2021
%
21-
% 20 local SAR frequency-domain dump
22-
% 21 1g averaging SAR frequency-domain dump
23-
% 22 10g averaging SAR frequency-domain dump
22+
% - 20 local SAR frequency-domain dump
23+
% - 21 1g averaging SAR frequency-domain dump
24+
% - 22 10g averaging SAR frequency-domain dump
2425
%
25-
% 29 raw data needed for SAR calculations (electric field FD,
26-
% cell volume, conductivity and density)
26+
% - 29 raw data needed for SAR calculations (electric field FD,
27+
% cell volume, conductivity and density)
2728
%
28-
% Frequency: specify a frequency vector (required for dump types >=10)
29+
% - Frequency: specify a frequency vector (required for dump types >=10)
2930
%
30-
% DumpMode: 0 no-interpolation
31-
% 1 node-interpolation (default, see warning below)
32-
% 2 cell-interpolation (see warning below)
31+
% - DumpMode:
32+
% - 0 no-interpolation
33+
% - 1 node-interpolation (default, see warning below)
34+
% - 2 cell-interpolation (see warning below)
3335
%
34-
% FileType: 0 vtk-file dump (default)
35-
% 1 hdf5-file dump
36+
% - FileType:
37+
% - 0 vtk-file dump (default)
38+
% - 1 hdf5-file dump
3639
%
37-
% SubSampling: field domain sub-sampling, e.g. '2,2,4'
38-
% OptResolution: field domain dump resolution, e.g. '10' or '10,20,5'
40+
% - SubSampling: field domain sub-sampling, e.g. '2,2,4'
41+
% - OptResolution: field domain dump resolution, e.g. '10' or '10,20,5'
3942
%
40-
% MultiGridLevel: Request to dump from a multigrid level (default is 0)
43+
% - MultiGridLevel: Request to dump from a multigrid level (default is 0)
4144
% Note: This only takes effect if the method supports and
4245
% uses multiple grids!
4346
%
44-
% StartTime/StopTime: Define a start and/or stop time (in seconds)
47+
% - StartTime/StopTime: Define a start and/or stop time (in seconds)
4548
% for this dump to be active.
4649
%
47-
% Warning:
48-
% FDTD Interpolation abnormalities:
49-
% - no-interpolation: fields are located in the mesh by the
50-
% Yee-scheme, the mesh only specifies E- or H-Yee-nodes
51-
% --> use node- or cell-interpolation or be aware of the offset
52-
% - E-field dump & node-interpolation: normal electric fields on
53-
% boundaries will have false amplitude due to forward/backward
54-
% interpolation in case of (strong) changes in material
55-
% permittivity or on metal surfaces
56-
% --> use no- or cell-interpolation
57-
% - H-field dump & cell-interpolation: normal magnetic fields on
58-
% boundaries will have false amplitude due to forward/backward
59-
% interpolation in case of (strong) changes in material permeability
60-
% --> use no- or node-interpolation
50+
% - Warning:
51+
% - FDTD Interpolation abnormalities
52+
% - no-interpolation: fields are located in the mesh by the
53+
% Yee-scheme, the mesh only specifies E- or H-Yee-nodes
54+
% --> use node- or cell-interpolation or be aware of the offset
55+
% - E-field dump & node-interpolation: normal electric fields on
56+
% boundaries will have false amplitude due to forward/backward
57+
% interpolation in case of (strong) changes in material
58+
% permittivity or on metal surfaces
59+
% --> use no- or cell-interpolation
60+
% - H-field dump & cell-interpolation: normal magnetic fields on
61+
% boundaries will have false amplitude due to forward/backward
62+
% interpolation in case of (strong) changes in material permeability
63+
% --> use no- or node-interpolation
6164
%
62-
% e.g. AddDump(CSX,'Et');
63-
% CSX = AddBox(CSX,'Et',10,[0 0 0],[100 100 200]); %assign box
65+
% e.g.
66+
%
67+
% AddDump(CSX,'Et');
68+
% CSX = AddBox(CSX,'Et',10,[0 0 0],[100 100 200]); %assign box
6469
%
65-
% or AddDump(CSX,'Ef',DumpType, 10, 'Frequency',[1e9 2e9]);
66-
% CSX = AddBox(CSX,'Ef',10,[0 0 0],[100 100 200]); %assign box
70+
% or
71+
%
72+
% AddDump(CSX,'Ef',DumpType, 10, 'Frequency',[1e9 2e9]);
73+
% CSX = AddBox(CSX,'Ef',10,[0 0 0],[100 100 200]); %assign box
6774
%
68-
% or AddDump(CSX,'Ht','SubSampling','2,2,4','DumpType',1);
69-
% CSX = AddBox(CSX,'Ht',10,[0 0 0],[100 100 200]); %assign box
75+
% or
76+
%
77+
% AddDump(CSX,'Ht','SubSampling','2,2,4','DumpType',1);
78+
% CSX = AddBox(CSX,'Ht',10,[0 0 0],[100 100 200]); %assign box
7079
%
7180
% See also AddMaterial, AddExcitation, AddProbe, AddMetal, AddBox
7281
%

‎matlab/AddExcitation.m‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,23 +3,24 @@
33
%
44
% Creates an E-field or H-field excitation.
55
%
6-
% CSX: CSX-struct created by InitCSX
7-
% name: property name for the excitation
8-
% type: 0=E-field soft excitation 1=E-field hard excitation
9-
% 2=H-field soft excitation 3=H-field hard excitation
10-
% 10=plane wave excitation
6+
% - CSX: CSX-struct created by InitCSX
7+
% - name: property name for the excitation
8+
% - type: 0=E-field soft excitation 1=E-field hard excitation
9+
% 2=H-field soft excitation 3=H-field hard excitation
10+
% 10=plane wave excitation
1111
%
1212
% excite: e.g. [2 0 0] for excitation of 2 V/m in x-direction
1313
%
1414
% additional options for openEMS:
15-
% 'Delay' : setup an excitation time delay in seconds
16-
% 'PropDir': direction of plane wave propagation (plane wave excite only)
15+
% - 'Delay' : setup an excitation time delay in seconds
16+
% - 'PropDir': direction of plane wave propagation (plane wave excite only)
1717
%
1818
% example:
19-
% CSX = AddExcitation( CSX, 'infDipole', 1, [1 0 0] );
20-
% start = [-dipole_length/2, 0, 0];
21-
% stop = [+dipole_length/2, 0, 0];
22-
% CSX = AddBox( CSX, 'infDipole', 1, start, stop );
19+
%
20+
% CSX = AddExcitation( CSX, 'infDipole', 1, [1 0 0] );
21+
% start = [-dipole_length/2, 0, 0];
22+
% stop = [+dipole_length/2, 0, 0];
23+
% CSX = AddBox( CSX, 'infDipole', 1, start, stop );
2324
%
2425
%
2526
% CSXCAD matlab interface

0 commit comments

Comments
 (0)
⚡