5. The Raith_library class

Class overview: Raith_library

Properties (public)
Raith_library.name	Character array specifying name of GDSII library
Raith_library.structures	Array of Raith_structure objects in library

Properties (private set access)
Raith_library.structlist	Cell array of all structure names in library

Methods
Raith_library.append()	Append Raith_structure object(s) to library
Raith_library.writegds()	Output Raith GDSII hierarchy (.csf/.gds) file
Raith_library.plot()	Plot structure in library as filled polygons
Raith_library.plotedges()	Plot structure in library as unfilled polygons

Static Methods
Raith_library.trans()	Return augmented matrix for translation
Raith_library.rot()	Return augmented matrix for rotation
Raith_library.refl()	Return augmented matrix for reflection about u-axis
Raith_library.scale()	Return augmented matrix for uniform scaling
Raith_library.writerec()	Write GDSII record to file
Raith_library.writehead()	Write GDSII library header records
Raith_library.writebeginstruct()	Write GDSII records to begin a structure
Raith_library.writeelement()	Write GDSII element records
Raith_library.writeendstruct()	Write GDSII records to end a structure
Raith_library.writeendlib()	Write GDSII records to end a library

class Raith_library

Raith_library objects define GDSII hierarchies containing collections of structures (Raith_structure objects) which may be referred to in positionlist entries. By default, the Raith_library.writegds() method outputs a “Raith-dialect” GDSII (.csf) file which can be used by the Raith NanoSuite beamwriting software without any additional modification; a standard GDSII (.gds) file readable by non-Raith GDSII viewers/editors can be output instead if the 'plain' dialect option is selected. Additionally, if all referenced structures are contained in the library, the full hierarchy of structures containing 'sref' or 'aref' elements may be displayed using the Raith_library.plot() and Raith_library.plotedges() methods.

5.1. Properties

5.1.1. Public properties

Raith_library.name

Character array specifying name of GDSII library, not including .csf/.gds extension.

Raith_library.structures

Array of Raith_structure objects in library. Raith_structure objects may be added to structures either using standard MATLAB notation, or via the Raith_library.append() method.

5.1.2. Private set-access properties

Raith_library.structlist

Ordered cell array of all names of structures (character arrays) found in library. structlist is automatically updated whenever structures is amended.

5.2. Constructor

Constructor:

L=Raith_library(name,structures)

Arguments:

• name – Character array specifying name of GDSII library, not including .csf/.gds extension.

• structures – Array of Raith_structure objects in library. Raith_structure objects may be added to structures either using standard MATLAB notation, or via the Raith_library.append() method.

Note

By default, all properties are checked for correctness (typing, allowed values, size) before being assigned, whether the Raith_library object is created with a constructor or its properties are amended individually.

Example

Given the Raith_structure object S defined in §4.2:

% Racetrack resonator defined in Raith_structure object S; here we are adding a text label
lbl=Raith_structure('radius_label',Raith_element('text',0,[0 0],2,0,[1 0],'3 µm',1.5));
L=Raith_library('resonators',[S lbl]);

5.3. Methods

Raith_library.append(S)

Append Raith_structure object(s) to library; structure names are checked for uniqueness.

Arguments:

S – Raith_structure object (or array thereof) to be appended to library

Returns:

None

Example

Given the Raith_structure objects S and lbl, defined in §4.2 and the above Constructor section, respectively, the three following commands all yield the same library L:

% Using Raith_library.append
L=Raith_library('resonators',S);
L.append(lbl);

% Using horizontal concatenation
L=Raith_library('resonators',[S lbl]);

% Using array indexing
L=Raith_library('resonators',S);
L.structures(end+1)=lbl;

Raith_library.writegds([outdir[, dialect]])

Write Raith GDSII hierarchy of all structures to file name.csf ('Raith' dialect) or name.gds ('plain' dialect).

Arguments:

• outdir – Character array specifying directory in which to write .csf/.gds file [optional]; if called without arguments, file is written to working directory.

• dialect – Character array specifying dialect of GDSII to write [optional]; may be 'Raith' (default) or 'plain' (readable by non-Raith GDSII viewers/editors).

Returns:

None

Note

If 'plain' is specified for dialect, Raith curved and FBMS elements ('arc', 'circle', 'ellipse', 'fbmspath', 'fbmscircle') are converted to GDSII BOUNDARY (polygon) elements or PATH elements, as appropriate, matching their appearance when plotted. The exported file also has a .gds extension by default, and may be opened by non-Raith GDSII editors such as KLayout .

Example

Given the Raith_library object L in the above Constructor section:

>> L.writegds('/Users/Public/Documents');

Checking for missing structures...OK.
Writing /Users/Public/Documents/resonators.csf...
     Header information
     Structure 1/2:  racetrack
     Structure 2/2:  radius_label
GDSII library resonators.csf successfully written.

Raith_library.plot(structname[, M[, scDF]])

Plot structure in library with default Raith dose factor colouring. Elements are displayed as filled polygons, where applicable ('polygon'; 'path' with non-zero data.w; 'arc', 'circle', and 'ellipse' with empty data.w; 'text'). All elements in the structure are plotted, regardless of data.layer value. The full hierarchy of structures including 'sref' or 'aref' elements are displayed if all structures being referenced are present in the library.

