Cell Hierarchy Digest

The Cell Hierarchy Digest (CHD) is a data structure for saving a description of a cell hierarchy in compact form. The CHD can be used to access data in the original file, without having to load the file, in an efficient manner. This capability is accessible from a set of script functions described below. This capability applies to physical data only.

(string) FileInfo(filename, handle_or_filename, flags)
This function provides information about the archive file given by the first argument. If the second argument is a string giving the name of a file, output will go to that file. If the second argument is a handle returned from the Open function or similar (opened for writing), output goes to the handle stream. In either case, the return value is a null string. If the second argument is a scalar 0, the output will be in the form of a string which is returned.

The third argument is an integer or string which determines the type of information to return. If an integer, the bits are flags that control the possible data fields and printing modes. The string form is a space or comma-separated list of text tokens or hex integers. The hex numbers or equivalent values for the text tokens are or'ed together to form the flags integer.

This is really just a convenience wrapper around the ChdInfo function. See the description of that function for a description of the flags. In this function, the following keyword flags will show as follows:

alias
No aliasing is applied.

flags
The flags will always be 0.

On error, a null string is returned, with an error message likely available from GetError.

(chd_name) OpenCellHierDigest(filename, info_saved)
This function returns an access name to a new Cell Hierarchy Digest (CHD), obtained from the archive file given as the argument. The new CHD will be listed in the Cell Hierarchy Digests panel, and the access name is used by other functions to access the CHD.

See the table in 14.1 for the features that apply during a call to this function. In particular, the names of cells saved in the CHD reflect any aliasing that was in force at the time the CHD was created.

The file is opened from the library search path, if a full path is not provided. The CHD is a data structure that provides information about the hierarchy in compact form, and does not use that main database. The second argument is an integer that determines the level of statistical information about the hierarchy saved. This info is available from the ChdInfo function and by other means. The values can be:

0	No information is saved.
1	Only total object counts are saved (default).
2	Object totals are saved per layer.
3	Object totals are saved per cell.
4	Objects counts are saved per cell and per layer.

The larger the value, the more memory is required, so it is best to only save information that will be used.

If the ChdEstFlatMemoryUse function will be called from the new CHD, the per-cell totals must be specified (value 3 or 4) or the estimate will be wildly inaccurate.

The CHD refers to physical information only. On error, a null string is returned, and an error message may be available with the GetError function.

(int) WriteCellHierDigest(chd_name, filename, incl_geom, no_compr)
This function will write a disk file representation of the Cell Hierarchy Digest (CHD) associated with the access name given as the first argument, into the file whose name is given as the second argument. Subsequently, the file can be read with ReadCellHierDigest to recreate the CHD. The file has no other use and the format is not documented.

The CHD (and thus the file) contains offsets onto the target archive, as well as the archive location. There is no checksum or other protection currently, so it is up to the user to make sure that the target archive is not moved or modified while the CHD is potentially or actually in use.

If the boolean argument incl_geom is true, and the CHD has a linked CGD (as from ChdLinkCgd), then geometry records will be written to the file as well. When the file is read, a new CGD will be created and linked to the new CHD. Presently, the linked CGD must have memory or file type, as described for OpenCellGeomDigest.

The boolean argument no_compr, if true, will skip use of compression of the CHD records. This is unnecessary and not recommended, unless compatibility with Xic releases earlier than 3.2.17, which did not support compression, is needed.

The function returns 1 if the file was written successfully, 0 otherwise, with an error message likely available from GetError.

(string) ReadCellHierDigest(filename, cgd_type)
This function returns an access name to a new cell Hierarchy Digest (CHD) created from the file whose name is passed as an argument. The file must have been created with WriteCellHierDigest, or with the Save button in the Cell Hierarchy Digests panel.

If the file was written with geometry records included, a new Cell Geometry Digest (CGD) may also be created (with an internally generated access name), and linked to the new CHD. If the integer argument cgd_type is 0, a ``memory'' CGD will be created, which has the compressed geometry data stored in memory. If cgd_type is 1, a ``file'' CGD will be created, which will use offsets to obtain geometry from the CHD file when needed. If cgd_type is any other value, or the file does not contain geometry records, no CGD will be produced.

On error, a null string is returned, with an error message probably available from GetError.

(stringlist_handle) ChdList()
This function returns a handle to a list of access strings to Cell Hierarchy Digests that are currently in memory. The function never fails, though the handle may reference an empty list.

(int) ChdChangeName(old_chd_name, new_chd_name)
This function allows the user to change the access name of an existing Cell Hierarchy Digest (CHD) to a user-supplied name. The new name must not already be in use by another CHD.

The first argument is the access name of an existing CHD, the second argument is the new access name, with which the CHD will subsequently be accessed. This name can be any text string, but can not be null.

The function returns 1 on success, 0 otherwise, with an error message likely available from GetError.

(int) ChdIdValid(chd_name)
This function returns one if the string argument is an access name of a Cell Hierarchy Digest currently in memory, zero otherwise.

(int) ChdDestroy(chd_name)
If the string argument is an access name of a Cell Hierarchy Digest (CHD) currently in memory, the CHD will be destroyed and its memory freed. One is returned on success, zero otherwise, with an error message likely available with GetError.

(string) ChdInfo(chd_name, handle_or_filename, flags)
This function provides information about the archive file represented by the Cell Hierarchy Digest (CHD) whose access name is given as the first argument. If the second argument is a string giving the name of a file, output will go to that file. If the second argument is a handle returned from the Open function or similar (opened for writing), output goes to the handle stream. In either case, the return value is a null string. If the second argument is a scalar 0, the output will be in the form of a string which is returned.

