Phase 1: self-intersecting polyslab

[weiliangjin2021]

The support of self-intersecting polyslabs is scheduled to roll out in two phases. In phase 1, we consider the case where the length of some edges can approach 0 (or neighboring vertices become degenerate) at some point during extrusion. In phase 2, more general types of edge events will be treated. The main idea in this PR is to divide a complex polyslab into many simple polyslabs.

• A class ComplexPolySlab is defined in plugin. It takes the same fields as PolySlab. We can consider move this class to geometry.py. The current design is to leave space for phase 2.
• An example on how to use this class can be found here. In short, one can use the property method .sub_polyslabs to obtain a list of simple polyslabs, or .geometry_group that wraps up the simple polyslabs in a geometry group.
• Constructing from GDS file is also supported. The usage is the same as PolySlab. Here is an example.
• There some updates to the visualization part in PolySlab: previously we cache the polygon on the base, and always use base polygon to construct polygons at other extrusion distance. However, now as we construct simple polyslabs from a complex polyslab, the degenerate vertices of the simple polyslab are removed on the top or the base. So the polygon on the base or the top can be different from the polygon in the between. An appropriate way is to use the polygon in the middle to construct polygons at other extrusion distance.

[tylerflex]

Looks good! I'm not able to follow everything but I think this general approach makes sense. So if a user wants to use a ComplexPolySlab in their Simulation, would the standard way be to

cps = ComplexPolySlab(...)
geo = cps.geometry_group
structure = td.Structure(geometry=geo, medium=medium)

? I worry a little that it won't be so clear to the new user how to do this, so maybe there can be some mention of this in the Docstring of ComplexPolySlab. For example

Class ComplexPolySlab(PolySlab):
    """ Interface for dividing a complex polyslab where self-intersecting polygon can occur during extrusion. 
    To generate a :class:`.GeometryGroup` from a `ComplexPolySlab`` instance for use in :class:`Simulation`, 
    pass `complex_polyslab.geometry_group` to the `geometry` field of :class:`.Structure`.
    """

[weiliangjin2021]

So if a user wants to use a ComplexPolySlab in their Simulation, would the standard way be to

cps = ComplexPolySlab(...)
geo = cps.geometry_group
structure = td.Structure(geometry=geo, medium=medium)

Right, and the other approach is

cps = ComplexPolySlab(...)
geo_list = cps.sub_polyslabs
structure_list = [td.Structure(geometry=geo, medium=medium) for geo in geo_list]

So how about a docstring like this?

Class ComplexPolySlab(PolySlab):
    """ Interface for dividing a complex polyslab where self-intersecting polygon can occur during extrusion. 
    The list of divided polyslabs can be accessed from a `ComplexPolySlab`` instance with 
    `complex_polyslab.sub_polyslabs`, or wrapped in a :class:`.GeometryGroup` with
    `complex_polyslab.geometry_group`.
    """

[lucas-flexcompute]

So if a user wants to use a ComplexPolySlab in their Simulation, would the standard way be to

cps = ComplexPolySlab(...)
geo = cps.geometry_group
structure = td.Structure(geometry=geo, medium=medium)

Right, and the other approach is

cps = ComplexPolySlab(...)
geo_list = cps.sub_polyslabs
structure_list = [td.Structure(geometry=geo, medium=medium) for geo in geo_list]

So how about a docstring like this?

Class ComplexPolySlab(PolySlab):
    """ Interface for dividing a complex polyslab where self-intersecting polygon can occur during extrusion. 
    The list of divided polyslabs can be accessed from a `ComplexPolySlab`` instance with 
    `complex_polyslab.sub_polyslabs`, or wrapped in a :class:`.GeometryGroup` with
    `complex_polyslab.geometry_group`.
    """

I usually find it most useful to have a small example straight into the documentation, much like numpy and scipy do. It's easy to understand and quicker to find than going through a complete example notebook (which should, of course, exist as a full reference and tutorial)

[tylerflex]

Related: It might be nice to add

def to_structure(self, medium: MediumType) -> td.Structure:
    """Construct a structure containing a user-specified medium and a GeometryGroup made of all the PolySlabs from this object."""

just as one other alternative to both of those.

[weiliangjin2021]

I usually find it most useful to have a small example straight into the documentation, much like numpy and scipy do. It's easy to understand and quicker to find than going through a complete example notebook (which should, of course, exist as a full reference and tutorial)

Good point. It has been added to the doc.

[lucas-flexcompute]

From what I can tell, this should work for edge collapsing (neighboring vertices merging), but I'm not sure it will be straightforward to implement the general case. That's because the subdivision algorithm explicitly uses the offset at which the collapsing event happens, which is much harder for edges. Anyway, for now it looks great!

[lucas-flexcompute]

This dilation/erosion might itself result in self-intersecting polygons. Should we do some clean-up to remove those? Here the problem is easier than with the extrusion, since it doesn't have to be compared to any other slabs. @weiliangjin2021 I believe you mentioned that shapely had already a function that could be used for this, right?

[weiliangjin2021]

I was thinking about doing this as well, but then quickly realized that if we allow self-intersecting polygon at the reference plane and perform clean-up, there are situations where the healed polygon can split and have islands/holes. So right now, we simply error in this case:

tidy3d/tidy3d/components/geometry.py

Lines 1854 to 1855 in 94b801b

	@pydantic.validator("vertices", always=True)
	def no_self_intersecting_polygon_at_reference_plane(cls, val, values):

Another possibility is to error only when the healed polygon splits or generates holes/islands, but allow the change of vertices number. What do you think?

[lucas-flexcompute]

I think its usually best to make it easier for the user, as long as we don't overstep on what their intentions might be. In this case, we should gracefully handle both cases, but I can see that the current API might make it difficult to return multiple islands. Maybe continue to error in this case, but handle the easier one, where we just clean-up the polygon and remain with a single proper polygon?

[weiliangjin2021]

Shall we error or just warning for polygon splitting/islands? I'm thinking about: 1) error for polygon splitting/islands; 2) warning for the change of the number of vertices.

[weiliangjin2021]

This part has been added. Quite significant change in the two validators.

[weiliangjin2021]

Actually, what I have now doesn't really address your comments, since I still offset the vertices first and then heal. I cannot think of any self-intersecting polygon that can really pass the validator here. Maybe let's plan on the next release.

[tomflexcompute]

This is an useful implementation. With the regular PolySlab, it seems like as long as the user knows where the vertices will meet during the extrusion, they can always manually define multiple polyslabs to achieve the same final geometry (group) as the ComplexPolySlab, but it could take a lot of trigometry to figure everything out.

My concern is that polyslabs that will result in self-intersection vertices usually have a more complex geometry. After extrusion, it might be difficult to examine if the result is correct only by examining the crossing section using the plot method. At this point, probably there is no better way than submitting the job to the server and going to web GUI for visualization.