Instantiation of geometries from GDSII files

[HomerReid]

Initial stab at defining geometries from GDSII files.

• Update configure.ac to look for libGDSII, distributed for now as a separate standalone package.

• Add new source file libmeepgeom/GDSIIgeom.cpp implementing simple routines for defining meep geometries from GDSII files. If compiling without libGDSII, these routines all default to stubs that exit with error messages, like what happens in src/mpb.cpp if compiled without MPB.

• Updated libmeepgeom/bend-flux-ll.cpp code to allow optional definition of the bend-flux geometry from a GDSII file, specified on the command line with the --GDSIIFile option.

Instantiating the bend-flux geometry from a GDSII file

The libGDSII source distribution comes with a GDSII geometry file called bend-flux.gds. (After a successful libGDSII installation to prefix $(prefix), this file will be installed on your system in the directory $(prefix)/share/libGDSII/examples/bend-flux/). Here's a screenshot of what this file looks like in the wonderful open-source layout editor KLayout:

Note that this simple geometry contains multiple layers, with just one polygon per layer:

• Layer 0: Geometry (computational cell)
• Layer 1: Straight waveguide structure
• Layer 2: Bent waveguide structure
• Layer 3: Volume for source region
• Layer 4: Volume for reflected flux region
• Layer 5: Volume for transmitted flux region (straight waveguide case)
• Layer 6: Volume for transmitted flux region (bent waveguide case)

The idea is to build up the meep geometry one element at a time by referencing individual layers in the GDSII file. The new source file libmeepgeom/GDSIIgeom.cpp includes several routines to facilitate this:

• Define the extents of the computational cell from a polygon on a given GDSII layer:
  • grid_volume set_geometry_from_GDSII(double resolution, char *GDSIIFile, int GDSIILayer, double zsize=0.0);

• Create a prism by specifying a material, a GDSII layer containing a polygon, and z coordinates of the prism floor and ceiling:
  • geometric_object get_GDSII_prism(material_type material, char *GDSIIFile, int GDSIILayer, double zmin=0, double zmax=0);

• Define a meep::volume from a polygon on a given layer in the GDSIIFile:
  • volume get_GDSII_volume(char *GDSIIFile, int GDSIILayer, double zsize=0);

The updated libmeepgeom/bend-flux-ll.cpp uses these primitives to define the bend-flux geometry (with either the straight or bent waveguides) and to define meep::volumes that are later used to add sources and flux regions to the simulation:

/***************************************************************/
/* define geometry from GDSII file *****************************/
/***************************************************************/
#define GEOM_LAYER           0   // hard-coded indices of GDSII layers
#define STRAIGHT_WVG_LAYER   1   //  on which various geometric entities are defined
#define BENT_WVG_LAYER       2
#define SOURCE_LAYER         3
#define RFLUX_LAYER          4
#define STRAIGHT_TFLUX_LAYER 5
#define BENT_TFLUX_LAYER     6