The third argument is an integer or string which determines the type of information to return. If an integer, the bits are flags that control the possible data fields and printing modes. The string form is a space or comma-separated list of text tokens (from the list below, case insensitive) or hex integers. The hex numbers or equivalent values for the text tokens are or'ed together to form the flags integer.

If this argument is 0, all flags except for allcells, instances, flags, instcnts, and instcntsp are implied. Thus, the sometimes very lengthly cells/instances listing is skipped by default. To obtain all available information, pass -1 or all as the flags value.

Keyword	Value	Description
filename	0x1	File name.
filetype	0x2	File type (``CIF'', ``CGX'', ``GDSII'', or ``OASIS'').
unit	0x4	File unit in meters (e.g., GDSII M-UNIT).
alias	0x8	Applied cell name aliasing modes.
reccounts	0x10	Table of record type counts (file format dependent).
objcounts	0x20	Table of object counts.
depthcnts	0x40	Tabulate the number of cell instances at each hierarchy level.
estsize	0x80	Print estimated memory needed to read file into Xic.
estchdsize	0x100	Print size of data structure used to provide info.
layers	0x200	List of layer names found, as for ChdLayers function.
unresolved	0x400	List any cells that are referenced but not defined in the file.
topcells	0x800	Top-level cells.
allcells	0x1000	All cells.
offsort	0x2000	Sort cells by offset in archive file.
offset	0x4000	Print offsets of cell definitions in archive file.
instances	0x8000	List instances with cells.
bbs	0x10000	List bounding boxes with cells, and attributes with instances.
flags	0x20000	Unused.
instcnts	0x40000	Count cell instances and report totals.
instcntsp	0x80000	Count cell instances and report totals per master.
all	-1	Set all flags.

The information provided by these flags is more fully described below.

filename
Print the name of the archive file for which the information applies.

filetype
Print a string giving the format of the archive file: one of ``CIF'', ``CGX'', ``GDSII'', or ``OASIS''.

unit
This is a file parameter giving the value of one unit in meters. In GDSII files, this is obtained from the M-UNIT record. The value is typically 1e-9, which means that a coordinate value of 1000 corresponds to one micron.

alias
Print a string giving the cell name aliasing modes that were in effect when the CHD was created.

reccounts
Print a table of the counts for record types found in the archive. This is format-dependent.

objcounts
Print a table of object counts found in the archive file. The table contains the following keywords, each followed by a number.

Keyword	Description
Records	Total record count
Cells	Number of cell definitions
Boxes	Number of rectangles
Polygons	Number of polygons
Wires	Number of wire paths
Avg Verts	Average vertex count per poly or wire
Labels	Number of (non-physical) labels
Srefs	Number of non-arrayed instances
Arefs	Number of arrayed instances

If the per-layer counts option was set when the CHD was created, additional lines will display the object counts as above, broken out per-layer.

depthcnts
A table of the number of cell instantiations at each hierarchy level is printed, for each top-level cell found in the file. The count for depth 0 is 1 (the top-level cell), the count at depth 1 is the number of subcells of the top-level cell, depth 2 is the number of subcells of these subcells, etc. Arrays are expanded, with each element counting as an instance placement. A total is printed, the same value that would be obtained from the instcnts flag.

estsize
This flag will enable printing of the estimated memory required to read the entire file into Xic. The system must be able to provide at least this much memory for a read to succeed.

estchdsize
Print an estimate of the memory required by the present CHD.

By default, a compression mechanism is used to reduce the data storage needed for instance lists. The NoCompressContext variable, if set, will turn off use of compression. If compression is used, the extcxsize field will include compression statistics. The ``ratio'' is the space actually used to the space used if not compressed.

layers
Print a list of the layer names encountered in the archive, as for the ChdLayers function.

unresolved
This will list cells that are referenced but not defined in the file. These will also be listed if allcells is given. A valid archive file will not contain unresolved references.

topcells
List the top-level cells, i.e., the cells in the file that are not used as a subcell by another cell in the file. If allcells is also given, only the names are listed, otherwise the cells are listed including the offset, instances, bbs, and flags fields if these flags are set. The list will be sorted as per offsort.

allcells
All cells found in the file are listed by name, including the offset, instances, bbs, and flags fields if these flags are also given. The list will be sorted as per offsort.

The following flags apply only if at least one of topcells or allcells is given.

offsort
If this flag is set, the cells will be listed in ascending order of the file offset, i.e., in the order in which the cell definitions appear in the archive file. If not set, cells are listed alphabetically.

offset
When set, the cell name is followed by the offset of the cell definition record in the archive file. This is given as a decimal number enclosed in square brackets.

instances
For each cell, the subcells used in the cell are listed. The subcell names are indented and listed below the cell name.

bbs
For each cell the bounding box is shown, in L,B R,T form. For subcells, the position, transformation, and array parameters are shown. Coordinates are given in microns. The subcell transformation and array parameters are represented by a concatenation of the following tokens, which follow the subcell reference position. These are similar to the transformation tokens found in CIF, and have the same meanings.

MY	Mirror about the x-axis.
Ri,j	Rotate by an angle given by the vector i,j.
Mmag	Magnify by mag.
Anx,ny,dx,dy	Specifies an array, nx x ny with spacings dx, dy.

Note: for technical reasons, the cell bounding boxes in CHDs do not include empty cells, unlike the bounding boxes computed in the main database, which will include the placement location points.

flags
This is currently unused and ignored.

instcnts
Print the total number of cell instantiations found in the hierarchy. Arrays are expanded, i.e., each element of an array counts as an instance placement.

instcntsp
Similar to instcnts, but print the total instantiations for each master cell.

all
This enables all flags.