Arguments:

• structname – Character array specifying name of structure to be plotted (must be in structlist)

• M – Augmented transformation matrix to be applied to element [optional]; see Raith_library.trans(), Raith_library.rot(), Raith_library.refl(), and Raith_library.scale().

• scDF – Overall multiplicative scaling factor applied to dose factors of all elements in structure [optional]

Returns:

None

Calling Raith_library.plot() does not change the current axis scaling; issue an axis equal command to ensure that the element is displayed in the figure correctly.

Note

Normally, Raith_library.plot() is called without arguments, to display the structure as it would appear in the Raith NanoSuite software. The optional arguments M and scDF are used internally, when Raith_library.plot() is called by Raith_positionlist.plot().

Example

Given the Raith_structure objects S and lbl, defined in §4.2 and §5.2 section, respectively:

% Racetrack resonator defined in Raith_structure object S
% Radius label defined in Raith_structure object lbl
E(1)=Raith_element('sref','racetrack',[0 0]);
E(2)=Raith_element('sref','radius_label',[0 -4]);
RR=Raith_structure('labelled_racetrack',E);

L=Raith_library('resonators',RR);
L.plot('labelled_racetrack');  % Figure 5.1

L.append(S);
clf;
L.plot('labelled_racetrack');  % Figure 5.2
axis equal;

L.append(lbl);
clf;
L.plot('labelled_racetrack');  % Figure 5.3
axis equal;

Fig. 5.1 Display resulting from Raith_library.plot() method when referenced structures are not in library

Fig. 5.2 Display resulting from Raith_library.plot() method when one referenced structure is not in library

Fig. 5.3 Display resulting from Raith_library.plot() method when all referenced structures are present in library

Raith_library.plotedges([M[, scDF]])

Plot outlines of structure in library with default Raith dose factor colouring. Elements are displayed as unfilled polygons, where applicable ('polygon'; 'path' with non-zero data.w; 'arc', 'circle', and 'ellipse' with empty data.w; 'text'). All elements in the structure are plotted, regardless of data.layer value. The full hierarchy of structures including 'sref' or 'aref' elements are displayed if all structures being referenced are present in the library.

Arguments:

• structname – Character array specifying name of structure to be plotted (must be in structlist)

• M – Augmented transformation matrix to be applied to element [optional]; see Raith_library.trans(), Raith_library.rot(), Raith_library.refl(), and Raith_library.scale().

• scDF – Overall multiplicative scaling factor applied to dose factors of all elements in structure [optional]

Returns:

None

Calling Raith_library.plotedges() does not change the current axis scaling; issue an axis equal command to ensure that the element is displayed in the figure correctly.

Note

Normally, Raith_library.plotedges() is called without arguments, to display the structure as it would appear in the Raith NanoSuite software. The optional arguments M and scDF are used internally, when Raith_library.plotedges() is called by Raith_positionlist.plotedges().

Example

Given the Raith_library object L defined at the end of the previous example:

L.plotedges('labelled_racetrack');
axis equal;

Fig. 5.4 Display resulting from Raith_library.plotedges() method when all structures are present in library

5.4. Static methods

The methods in this section do not require an instance of the Raith_library class to be called (static), and are generally used internally. Certain circumstances, however, may require the user to call them explicity (e.g., see §7.3).

static Raith_library.trans(p)

Return augmented matrix for translation.

Arguments:

p – Translation vector; 1 × 2 vector [p_u p_v] (µm)

Returns:

M – Augmented matrix for translation

Note

For translation by a vector \(\vec{p}\), the augmented matrix is

\[\begin{split}\left[ \begin{matrix} 1 & 0 & p_u\\ 0 & 1 & p_v\\ 0 & 0 & 1 \end{matrix}\right]\end{split}\]

Example

Raith_library.trans([10 20])

ans =

     1     0    10
     0     1    20
     0     0     1

static Raith_library.rot(theta)

Return augmented matrix for rotation.

Arguments:

theta – Rotation angle, counter-clockwise positive (degrees)

Returns:

M – Augmented matrix for rotation

Note

For counter-clockwise rotation through an angle θ, the augmented matrix is

\[\begin{split}\left[ \begin{matrix} \cos\theta & \sin\theta & 0 \\ \sin\theta & \cos\theta & 0 \\ 0 & 0 & 1 \end{matrix}\right]\end{split}\]

Example

Raith_library.rot(30)

ans =

    0.8660   -0.5000         0
    0.5000    0.8660         0
         0         0    1.0000

static Raith_library.refl(n)

Return augmented matrix for reflection about u-axis n times.

Arguments:

n – Number of times to reflect about u-axis

Returns:

M – Augmented matrix for reflection

Note

For reflection about u-axis n times, the augmented matrix is

\[\begin{split}\left[ \begin{matrix} 1 & 0 & 0\\ 0 & (-1)^n & 0\\ 0 & 0 & 1 \end{matrix}\right]\end{split}\]

Example

Raith_library.refl(1)

