masque/examples/tutorial/README.md

masque Tutorial
===============

These examples are meant to be read roughly in order.

- Start with `basic_shapes.py` for the core `Pattern` / GDS concepts.
- Then read `devices.py` and `library.py` for hierarchical composition and libraries.
- Read the `pather*` tutorials separately when you want routing helpers.

Contents
--------

- [basic_shapes](basic_shapes.py):
    * Draw basic geometry
    * Export to GDS
- [devices](devices.py)
    * Build hierarchical photonic-crystal example devices
    * Reference other patterns
    * Add ports to a pattern
    * Use `Builder` to snap ports together into a circuit
    * Check for dangling references
- [library](library.py)
    * Continue from `devices.py` using a lazy library
    * Create a `LazyLibrary`, which loads / generates patterns only when they are first used
    * Explore alternate ways of specifying a pattern for `.plug()` and `.place()`
    * Design a pattern which is meant to plug into an existing pattern (via `.interface()`)
- [pather](pather.py)
    * Use `Pather` to route individual wires and wire bundles
    * Use `AutoTool` to generate paths
    * Use `AutoTool` to automatically transition between path types
- [renderpather](renderpather.py)
    * Use `RenderPather` and `PathTool` to build a layout similar to the one in [pather](pather.py),
        but using `Path` shapes instead of `Polygon`s.
- [port_pather](port_pather.py)
    * Use `PortPather` and the `.at()` syntax for more concise routing
    * Advanced port manipulation and connections


Additionally, [pcgen](pcgen.py) is a utility module used by `devices.py` for generating
photonic-crystal lattices; it is support code rather than a step-by-step tutorial.


Running
-------

Run from inside the examples directory:
```bash
cd examples/tutorial
python3 basic_shapes.py
klayout -e basic_shapes.gds
```

Some tutorials depend on outputs from earlier ones. In particular, `library.py`
expects `circuit.gds`, which is generated by `devices.py`.