On error, a null string is returned, with an error message likely available from GetError.

This function is similar to the !fileinfo command and to the FileInfo script function.

(string) ChdFileName(chd_name)
This function returns a string containing the full pathname of the file associated with the Cell Hierarchy Digest (CHD) whose access name was given in the argument. A null string is returned on error, with an error message likely available from GetError.

(string) ChdFileType(chd_name)
This function returns a string containing the file format of the archive file associated with the Cell Hierarchy Digest (CHD) whose access name was given in the argument. A null string is returned on error, with an error message likely available from GetError. Other possible returns are ``CIF'', ``GDSII'', ``CGX'', and ``OASIS''.

(stringlist_handle) ChdTopCells(chd_name)
This function returns a handle to a list of strings that contain the top-level cell names in the Cell Hierarchy Digest (CHD) whose access name was given in the argument (physical cells only). The top-level cells are those not used as a subcell by another cell in the CHD. A scalar zero is returned on error, with an error message likely available from GetError.

(stringlist_handle) ChdListCells(chd_name, cellname, mode, all)
This function returns a handle to a list of cellnames from among those found in the CHD, whose access name is given as the first argument. There are two basic modes, depending on whether the boolean argument all is true or not.

If all is true, the cellname argument is ignored, and the list will consist of all cells found in the CHD. If the integer mode argument is 0, all physical cell names are listed. If mode is 1, all electrical cell names will be returned. If any other value, the listing will contain all physical and electrical cell names, with no duplicates.

If all is false, the listing will contain the names of all cells under the hierarchy of the cell named in the cellname argument (including cellname). If cellname is 0, empty, or null, the default cell for the CHD is assumed, i.e., the cell which has been configured, or the first top-level cell found. The mode argument is 0 for physical cells, nonzero for electrical cells (there is no merging of lists in this case).

On error, a scalar 0 is returned, and a message may be available from GetError.

(stringlist_handle) ChdLayers(chd_name)
This function returns a handle to a list of strings that contain the names of layers used in the file represented by the Cell Hierarchy Digest whose access name is passed as the argument (physical cells only). For file formats that use a layer/datatype, the names are four-byte hex integers, where the left two bytes are the zero-padded hex value of the layer number, and the right two bytes are the zero-padded value of the datatype number. This applies for GDSII/OASIS files that follow the standard convention that layer and datatype numbers are 0-255. If either number is larger than 255, the layer ``name'' will consist of eight hex bytes, the left four for layer number, the right four for datatype.

The layers listing is available only if the CHD was created with info available, i.e., OpenCellHierDigest was called with the info_saved argument set to a value other than 0.

Each unique combination or layer name is listed. A scalar zero is returned on error, in which case an error message may be available from GetError.

(int) ChdInfoMode(chd_name)
This function returns the saved info mode of the Cell Hierarchy Digest whose access name is passed as the argument. This is the info_saved value passed to OpenCellHierDigest. The values are:

0	no information is saved.
1	only total object counts are saved.
2	object totals are saved per layer.
3	object totals are saved per cell.
4	objects counts are saved per cell and per layer.

If the CHD name is not resolved, the return value is -1, with an error message available from GetError.

(stringlist_handle) ChdInfoLayers(chd_name, cellname)
This is identical to the ChdLayers function when the cellname is 0, null, or empty. If the CHD was created with OpenCellHierDigest with the info_saved argument set to 4 (per-cell and per-layer info saved), then a cellname string can be passed. In this case, the return is a handle to a list of layers used in the named cell. A scalar 0 is returned on error, with an error message probably available from GetError.

(stringlist_handle) ChdInfoCells(chd_name)
If the CHD whose access name is given as the argument was created with OpenCellHierDigest with the info_saved argument set to 3 (per-cell data saved) or 4 (per-cell and per-layer data saved), then this function will return a handle to a list of cell names from the source file. On error, a scalar 0 is returned, with an error message probably available from GetError.

(int) ChdInfoCounts(chd_name, cellname, layername, array)
This function will return object count statistics in the array, which must have size 4 or larger. The counts are obtained when the CHD, whose access name is given as the first argument, was created. The types of counts available depend on the info_saved value passed to OpenCellHierDigest when the CHD was created.

The array is filled in as follows:

array[0]	Box count.
array[1]	Polygon count.
array[2]	Wire count.
array[3]	Vertex count (polygons plus wires).

The following counts are available for the various info_saved modes.

info_saved = 0
No information is available.

info_saved = 1
Both cellname and layername arguments are ignored, the return provides file totals.

info_saved = 2
The cellname argument is ignored. If layername is 0, null, or empty, the return provides file totals. Otherwise, the return provides totals for layername, if found.

info_saved = 3
The layername argument is ignored. If cellname is 0, null, or empty, the return represents file totals. Otherwise, the return provides totals for cellname, if found.

info_saved = 4
If both arguments are 0, null, or empty, the return represents file totals. If cellname is 0, null, or empty, the return represents totals for the layer given. If layername is 0, null, or empty, the return provides totals for the cell name given. If both names are given, the return provides totals for the given layer in the given cell.

If a cell or layer is not found, or data are not available for some reason, or an error occurs, the return value is 0, and an error message may be available from GetError. Otherwise, the return value is 1, and the array is filled in.

(int) ChdCellBB(chd_name, cellname, array)
This returns the bounding box of the named cell. The cellname is a string giving the name of a physical cell found in the Cell Hierarchy Digest (CHD) whose access name is given in the first argument.

The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

The values are returned in the array, which must have size 4 or larger. the order is l,b,r,t. One is returned on success, zero otherwise, with an error message likely available from GetError.

