Coordinate Systems

AbstractCoordinateSystem{S<:Coordinate} <: GeometryStructure{S}

Abstract supertype for coordinate systems, including CoordinateSystem and Cell.

Also exists to avoid circular definitions involving the concrete AbstractCoordinateSystem types and subtypes of GeometryReference.

addref!(c1::AbstractCoordinateSystem, cr::GeometryReference)

Add the reference cr to the list of references in c1.

addref!(c1::AbstractCoordinateSystem{T},
    c2::GeometryStructure,
    origin=zero(Point{T});
    kwargs...)

Add a reference to c2 to the list of references in c1.

The reference to c2 has origin origin; x-reflection, magnification factor, and rotation are set by keywords arguments.

Synonyms are accepted for these keywords:

• X-reflection: :xrefl, :xreflection, :refl, :reflect, :xreflect, :xmirror, :mirror
• Magnification: :mag, :magnification, :magnify, :zoom, :scale
• Rotation: :rot, :rotation, :rotate, :angle

addarr!(
    c1::AbstractCoordinateSystem{T},
    c2::GeometryStructure,
    origin::Point=zero(Point{T});
    kwargs...
)

Add an ArrayReference to c2 to the list of references in c1.

The reference to c2 has origin origin. Keyword arguments specify the column vector, row vector, number of columns, number of rows, x-reflection, magnification factor, and rotation.

Synonyms are accepted for these keywords:

• Column vector dc::Point{T}: :deltacol, :dcol, :dc, :vcol, :colv, :colvec, :colvector, :columnv, :columnvec, :columnvector
• Row vector: :deltarow, :drow, :dr, :vrow, :rv, :rowvec, :rowvector
• Number of columns: :nc, :numcols, :numcol, :ncols, :ncol
• Number of rows: :nr, :numrows, :numrow, :nrows, :nrow
• X-reflection: :xrefl, :xreflection, :refl, :reflect, :xreflect, :xmirror, :mirror
• Magnification: :mag, :magnification, :magnify, :zoom, :scale
• Rotation: :rot, :rotation, :rotate, :angle

addarr!(
    c1::AbstractCoordinateSystem,
    c2::GeometryStructure,
    c::AbstractRange,
    r::AbstractRange;
    kwargs...
)

Add an ArrayReference to c2 to the list of references in c1, based on ranges.

c specifies column coordinates and r for the rows. Pairs from c and r specify the origins of the repeated cells. The extrema of the ranges therefore do not specify the extrema of the resulting ArrayReference's bounding box; some care is required.

Keyword arguments specify x-reflection, magnification factor, and rotation, with synonyms allowed:

• X-reflection: :xrefl, :xreflection, :refl, :reflect, :xreflect, :xmirror, :mirror
• Magnification: :mag, :magnification, :magnify, :zoom, :scale
• Rotation: :rot, :rotation, :rotate, :angle

flatten!(c::AbstractCoordinateSystem, depth::Integer=-1, metadata_filter=nothing, max_copy=Inf)

Recursively flatten references and arrays up to a hierarchical depth, adding their elements to c with appropriate transformations.

The references and arrays that were flattened are then discarded. Deeper references and arrays are brought upwards and are not discarded.

This function has no effect for depth == 0, and unlimited depth by default.

mutable struct Cell{S<:Coordinate}

A cell has a name and contains polygons and references to CellArray or CellReference objects. It also records the time of its own creation. As currently implemented it mirrors the notion of cells in GDSII files.

To add elements, use render!. To add references, use addref! or addarr!. To add text, use text!.

Cell(name::AbstractString)

Convenience constructor for Cell{typeof(1.0UPREFERRED)}.

DeviceLayout.UPREFERRED is a constant set according to the unit preference in Project.toml or LocalPreferences.toml. The default ("PreferNanometers") gives const UPREFERRED = DeviceLayout.nm, with mixed-unit operations preferring conversion to nm.

Unit preference does not affect the database scale for GDS export.

dbscale(c::Cell)

