From 837f42b9edc7d1f4b62c2b78318273030107e3b1 Mon Sep 17 00:00:00 2001 From: jan Date: Fri, 13 Oct 2023 00:50:01 -0700 Subject: [PATCH] more design pattern docs --- README.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9a734c8..e23059d 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Each `Pattern` can contain `Ref`s pointing at other patterns, `Shape`s, and `Lab - `annotation`: Additional metadata. OASIS or GDS "property". -## Design choices & shorthand +## Syntax, shorthand, and design patterns Most syntax and behavior should follow normal python conventions. There are a few exceptions, either meant to catch common mistakes or to provide a shorthand for common operations: @@ -94,6 +94,7 @@ library['mycell'] = pattern0 library['mycell'] = pattern1 # Error! 'mycell' already exists and can't be overwritten del library['mycell'] # We can explicitly delete it library['mycell'] = pattern1 # And now it's ok to assign a new value +library.delete('mycell') # This also deletes all refs pointing to 'mycell' by default ``` ### Insert a newly-made hierarchical pattern (with children) into a layout @@ -112,7 +113,13 @@ new_name = library << tree # Add `tree` into `library` and return the top my_pattern.ref(new_name, ...) # instantiate the cell # In practice, you may do lots of -top_pattern.ref(lib << make_tree(...), ...) +my_pattern.ref(lib << make_tree(...), ...) +``` + +We can also use this shorthand to quickly add and reference a single flat (as yet un-named) pattern: +```python3 +anonymous_pattern = Pattern(...) +my_pattern.ref(lib << {'_tentative_name': anonymous_pattern}, ...) ``` ### Place a hierarchical pattern into a layout, preserving its port info @@ -131,7 +138,7 @@ my_pattern.place(abstract, ...) # or my_pattern.place(library << make_tree(...), ...) -``` + ### Quickly add geometry, labels, or refs: The long form for adding elements can be overly verbose: @@ -167,6 +174,22 @@ pattern['input'] = Port(...) # Error! has_input = ('input' in pattern) # Error! ``` +### Building patterns +```python3 +library = Library(...) +my_pattern_name, my_pattern = library.mkpat(some_name_generator()) +... +def _make_my_subpattern() -> str: + # This function can draw from the outer scope (e.g. `library`) but will not pollute the outer scope + # (e.g. the variable `subpattern` will not be accessible from outside the function; you must load it + # from within `library`). + subpattern_name, subpattern = library.mkpat(...) + subpattern.rect(...) + ... + return subpattern_name +my_pattern.ref(_make_my_subpattern(), offset=..., ...) +``` + ## TODO