The cell bounding boxes for geometry are computed as the file is read, so that if the NoReadLabels variable is set during the read, i.e., when OpenCellHierDigest is called, text labels will not contribute to the bounding box computation.

(int) ChdSetDefCellName(chd_name, cellname)
This will set or unset the configuration of a default cell namein the Cell Hierarchy Digest whose access name is given in the first argument.

If the cellname argument in not 0 or null, it must be a cell name after any aliasing that was in force when the CHD was created, that exists in the CHD. This will set the default cell name for the CHD which will be used subsequently by the CHD whenever a cell name is not otherwise specified. The current default cell name is returned from the ChdDefCellName function. If cellname is 0 or null, the default cell name is unconfigured. In this case, the CHD will use the first top-level cell found (lowest offset on the archive file). A top-level cell is one that is not used as a subcell by any other cell in the CHD.

One is returned on success, zero otherwise, with an error message likely available with GetError.

(string) ChdDefCellName(chd_name)
This will return the default cell name of the Cell Hierarchy Digest whose access name is given in the argument. This will be the cell name configured (with ChdSetDefCellName), or if no cell name is configured the return will be the name of the first top-level cell found (lowest offset on the archive file). A top-level cell is one that is not used as a subcell by any other cell in the CHD.

On error, a null string is returned, with an error message likely available from GetError.

(int) ChdLoadGeometry(chd_name)
This function will read the geometry from the original layout file from the Cell Hierarchy Digest (CHD) whose access name is given in the argument into a new Cell Geometry Digest (CGD) in memory, and configures the CHD to link to the new CGD for use when reading. The new CGD is given an internally-generated access name, and will store all geometry data in memory. The new CGD will be destroyed when unlinked.

This is a convenience function, one can explicitly create a CGD (with OpenCellGeomDigest) and link it to the CHD (with ChdLinkCgd) if extended features are needed.

See the table in 14.1 for the features that apply during a call to this function.

The return value is 1 on success, 0 otherwise, with an error message likely available from GetError.

(int) ChdLinkCgd(chd_name, cgd_name)
This function links or unlinks a Cell Geometry Digest (CGD) whose access name is given as the second argument, to the Cell Hierarchy Digest (CHD) whose access name is given as the first argument. With a CGD linked, when the CHD is used to access geometry data, the data will be obtained from the CGD, if it exists in the CGD, and from the original layout file if not provided by the CGD. The CGD is a ``geometry cache'' which resides in memory.

If the cgd_name is null or empty (0 can be passed for this argument) any CGD linked to the CHD will be unlinked. If the CGD was created specifically to link with the CHD, such as with ChdLoadGeometry, it will be freed from memory, otherwise it will be retained.

This function returns 1 on success, 0 otherwise with an error message likely available from GetError.

(string) ChdGetGeomName(chd_name)
The string argument is an access name for a Cell Hierarchy Digest (CHD) in memory. If the CHD exists and has an associated Cell Geometry Digest (CGD) linked (e.g., ChdLoadGeometry was called), this function returns the access name of the CGD. If the CHD is not found or not configured with a CGD, a null string is returned.

(int) ChdClearGeometry(chd_name)
This function will clear the link to the Cell Geometry Digest within the Cell Hierarchy Digest. If a CGD was linked, and it was created explicitly for linking into the CHD as in ChdLoadGeometry, the CGD will be freed, otherwise it will be retained. The return value is 1 if the CHD was found, 0 otherwise, with a message available from GetError.

This function is identical to ChdLinkCgd with a null second argument.

(int) ChdSetSkipFlag(chd_name, cellname, skip)
This will set/unset the skip flag in the Cell Hierarchy Digest (CHD) whose access name is given in the first argument for the cell named in cellname (physical only).

The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

With the skip flag set, the cell is ignored in the CHD, i.e., the cell and its instances will not be included in output or when reading into memory when the CHD is used to access layout data. The last argument is a boolean value: 0 to unset the skip flag, nonzero to set it. The return value is 1 if a flag was altered, 0 otherwise, with an error message likely available from GetError.

(int) ChdClearSkipFlags(chd_name)
This will clear the skip flags for all cells in the Cell Hierarchy Digest whose access name is given in the argument. The skip flags are set with SetSkipFlag. The return value is 1 on success, 0 otherwise, with an error message likely available with GetError.

(int) ChdCompare(chd_name1, cname1, chd_name2, cname2, layer_list, skip_layers, maxdiffs,
obj_types, geometric, array)
This will compare the contents of two cells, somewhat similar to the !compare command and the Compare Layouts operation in the Convert Menu. However, only one cell pair is compared, taking account only of features within the cells. The ChdCompareFlat function is similar, but flattens geometry before comparison.

When comparing subcells, arrays will be expanded into individual instances before comparison, avoiding false differences between arrayed and unarrayed equivalents. The returned handles (if any) contain differences, as lists of object copies. Properties are ignored.

The arguments are:

chd_name1
Access name of a Cell Hierarchy Digest (CHD) in memory.

cname1
Name of cell in chd_name1 to compare, if null (0 passed) the default cell in chd_name1 is used.

chd_name2
If not null or empty (one can pass 0 for this argument), the name of another CHD.

cname2
Name of cell in the second CHD, or in memory, to compare. If null, or 0 is passed, and a second CHD was specified, the second CHD's default cell is understood. Otherwise, the name will be assumed the same as cname1.

layer_list
String of space-separated layer names, or zero which implies all layers.

skip_layers
If this boolean value is nonzero and a layer_list was given, the layers in the list will be skipped. Otherwise, only the layers in the list will be compared (all layers if layer_list is passed zero).

maxdiffs
The function will return after recording this many differences. If 0 or negative, there is no limit.