ans =

     1     0     0
     0    -1     0
     0     0     1

static Raith_library.scale(mag)

Return augmented matrix for uniform scaling.

Arguments:

mag – Uniform scaling factor

Returns:

M – Augmented matrix for uniform scaling

Note

For uniform scaling by a factor m, the augmented matrix is

\[\begin{split}\left[ \begin{matrix} m & 0 & 0\\ 0 & m & 0\\ 0 & 0 & 1 \end{matrix}\right]\end{split}\]

Example

Raith_library.scale(3)

ans =

     3     0     0
     0     3     0
     0     0     1

static Raith_library.writerec(FileID, rectype, datatype, parameters)

Write single GDSII record to file.

Arguments:

• FileID – Integer file identifier obtained from MATLAB’s fopen function

• rectype – GDSII record type, specified in decimal format; Table 5.1 lists the record types used in the Raith_GDSII toolbox.

• datatype – GDSII data type, specified in decimal format; Table 5.2 lists the data types for the GDSII specification.

• parameters – Record parameters, of type defined by datatype

Returns:

None

Table 5.1 GDSII record types, with values in hexadecimal and decimal format. The latter is passed to Raith_library.writerec() as the rectype argument.

Record type	Hex	Dec
HEADER	0x00	0
BGNLIB	0x01	1
LIBNAME	0x02	2
UNITS	0x03	3
ENDLIB	0x04	4
BGNSTR	0x05	5
STRNAME	0x06	6
ENDSTR	0x07	7
BOUNDARY	0x08	8
PATH	0x09	9
SREF	0x0A	10
AREF	0x0B	11
LAYER	0x0D	13
DATATYPE	0x0E	14
WIDTH	0x0F	15
XY	0x10	16
SNAME	0x12	18
COLROW	0x13	19
STRANS	0x1A	26
MAG	0x1B	27
ANGLE	0x1C	28
CURVED[1]	0x56	86
FBMS[2]	0x58	88

Table 5.2 GDSII data types, with values in hexadecimal and decimal format. The latter is passed to Raith_library.writerec() as the datatype argument.

Data type	Hex	Dec
No data present	0x00	0
Bit array (2 bytes)	0x01	1
2-byte signed integer	0x02	2
4-byte signed integer	0x03	3
4-byte float[3]	0x04	4
8-byte float	0x05	5
ASCII string	0x06	6

Example

% Open a file for writing
FileID=fopen('test.csf','w');
% Write a BOUNDARY record, which contains no data
Raith_library.writerec(8,0,[]);

static Raith_library.writehead(FileID, name)

Write GDSII library header records.

Arguments:

• FileID – Integer file identifier obtained from MATLAB’s fopen function

• name – GDSII library name, without .csf/.gds extension (character array)

Returns:

None

Note

This method writes the HEADER, BGNLIB, LIBNAME, and UNITS records. The current system time is used for the BGNLIB record. 1 μm and 1 nm are used for the user and database units, respectively, in the UNITS record.

Example

% Open a file for writing
FileID=fopen('test.csf','w');
% Write GDSII header information
Raith_library.writehead(FileID,'test');

static Raith_library.writebeginstruct(FileID, name)

Write GDSII records to begin a structure.

Arguments:

• FileID – Integer file identifier obtained from MATLAB’s fopen function

• name – Name of structure (character array)

Returns:

None

Note

This method writes the BGNSTR and STRNAME records. The current system time is used for BGNSTR.

Example

% Open a file for writing
FileID=fopen('test.csf','w');
Raith_library.writebeginstruct(FileID,'waveguide');

static Raith_library.writeelement(FileID, element)

Write GDSII element records.

Arguments:

• FileID – Integer file identifier obtained from MATLAB’s fopen function

• element – Raith_element object to be written

Returns:

None

Note

The GDSII record types written vary according to the type of element.

Example

% Open a file for writing
FileID=fopen('test.csf','w');
% Define an element
E=Raith_element('path',0,[0 1 1;0 0 1],0.2,1);
Raith_library.writeelement(FileID,E);

static Raith_library.writeendstruct(FileID)

Write GDSII record to end a structure.

Arguments:

FileID – Integer file identifier obtained from MATLAB’s fopen function

Returns:

None

Note

This method writes the ENDSTR record, which has no parameters.

Example

% Open a file for writing
FileID=fopen('test.csf','w');
Raith_library.writeendstruct(FileID);

static Raith_library.writeendlib(FileID)

Write GDSII record to end a library.

Arguments:

FileID – Integer file identifier obtained from MATLAB’s fopen function

Returns:

None

Note

This method writes the ENDLIB record, which has no parameters.

Example

% Open a file for writing
FileID=fopen('test.csf','w');
Raith_library.writeendlib(FileID);

[1]

The Raith CURVED element record type is not part of the GDSII specification. It is used by the Raith NanoSuite software to denote arc, ellipse, and circle elements.

[2]

The Raith FBMS element record type is also not part of standard GDSII. It is used by the Raith NanoSuite software to denote fixed beam moving stage exposure.

[3]

The 4-byte float data type is listed as unused in the GDSII Stream Format Manual v6.0.