structure create_structure_from_GDSII(char *GDSIIFile, bool no_bend,
                                      volume &vsrc, volume &vrefl, volume &vtrans)
{
  // set computational cell
  double dpml       = 1.0;
  double resolution = 10.0;
  grid_volume gv=meep_geom::set_geometry_from_GDSII(resolution, GDSIIFile, GEOM_LAYER);
  structure the_structure(gv, dummy_eps, pml(dpml));

  // define waveguide
  geometric_object objects[1];
  meep_geom::material_type dielectric = meep_geom::make_dielectric(12.0);
  int GDSIILayer = (no_bend ? STRAIGHT_WVG_LAYER : BENT_WVG_LAYER);
  objects[0] = meep_geom::get_GDSII_prism(dielectric, GDSIIFile, GDSIILayer);
  geometric_object_list g={ 1, objects };
  meep_geom::set_materials_from_geometry(&the_structure, g);

  // define volumes for source and flux-monitor regions
  vsrc   = meep_geom::get_GDSII_volume(GDSIIFile, SOURCE_LAYER);
  vrefl  = meep_geom::get_GDSII_volume(GDSIIFile, RFLUX_LAYER);
  vtrans = meep_geom::get_GDSII_volume(GDSIIFile, (no_bend ? STRAIGHT_TFLUX_LAYER : BENT_T

  return the_structure;
}

I have verified that running bend-flux-ll with --HDF5File bend-flux.gds yields the same results as running with --use-prism, which creates the prism and other geometric elements by hand.

Specifying polygons by text instead of (or in addition to) layer

In the example above, the GDSII file contains just one polygon on each layer, and we specify which polygon we want by simply specifying the index of the layer. More generally, users may want to select one of multiple polygons defined on the same layer. libGDSII already includes a mechanism to do this: Tag the polygon you want by adding a GDSII text string with reference point lying inside the polygon (for example, in the above screenshot, the computational-cell polygon contains the string Geometry). Then instead of the above you could say e.g.

  grid_volume gv=meep_geom::set_geometry_from_GDSII(resolution, GDSIIFile, "Geometry")

This way multiple polygons can coexist on a single layer and we specify which one we want by tagging with appropriate labels.

[stevengj]

char* arguments should be const char* if the string isn't modified (otherwise C++ doesn't like you passing literal strings these days)

[stevengj]

Needs a rebase — it seems like this PR has commits from the zero-thickness DFT slice branch?

[stevengj]

Needs another rebase for conflict resolution.

[HomerReid]

I deleted my entire repository, re-cloned your master branch, and merged the GDSII updates into that. I hope this addressed the issues. If not, maybe you could recommend a git command or two that would clean things up?

[stevengj]

Looks good, thanks.

[ChristopherHogan]

@HomerReid: Here's the workflow I use that seems to prevent these types of issues.

In my local fork, I have two remotes:

1. upstream, which points to the main meep repo.
2. origin, which points to my forked meep repo.

$ git remote -v
origin	git@github.com:ChristopherHogan/meep.git (fetch)
origin	git@github.com:ChristopherHogan/meep.git (push)
upstream	https://github.com/stevengj/meep.git (fetch)
upstream	https://github.com/stevengj/meep.git (push)

Whenever there are new changes in the main repo, I sync them with my fork as follows:

git checkout master

# Fetch the changes from the main repo
git fetch upstream

# Merge the upstream changes to master into my local master branch
git merge upstream/master

# Push those changes to my forked remote master
git push origin master

That's the only kind of merge I ever do. If a PR has a merge conflict, or if I need a feature from master that's not on my local branch, then I rebase my working branch on the HEAD of master.

# After updating master as above
git checkout branch_I_am_working_on
git rebase master
git push -f origin branch_I_am_working_on

This keeps all my commits nice and clean with no extraneous changes. The only time this doesn't work is when I am working on a branch that's based off another branch that hasn't been merged yet. For example, I have feature a ready in branch A and a PR is open. Now I want to add feature b in branch B, but I have to create B from A instead of from master. So I do

git checkout A
git checkout -b B

Now I have something like this

---------master
              \
               -----------A
                             \
                              ----------B

Now let's say A is merged. I go through the process above to sync my fork with upstream, and we have this.

------------------------A------master
              \
               -----------A
                             \
                              ----------B

Now I need to rebase B onto master. This can lead to a long and painful conflict resolution process (I think because the PRs are all squashed and merged). To get around that, I create a new branch off master and cherry pick the commits I want.

git checkout master
git checkout -b new_B
git cherry-pick sha_for_commits_on_B
git push origin new_B

Now I can delete A and B and I can open a PR with my repo in this state

-------A------master
                  \
                  ----new_B

[stevengj]

A simpler alternative is to not maintain a forked master branch at all. Just have (1) master => stevengj/meep and (2) feature branches (one per PR).

Then the workflow is to periodically

git checkout master
git pull origin master # sync master with upstream
git checkout myfeature
git rebase master # rebase myfeature onto master
git push me +myfeature  # forced push to your myfeature branch

When you start working on a new PR, do:

git checkout master
git pull origin master # sync master with upstream before starting
git checkout -b newfeature # create and checkout new branch
...add commits...
git push me newfeature

Here, origin is a remote alias for stevengj/meep and me is a remote alias for your fork on github. Of course, your fork has a master branch too, but you can just ignore it completely — there's no need to ever push to it.

[HomerReid]

@ChristopherHogan, thanks a lot for taking the time to put together a detailed tutorial. I'm long overdue to modernize my protocols. I will study these approaches and finally learn how to do it right.