obj_types
String consisting of the layers c,b,p,w,l, which determines objects to consider (subcells, boxes, polygons, wires, and labels), or zero. If zero, ``cbpw'' is the default, i.e., labels are ignored. If the geometric argument is nonzero, all but 'c' will be ignored, and boxes, polygons, and wires will be compared.

geometric
If this boolean value is nonzero, a geometric comparison will be performed, otherwise objects are compared directly.

array
This is a two-element or larger array, or zero. If an array is passed, upon return the elements are handles to lists of box, polygon, and wire object copies (labels and subcells are not returned): array[0] contains a list of objects in handle1 and not in handle2, and array[1] contains objects in handle2 and not in handle1. The H function must be used on the array elements to access the handles. If the argument is passed zero, no object lists are returned.

The cells for the current mode (electrical or physical) are compared. The scalar return can take the following values:

-1	An error occurred, with a message possibly available from the GetError function.
0	Successful comparison, no differences found.
1	Successful comparison, differences found.
2	The cell was not found in chd_name1.
3	The cell was not found in chd_name2.
4	The cell was not found in either source.

(int) ChdCompareFlat(chd_name1, cname1, chd_name2, cname2, layer_list, skip_layers,
maxdiffs, area, coarse_mult, find_grid, array)
This will compare the contents of two hierarchies, using a flat geometry model similar to the flat options of the !compare command and the Compare Layouts operation in the Convert Menu. The ChdCompare function is similar, but does not flatten.

The returned handles (if any) contain the differences, as lists of objects. Properties are ignored.

The arguments are:

chd_name1
Access name of a Cell Hierarchy Digest (CHD) in memory.

cname1
Name of cell in chd_name1 to compare, if null (0 passed) the default cell in chd_name1 is used.

chd_name2
Access name of another CHD in memory. This argument can not be null as in ChdCompare, flat comparison to memory cells is unavailable.

cname2
Name of cell in the second CHD to compare. If null, or 0 is passed, the second CHD's default cell is understood.

layer_list
String of space-separated layer names, or zero which implies all layers.

skip_layers
If this boolean value is nonzero and a layer_list was given, the layers in the list will be skipped. Otherwise, only the layers in the list will be compared (all layers if layer_list is passed zero).

maxdiffs
The function will return after recording this many differences. If 0 or negative, there is no limit.

area
This argument can be an array of size 4 or larger, or 0. If an array, it contains a rectangle description in order L,B,R,T in microns, which specifies the area to compare. If 0 is passed, the area compared will contain the two hierarchies entirely.

coarse_mult
The comparison is performed in the manner described for the ChdIterateOverRegion function, using a fine grid and a coarse grid. This argument specifies the size of the coarse grid in multiples of the fine grid size. All of the geometry needed for a coarse grid cell is brought into memory at once, so this size should be consistent with memory availability and layout feature density. Values of 1-100 are accepted for this argument, with 20 a reasonable initial choice.

fine_grid
Comparison is made within a fine grid cell. The optimum fine grid size depends on factors including layout feature density and memory availability. Larger sizes usually run faster, but may require excessive memory. The value is given in microns, with the acceptable range being 1.0 - 100.0 microns. A reasonable initial choice is 20.0, but experimentation can often yield better performance.

array
This is a two-element or larger array, or zero. If an array is passed, upon return the elements are handles to lists of box, polygon, and wire object copies (labels and subcells are not returned): array[0] contains a list of objects in handle1 and not in handle2, and array[1] contains objects in handle2 and not in handle1. The H function must be used on the array elements to access the handles. If the argument is passed zero, no object lists are returned.

The cells for the physical mode are compared, it is not possible to compare electrical cells in flat mode. The return value is an integer, -1 on error (with a message likely available from GetError), 0 if no differences were seen, or positive giving the number of differences seen.

(int) ChdEdit(chd_name, scale, cellname)
This will read the given cell and its descendents into memory and open the cell for editing, similar to the Edit function, however the layout data will be accessed through the Cell Hierarchy Digest whose access name is given in the first argument. The return value takes the same values as the Edit function return.

See the table in 14.1 for the features that apply during a call to this function.

The scale will multiply all coordinates in cells opened, and can be in the range 0.001 - 1000.0.

The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

(int) ChdOpenFlat(chd_name, scale, cellname, array, clip)
This will read the cell named in the cellname string and its subcells into memory, creating a flat cell with the same name. The Cell Hierarchy Digest (CHD) whose access name is given in the first argument is used to obtain the layout data.

See the table in 14.1 for the features that apply during a call to this function. Text labels are ignored.

The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

If the cell already exists in memory, it will be overwritten.

The scale will multiply all coordinates read, and can be in the range 0.001 - 1000.0.

If the array argument is passed 0, no windowing will be used. Otherwise the array should have four components which specify a rectangle, in microns, in the coordinates of cellname. The values are

array[0]	X left
array[1]	Y bottom
array[2]	X right
array[3]	Y top

If an array is given, only the objects and subcells needed to render the window will be read.

If the boolean value clip is nonzero and an array is given, objects will be clipped to the window. Otherwise no clipping is done.

Before calling ChdOpenFlat, the memory use can be estimated by calling the ChdEstFlatMemoryUse function. An overall transformation can be set with ChdSetFlatReadTransform, in which case the area given applies in the ``root'' coordinates.

The return value is 1 on success, 0 on error, or -1 if an interrupt was received. In the case of an error return, an error message may be available through GetError.

(real) ChdSetFlatReadTransform(tfstring, x, y)
This rather arcane function will set up a transformation which will be used during calls to the following functions:

ChdOpenFlat
ChdWriteSplit
ChdGetZlist
ChdOpenOdb
ChdOpenZdb
ChdOpenZbdb