Give the database scale for a cell. The database scale is the smallest increment of length that will be represented in the output CAD file. This is different from the working coordinate type T of the Cell.

The database scale defaults to 1nm (1.0nm if T <: FloatCoordinate), but can be changed by updating c.dbscale to a new Unitful.Length quantity.

dbscale(cell::Cell...)

Choose an appropriate database scale for a GDSII file given Cells of different types. The smallest database scale of all cells considered is returned.

const CellArray

Alias for ArrayReferences to Cells.

const CellReference

Alias for StructureReferences to Cells.

struct GDSMeta <: DeviceLayout.Meta
    layer::Int
    datatype::Int
    GDSMeta() = new(DEFAULT_LAYER, DEFAULT_DATATYPE)
    GDSMeta(l) = new(l, DEFAULT_DATATYPE)
    GDSMeta(l, d) = new(l, d)
end

Metadata associated with GDSII format. Default layer and datatype are 0.

render!(c::Cell, p::Polygon, meta::GDSMeta=GDSMeta())

Render a polygon p to cell c, defaulting to plain styling. If p has more than 8190 (set by DeviceLayout's GDS_POLYGON_MAX constant), then it is partitioned into smaller polygons which are then rendered. Environment variable ENV["GDS_POLYGON_MAX"] will override this constant. The partitioning algorithm implements guillotine cutting, that goes through at least one existing vertex and in manhattan directions. Cuts are selected by ad hoc optimzation for "nice" partitions.

save(::Union{AbstractString,IO}, cell0::Cell{T}, cell::Cell...)
save(f::File{format"GDS"}, cell0::Cell, cell::Cell...;
    name="GDSIILIB", userunit=1μm, modify=now(), acc=now(),
    spec_warnings=true, verbose=false)

This bottom method is implicitly called when you use the convenient syntax of the top method: save("/path/to/my.gds", cells_i_want_to_save...)

Keyword arguments include:

• name: used for the internal library name of the GDSII file and probably inconsequential for modern workflows.
• userunit: sets what 1.0 corresponds to when viewing this file in graphical GDS editors with inferior unit support.
• modify: date of last modification.
• acc: date of last accession. It would be unusual to have this differ from now().
• spec_warnings: whether to emit warnings due to GDSII format violations (default: true)
• verbose: monitor the output of traverse! and order! to see if something funny is happening while saving.

traverse!(a::AbstractArray, c::GeometryStructure, level=1)

Given a coordinate system, recursively traverse its references for other coordinate systems and add to array a some tuples: (level, c). level corresponds to how deep the coordinate system was found, and c is the found coordinate system.

order!(a::AbstractArray)

Given an array of tuples like that coming out of traverse!, we sort by the level, strip the level out, and then retain unique entries. The aim of this function is to determine an optimal writing order when saving pattern data (although the GDSII spec does not require cells to be in a particular order, there may be performance ramifications).

For performance reasons, this function modifies a but what you want is the returned result array.

mutable struct CoordinateSystem{S<:Coordinate} <: AbstractCoordinateSystem{S}
    name::String
    elements::Vector{GeometryEntity{S}}
    meta::Vector{Meta}
    refs::Vector{GeometryReference}
    create::DateTime

    CoordinateSystem{S}(x, y, ym, z, t) where {S} = new{S}(x, y, ym, z, t)
    CoordinateSystem{S}(x, y, ym, z) where {S} = new{S}(x, y, ym, z, now())
    CoordinateSystem{S}(x, y, ym) where {S} = new{S}(x, y, ym, GeometryReference[], now())
    CoordinateSystem{S}(x) where {S} =
        new{S}(x, GeometryEntity{S}[], Meta[], GeometryReference[], now())
    CoordinateSystem{S}() where {S} = begin
        c = new{S}()
        c.elements = GeometryEntity{S}[]
        c.meta = Meta[]
        c.refs = GeometryReference[]
        c.create = now()
        c
    end
end

A CoordinateSystem has a name and contains geometry entities (Polygons, Rectangles) and references to GeometryStructure objects. It also records the time of its own creation.

To add elements, use place!, or use render! to be agnostic between CoordinateSystem and Cell. To add references, use addref! or addarr!.

const CoordinateSystemReference

Alias for StructureReferences to CoordinateSystems.

const CoordinateSystemArray

Alias for ArrayReferences to CoordinateSystems.

place!(cs::CoordinateSystem, ent::GeometryEntity, metadata)

Place ent in cs with metadata metadata.

place!(cs::CoordinateSystem, s::GeometryStructure)

Place a reference to s in cs.

place!(cs::CoordinateSystem, p::Path, metadata=p.metadata)

Place a reference to p in cs and set metadata to metadata.

struct SemanticMeta <: DeviceLayout.Meta
    layer::Symbol
    index::Int = 1
    level::Int = 1
end
SemanticMeta(layer::String; kwargs...)
SemanticMeta(meta::Meta; kwargs...)

DeviceLayout-native representation of an object's layer information and attributes.

Semantic metadata refers to the meaning of an element without reference to a fixed encoding. For example, “this polygon is in the negative of the ground plane” is semantic, while “this polygon is in GDS layer 1, datatype 2” is not. The semantic metadata is used in the final render step, where a layout is converted from a CoordinateSystem to a representation corresponding to a particular output format (e.g., a Cell for GDSII). A call to render!(cell::Cell{S}, cs::CoordinateSystem; map_meta = identity, kwargs...) will use the map_meta function to map each GeometryEntity's metadata to GDSMeta.

The level and index fields do not have a strict interpretation imposed by DeviceLayout. (In this sense they are similar to GDS datatype.) The suggested use is as follows:

• index distinguishes numbered instances within a layer, for example in greyscale lithography or port numbering
• level distinguishes instances of a layer occurring in different contexts, such as in a 3D stack where equivalent layers may be present in multiple levels

layer(m::Meta)

The layer specified by m, as a Symbol.

For example, layer(GDSMeta(1, 2)) is :GDS1_2, and layername(SemanticMeta(:base)) is :base.

layerindex(m::Meta)

The index specified by metadata m. Defaults to 1 for metadata types without an index.

layername(m::Meta)

The layer specified by m, as a String.

For example, layer(GDSMeta(1, 2)) is "GDS1_2", and layername(SemanticMeta(:base)) is "base".

level(m::Meta)

The level specified by metadata s. Defaults to 1 for metadata types without a level.

Cell(cs::CoordinateSystem{S}) = Cell{S}(cs)
Cell(cs::CoordinateSystem, unit::CoordinateUnits) = Cell{typeof(1.0unit)}(cs)
Cell{S}(cs::CoordinateSystem) where {S}

Construct a Cell from a CoordinateSystem by rendering its contents, reproducing the reference hierarchy.

render!(cell::Cell{S}, cs::GeometryStructure;
    memoized_cells=Dict{GeometryStructure, Cell}(),
    map_meta = identity,
    kwargs...) where {S}

Render a geometry structure (e.g., CoordinateSystem) to a cell.

Passes each element and its metadata (mapped by map_meta if a method is supplied) to render!(::Cell, element, ::Meta), traversing the references such that if a structure is referred to in multiple places, it will become a single cell referred to in multiple places.

Rendering a GeometryStructure to a Cell uses the optional keyword arguments

• map_meta, a function that takes a Meta object and returns a GDSMeta object (or nothing, in which case rendering is skipped)
• memoized_cells, a dictionary used internally to make sure that if a structure is referred to in multiple places, it will become a single cell referred to in multiple places. Calling this function with non-empty dictionary memoized_cells = Dict{GeometryStructure, Cell}(geom => prerendered_cell) is effectively a manual override that forces geom (which may be cs or any structure in its reference hierarchy) to render as prerendered_cell.

Additional keyword arguments are passed to to_polygons for each entity and may be used for certain entity types to control how they are converted to polygons.