The transform will be applied to all of the objects read through the CHD with these functions. Why might this function be used? Consider the following: suppose we have a CHD describing a cell hierarchy, the top-level cell of which is to be instantiated under another cell we'll call ``root'', with a given transformation. We would like to consider the objects from the CHD from the perspective of the ``root'' cell. This function would be called to set the transformation, then one of the flat read functions would be called and the returned objects accumulated. The returned objects will have coordinates relative to the ``root'' cell, rather than relative to the top-level cell of the CHD.

The tfstring describes the rotation and mirroring part of the transformation. It is either one of the special tokens to be described, or a sequence of the following tokens:

MX
Flip the X axis.

MY
Flip the Y axis.

Rnnn
Rotate by nnn degrees. The nnn must be one of 0, 45, 90, 135, 180, 225, 270, 315.

White space can appear between tokens. The operations are performed in order. Note that, e.g., ``MXR90'' is very different from ``R90MX''.

Alternatively, the tfstring can contain a single ``Lef/Def'' token as listed below. The second column is the equivalent string using the syntax previously described.

N	null or empty or R0
S	R180
W	R90
E	R270
FN	MX
FS	MY
FW	MYR90
FE	MXR90

The x and y are the translation part of the transformation. These are coordinates, given in microns.

If tfstring is null or empty, no rotations or mirroring will be used.

The function returns 1 on success, 0 if the tfstring contains an error.

(real) ChdEstFlatMemoryUse(chd_name, cellname, array, counts_array)
This function will return an estimate of the memory required to perform a ChdOpenFlat call. The first argument is the access name of an existing Cell Hierarchy Digest that was created with per-cell object counts saved (e.g., a call to OpenCellHierDigest with the info_saved argument set to 3 or 4).

The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

The third argument is an array of size four or larger that contains the rectangular area as passed to the ChdOpenFlat call. The components are

array[0]	X left
array[1]	Y bottom
array[2]	X right
array[3]	Y top

This argument can also be zero to indicate that the full area of the top level cell is to be considered.

The final argument is also an array of size four or larger, or zero. If an array is passed, and the function succeeds, the components are filled with the following values:

counts_array[0]	estimated total box count
counts_array[1]	estimated total polygon count
counts_array[2]	estimated total wire count
counts_array[3]	estimated total vertex count

These are counts of objects that would be saved in the top-level cell during the ChdOpenFlat call. These are estimates, based on area normalization, and do not include any clipping or merging. The vertex count is an estimate of the total number of polygon and wire vertices.

The return value is an estimate, in megabytes, of the incremental memory required to perform the ChdOpenFlat call. This does not include normal overhead.

(int) ChdWrite(chd_name, scale, cellname, array, clip, all, flatten, ecf_level, outfile)
This will write the cell named in the cellname string to the output file given in outfile, using the Cell Hierarchy Digest whose access name is given in the first argument to obtain layout data.

If the outfile is null or empty, the geometry will be ``written'' as cells in the main database, hierarchically if all is true. This allows windowing to be applied when converting a hierarchy, which will attempt to convert only objects and cells needed to render the window area. This has the potential to hopelessly scramble your in-memory design data so be careful.

See the table in 14.1 for the features that apply during a call to this function.

The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

If the boolean argument all is nonzero, the hierarchy under the cell is written, otherwise only the named cell is written. If the outfile is null or empty, native cell files will be created in the current directory. If the outfile is the name of an existing directory, native cell files will be created in that directory. Otherwise, the extension of the outfile determines the file type:

CGX	.cgx
CIF	.cif
GDSII	.gds, .str, .strm, .stream
OASIS	.oas

Only these extensions are recognized, however CGX and GDSII allow an additional .gz which will imply compression.

The scale will multiply all coordinates read, and can be in the range 0.001 - 1000.0.

If the array argument is passed 0, no windowing will be used. Otherwise the array should have four components which specify a rectangle, in microns, in the coordinates of cellname. The values are

array[0]	X left
array[1]	Y bottom
array[2]	X right
array[3]	Y top

If an array is given, only the objects and subcells needed to render the window will be written.

If the boolean value clip is nonzero and an array is given, objects will be clipped to the window. Otherwise no clipping is done.

If the boolean value all is nonzero, the hierarchy under cellname is written, otherwise not. If windowing is applied, this applies only to cellname, and not subcells.

If the boolean variable flatten is nonzero, the objects in the hierarchy under cellname will be written into cellname, i.e., flattened. The all argument is ignored in this case. Otherwise, no flattening is done.

The ecf_level is an integer 0-3 which sets the empty cell filtering level, as described for the Format Conversion panel in 14.10. The values are

0	No empty cell filtering.
1	Apply pre- and post-filtering.
2	Apply pre-filtering only.
3	Apply post-filtering only.

The return value is 1 on success, 0 on error, or -1 if an interrupt was received. In the case of an error return, an error message may be available through GetError.

(int) ChdWriteSplit(chd_name, cellname, basename, array, regions_or_gridsize,
numregions_or_bloatval, maxdepth, scale, flags)
This function will read the geometry data through the a Cell Hierarchy Digest (CHD) whose name is given as the first argument, into a collection of files representing rectangular regions of the top-level cell. Each output file contains only the cells and geometry necessary to represent the region. The regions can be specified as a list of rectangles, or as a grid.

See the table in 14.1 for the features that apply during a call to this function.

cellname
The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

basename
The basename is a cell path name in the form

[/path/to/]basename.ext,

where the extension ext gives the type of file to create. One of the following extensions must be provided:

CGX output	.cgx
CIF output	.cif
GDSII output	.gds, .str, .strm, .stream
OASIS output	.oas, .oasis

A ``.gz'' second extension is allowed following CGX and GDSII extensions in which case the files will be compressed using the gzip format.

When writing a list of regions, the output files will be named in the form basename_N.ext, where the .ext is the extension supplied, and N is a 0-based index of the region, ordered as given. When writing a grid, the output files will be named in the form basename_X_Y.ext, where the .ext is the extension supplied, and X,Y are integer indices representing the grid cell (origin is the lower-left corner). If a directory path is prepended to the basename, the files will be found in that directory (which must exist, it will not be created).

array
The array argument can be 0, or the name of an array of size four or larger that contains a rectangle specification, in microns, in order L,B,R,T. If given, the rectangle should intersect the bounding box of the top-level cell (cellname). Only cells and geometry within this area will be written to output. If 0 is passed, the entire bounding box of the top cell is understood.

When writing grid files, the origin of the grid, before bloating, is at the lower-left corner of the area to be output.

regions_or_gridsize
This argument can be an array, or a scalar value. If an array, the array consists of one or more rectangular area specifications, in order L,B,R,T in microns. These are the regions that will be written to output files.

If this argument is a number, it represents the size of a square grid cell, in microns.

bloatval
If an array was passed as the previous argument, then this argument is an integer giving the number of regions in the array to be written. The size of the array is at least four times the number of regions.

If instead a grid value was given in the previous argument, then this argument provides a bloating value. The grid cells will be bloated by this value (in microns) if the value is nonzero. A positive value pushes out the grid cell edges by the value given, a negative value does the reverse.

maxdepth
This integer value applies only when flattening, and sets the maximum hierarchy depth for include in output. If 0, only objects in the top-level cell will be included,

scale
This is a scale factor which will be applied to all output. The gridsize, bloatval, and array coordinates are the sizes found in output, and are independent of the scale factor. The valid range is 0.001 - 1000.0.

flags
This argument is a string consisting of specific letters, the presence of which sets one of several available modes. These are

p	parallel
f	flatten
c	clip
n[N]	empty cell filtering
m	map names

The character recognition is case-insensitive. A null or empty string indicates no flags set.

p
If p is given, a parallel writing algorithm is used. Otherwise, the output files are generated in sequence. The files should be identical from either writing mode. The parallel mode may be a little faster, but requires more internal memory. When writing in parallel, the user may encounter system limitations on the number of file descriptors open simultaneously.

f
If f is given, the output will be flattened. When flattening, an overall transformation can be set with ChdSetFlatReadTransform, in which case the given area description would apply in the ``root'' coordinates.

If not given, the output files will be hierarchical, but only the subcells needed to render the grid cell area, each containing only the geometry needed, will be written.

c
If c is given, objects will be clipped at the grid cell boundaries. This also applies to objects in subcells, when not flattening.

n[N]
The `n' can optionally be followed by an integer 0-3. If no integer follows, `3' is understood. This sets the empty cell filtering level as described for the Format Conversion panel in 14.10. The values are

0	No empty cell filtering (no operation).
1	Apply pre- and post-filtering.
2	Apply pre-filtering only.
3	Apply post-filtering only.

m
If m is given, and f is also given (flattening), the top-level cell names in the output files will be modified so as to be unique in the collection. A suffix ``_N'' is added to the cell name, where N is a grid cell or region index. The index is 0 for the lower-left grid cell, and is incremented in the sweep order left to right, bottom to top. If writing regions, the index is 0-based, in the order of the regions given. Furthermore, a native cell file is written, named ``basename_root'', which calls each of the output files. Loading this file will load the entire output collection, memory limits permitting.

The function returns 1 on success, 0 otherwise, with an error message likely available from GetError.

(int) ChdCreateReferenceCell(chd_name, cellname)
This function will create a reference cell (see 8.9.3) in memory. A reference cell is a special cell that references a cell hierarchy in an archive file, but does not have its own content. Reference cells can be instantiated during editing like any other cell, but their content is not visible. When a reference cell is written to disk as part of a cell hierarchy, the hierarchy of the reference cell is extracted from its source and streamed into the output.

The first argument is a string giving the name of a Cell Hierarchy Digest (CHD) already in memory. The second argument is the name of a cell in the CHD, which must include aliasing if aliasing was applied when the CHD was created. This will also be the name of the reference cell. A cell with this name should not already exist in current symbol table.

Although the CHD is required for reference cell creation, it is not required when the reference cell is written, but will be used if present. The archive file associated with the CHD should not be moved or altered before the reference cell is written to disk.

A value 0 is returned on error, with a message probably available from GetError. The value 1 is returned on success.

(int) ChdLoadCell(chd_name, cellname)
This function will load a cell into the main editing database, and subcells of the cell will be loaded as reference cells (see 8.9.3). This allows the cell to be edited, without loading the hierarchy into memory. When written to disk as part of a hierarchy, the cell hierarchies of the reference cells will be extracted from the input source and streamed to output.

The first argument is a string giving the name of a Cell Hierarchy Digest (CHD) already in memory. The second argument is the name of a cell in the CHD, which must include aliasing if aliasing was applied when the CHD was created. This cell will be read into memory. Any subcells used by the cell will be created in memory as reference cells, which a special cells which have no content but point to a source for their content.

Although the CHD is required for reference cell creation, it is not required when the reference cell is written, but will be used if present. The archive file associated with the CHD should not be moved or altered before the reference cell is written to disk.

A value 0 is returned on error, with a message probably available from GetError. The value 1 is returned on success.

$\parbox{6in}{(int) \tt ChdIterateOverRegion({\it chd\_name\/}, {\it... ...\it coarse\_mult\/}, {\it fine\_grid\/},\\ \hspace*{1.5cm}{\it bloat\_val})}$
This function is an interface to a system which creates a logical rectangular grid over a cell hierarchy, then iterates over the partitions in the grid, performing some action on the logically flattened geometry.

A Cell Hierarchy Digest (CHD) is used to obtain the flattened geometry, with or without the assistance of a Cell Geometry Digest (CGD). There are actually two levels of gridding: the coarse grid, and the fine grid. The area of interest is first logically partitioned into the coarse grid. For each cell of the coarse grid, a ``ZBDB'' special database (see F.7.4) is created, using the fine grid. For example, one might choose 400x400 microns for the coarse grid, and 20x20 microns for the fine grid. Thus, geometry access is in 400x400 ``chunks''. The geometry is extracted, flattened, and split into separate trapezoid lists for each fine grid area, for each layer.

As each fine grid cell is visited, a user-supplied script function is called. The operations performed are completely up to the user, and the framework is intended to be as flexible as possible. As an example, one might extract geometric parameters such as density, minimum line width and spacing, for use by a process analysis tool. Scalar parameters can be conveniently saved in spatial parameter tables (SPTs, see F.7.3).

The first argument is the access name of a CHD in memory. The second argument is the top-level cell from the CHD, or if passed 0, the CHD's default cell will be used.

The third argument is the name of a user-supplied script function which will implement the user's calculations. The function should already be in memory before ChdIterateOverRegion is called. This function is described in more detail below.

The array argument can be 0, in which case the area of interest is the entire top-level cell. Otherwise, the argument should be an array of size four or larger containing the rectangular area of interest, in order L,B,R,T in microns. The coarse and find grid origin is at the lower left corner of the area of interest.

The fine_grid argument is the size of the fine grid (which is square) in microns. The coarse_mult is an integer representing the size of the coarse grid, in fine_grid quanta.

The bloat_val argument specifies an amount, in microns, that the grid cells (both coarse and fine) should be expanded when returning geometry. Geometry is clipped to the bloated grid. Thus, it is possible to have some overlap in the geometry returned from adjacent grid cells. This value can be negative, in which case grid cells will effectively shrink.

The callback function has the following prototype.

(int) callback(db_name, j, i, spt_x, spt_y, data, cell_name, chd_name)

The function definition must start with the db_name and include the arguments in the order shown, but unused arguments to the right of the last needed argument can be omitted.

db_name (string)
The access name of the ZBDB database containing geometry.

j (integer)
The X index of the current fine grid cell.

i (integer)
The Y index of the current fine grid cell.

spt_x (real)
The X coordinate value in microns of the current grid cell in a spatial parameter table:
coarse_grid_cell_left + j*fine_grid_size + fine_grid_size/2

spt_y (real)
The Y coordinate value in microns of the current grid cell in a spatial parameter table:
coarse_grid_cell_bottom + i*fine_grid_size + fine_grid_size/2

data (real array)
An array containing miscellaneous parameters, described below).

cell_name (string)
The name of the top-level cell.

chd_name (string)
The access name of the CHD.

The data argument is an array that contains the following parameters.

index	description
0	The spatial parameter table column size.
1	The spatial parameter table row size.
2	The fine grid period in microns.
3	The coarse grid period in microns.
4	The amount of grid cell expansion in microns.
5	Area of interest left in microns.
6	Area of interest bottom in microns.
7	Area of interest right in microns.
8	Area of interest top in microns.
9	Coarse grid cell left in microns.
10	Coarse grid cell bottom in microns.
11	Coarse grid cell right in microns.
12	Coarse grid cell top in microns.
13	Fine grid cell left in microns.
14	Fine grid cell bottom in microns.
15	Fine grid cell right in microns.
16	Fine grid cell top in microns.

The trapezoid data for the grid cells can be accessed, from within the callback function, with the GetZlistZbdb function.

GetZlistZbdb(db_name, layer_lname, j, i)

Example:
Here is a function that simply prints out the fine grid indices, and the number of trapezoids in the grid location on a layer named ``M1''.

function myfunc(dbname, j, i, x, y, prms)
zlist = GetZlistZbdb(dbname, "M1", j, i)
Print("Location", j, i, "contains", Zlength(zlist), "zoids on M1")
endfunc

If the function returns a nonzero value, the operation will abort. If there is no explicit return statement, the return value is 0.

if (some error)
return 1
end

If all goes well, ChdIterateOverRegion returns 1, otherwise 0 is returned, with an error message possibly available from GetError.

This function is intended for OEM users, customization is possible. Contact Whiteley Research for more information.

(int) ChdWriteDensityMaps(chd_name, cellname, array, coarse_mult, fine_grid, bloat, save)
This function uses the same framework as ChdIterateOverRegion, but is hard-coded to extract density values only. The chd_name, cellname, array, coarse_mult, and fine_grid arguments are as described for that function.

When called, the function will iterate over the given area, and compute the fraction of dark area for each layer in a fine grid cell, saving the values in a spatial parameter table (SPT, see F.7.3). The access names of these SPTs are in the form cellname.layername, where cellname is the name of the top-level cell being processed. The layername is the name of the layer, possibly in hex format as used elsewhere.

If the boolean save argument is nonzero, the SPTs will be retained in memory after the function returns. Otherwise, the SPTs will be dumped to files in the current directory, and destroyed. The file names are the same as the SPT names, with a ``.spt'' extension added. These files can be read with ReadSPtable, and are in the format described for that function, with the ``reference coordinates'' the central points of the fine grid cells.

If all goes well, ChdWriteDensityMaps returns 1, otherwise 0 is returned, with an error message possibly available from GetError.