Merge pull request #2836 from gdsfactory/improve_docs

improve docs

README.md

@@ -20,16 +20,17 @@
 
 
 Gdsfactory is a Python library for designing chips (Photonics, Analog, Quantum, MEMs, and more), 3D printed objects, and PCBs.
-Here, you can code your designs in Python or YAML, perform verification (DRC, simulation, and extraction), and enable automated testing in the lab to ensure your fabricated devices meet your specifications. As input you write python code, as an output GDSFactory creates CAD files (GDS, OASIS, STL, GERBER).
+Here, you can code your designs in Python or YAML, perform verification (DRC, simulation, and extraction), and enable automated testing in the lab to ensure your fabricated devices meet your specifications.
 
 
+As input you write python code, as an output GDSFactory creates CAD files (GDS, OASIS, STL, GERBER).
 
 ![cad](https://i.imgur.com/TWP80ez.png)
 
 Highlights:
 
 - More than 1M downloads
-- More than 50 Contributors
+- More than 60 Contributors
 - More than 10 PDKs available
 
 ![workflow](https://i.imgur.com/abvxJJw.png)
@@ -132,7 +133,7 @@ Hundreds of organisations are using gdsfactory. Some companies and organizations
 - It's free, as in freedom and in cost.
 - It's the most popular EDA tool with a growing community of users, developers, and extensions to other tools.
 
-Gdsfactory is really fast thanks a C++ library for manipulating GDSII objects. You will notice this when reading/writing big GDS files or doing large boolean operations.
+Gdsfactory is really fast thanks to KLayout C++ library for manipulating GDSII objects. You will notice this when reading/writing big GDS files or doing large boolean operations.
 
 | Benchmark      |  gdspy  | gdsfactory | Gain |
 | :------------- | :-----: | :--------: | :--: |

docs/_toc.yml

@@ -14,8 +14,7 @@ parts:
           - file: notebooks/_0_python
           - file: notebooks/_1_git
           - file: notebooks/_4_gdsfactory
-          - url: https://gdsfactory.github.io/gdsfactory-photonics-training/index.html
-            title: gdsfactory-training
+          - file: workflow
       - file: layout
         sections:
           - file: notebooks/00_geometry
@@ -42,7 +41,6 @@ parts:
           - file: notebooks/08_pdk_examples
           - file: notebooks/09_pdk_import
           - file: notebooks/12_config
-      - file: workflow
       - file: migration
         sections:
           - file: notebooks/21_migration_guide_7_8

docs/developer.md

@@ -31,13 +31,16 @@ import gdsfactory as gf
 gf.config.print_version_plugins()
 ```
 
-## Docker container
+## Tutorials
 
-As an alternative, you can use the pre-built Docker image from [github](https://github.com/gdsfactory/gdsfactory/pkgs/container/gdsfactory)
+You can [download](https://github.com/gdsfactory/gdsfactory/archive/refs/heads/main.zip) the jupyter notebooks tutorial and open them with VSCode.
 
-For instance, VS Code supports development inside a container. See [Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers) for details.
+We recommend running the tutorials with VSCode but you can also install and run them with jupyterlab.
+```
+pip install jupyterlab
+```
 
-## Installation for developers
+## Installation for contributors
 
 As a contributor, if you are on windows you need to download [Git](https://git-scm.com/download/win) and optionally [GitHub Desktop](https://desktop.github.com/).
 
@@ -46,8 +49,8 @@ Then you need to fork the [GitHub repository](https://github.com/gdsfactory/gdsf
 The following lines will:
 
 - clone your gdsfactory fork (make sure you change `YourUserName` with your GitHub user name)
-- download the GDS golden data for running GDS regressions from a separate [repo](https://github.com/gdsfactory/gdsfactory-test-data/tree/test-data)
-- install gdsfactory locally on your computer in `-e` edit mode.
+- download the GDS reference files for running GDS regressions from a separate [repo](https://github.com/gdsfactory/gdsfactory-test-data/tree/test-data)
+- install gdsfactory on your computer in `-e` edit mode.
 - install pre-commit hooks for making sure your code syntax and style matches some basic rules.
 
 ```
@@ -58,12 +61,6 @@ pip install -e .[dev]
 pre-commit install
 ```
 
-**Note**:
-- If you need to run the notebooks and you are not using VSCode or Anaconda, then you need to install [jupyter lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html)
-```
-pip install jupyterlab
-```
-
 
 ## Style
 
@@ -137,7 +134,6 @@ What do we test?
 
 - Geometry polygons, layers and cell names.
 - Component Settings.
-- Port positions and ensure they are on grid.
 
 ```python
 import pytest
@@ -174,8 +170,9 @@ def test_settings(component_name: str, data_regression: DataRegressionFixture) -
 
 For questions join the [![Join the chat at https://gitter.im/gdsfactory-dev/community](https://badges.gitter.im/gdsfactory-dev/community.svg)](https://gitter.im/gdsfactory-dev/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) with [element.io](https://element.io/download) or use GitHub issues or discussions.
 
-## Running notebooks
 
-You can find the tutorial jupyter notebooks in `notebooks` and open them with VSCode.
+## Docker container
 
-You can use [VSCode gdsfactory extension](https://marketplace.visualstudio.com/items?itemName=gdsfactory.gdsfactory) to open and run the notebooks.
+As an alternative, you can use the pre-built Docker image from [github](https://github.com/gdsfactory/gdsfactory/pkgs/container/gdsfactory)
+
+For instance, VS Code supports development inside a container. See [Developing inside a Container](https://code.visualstudio.com/docs/devcontainers/containers) for details.

gdsfactory/component.py

@@ -986,6 +986,8 @@ def plot(
 
         from gdsfactory.pdk import get_layer_views
 
+        self.insert_vinsts()
+
         lyp_path = GDSDIR_TEMP / "layer_properties.lyp"
         layer_views = get_layer_views()
         layer_views.to_lyp(filepath=lyp_path)
@@ -996,6 +998,7 @@ def plot(
         cell_view = layout_view.cellview(cell_view_index)
         layout = cell_view.layout()
         layout.assign(kf.kcl.layout)
+
         cell_view.cell = layout.cell(self.name)
 
         layout_view.max_hier()

gdsfactory/samples/01_component_pcell.py

@@ -53,17 +53,17 @@ def straight_wide(
     # only this one has some geometry inside it.
     #
     # Let's create two of these Components by calling the straight_wide() function
-    WG1 = straight_wide(length=10, width=1, layer=(1, 0))
-    WG2 = straight_wide(length=12, width=2, layer=(2, 0))
+    _wg1 = straight_wide(length=10, width=1, layer=(1, 0))
+    _wg2 = straight_wide(length=12, width=2, layer=(2, 0))
 
     # Now we've made two straights Component WG1 and WG2, and we have a blank
     # Component c. We can add references from the devices WG1 and WG2 to our blank
     # Component by using the add_ref() function.
     # After adding WG1, we see that the add_ref() function returns a handle to our
     # reference, which we will label with lowercase letters wg1 and wg2.  This
     # handle will be useful later when we want to move wg1 and wg2 around in c.
-    wg1 = c.add_ref(WG1)  # Using the function add_ref()
-    wg2 = c << WG2  # Using the << operator which is identical to add_ref()
+    wg1 = c.add_ref(_wg1)  # Using the function add_ref()
+    wg2 = c << _wg2  # Using the << operator which is identical to add_ref()
 
     # Alternatively, we can do this all on one line
     wg3 = c.add_ref(straight_wide(length=14, width=3, layer=(3, 0)))

gdsfactory/samples/03_move.py

@@ -20,5 +20,5 @@
     # wg2.dmove([10, 1])  # Shift the second straight we created over by dx = 10, dy = 4
     # wg2.drotate(45)  # Rotate straight by 45 degrees around (0,0)
     # wg2.drotate(45, center=[5, 0])  # Rotate straight by 45 degrees around (5, 0)
-    # wg2.dmirror(p1=[1, 1], p2=[1, 3])  # Reflects wg across the line formed by p1 and p2
+    # wg2.dmirror(p1=gf.kdb.DPoint(1, 0), p2=gf.kdb.DPoint(1, 1))  # Reflects wg across the line formed by p1 and p2
     c.show()

gdsfactory/samples/05_remove_layers.py

@@ -8,7 +8,7 @@
 
 @gf.cell
 def remove_layers() -> Component:
-    c = gf.Component("test_remove_layers")
+    c = gf.Component()
 
     c.add_ref(gf.components.rectangle(size=(10, 1), layer=(1, 0)))
     c.add_ref(gf.components.rectangle(size=(10, 2), layer=(3, 0)))

gdsfactory/samples/06_remapping_layers.py

@@ -23,7 +23,8 @@ def remap_layers() -> Component:
 
 
 def test_remap_layers():
-    assert remap_layers()
+    c = remap_layers()
+    assert c.layers == [(2, 0)]
 
 
 if __name__ == "__main__":

gdsfactory/samples/07_flattening_device.py

@@ -3,12 +3,7 @@
 Sometimes you want to remove cell structure from a Component while keeping all
 of the shapes/polygons intact and in place.
 
-The Component.flatten() method returns a new flatten Component with all the
-polygons inside the Component, and removes all the underlying references.
-Also, if you specify the `single_layer` argument it will move all of the
-polygons to that single layer.
-
-FIXME! flatten gives a seg fault
+The Component.flatten() method flattens current Component by copying all polygons from the underlying references.
 
 """
 

gdsfactory/samples/08_grid.py

@@ -0,0 +1,14 @@
+"""Group components in a cell using grid."""
+
+if __name__ == "__main__":
+    import gdsfactory as gf
+
+    t1 = gf.components.text("1")
+    t2 = gf.components.text("2")
+    t3 = gf.components.text("3")
+    t4 = gf.components.text("4")
+    t5 = gf.components.text("5")
+    t6 = gf.components.text("6")
+
+    c = gf.grid([t1, t2, t3, t4, t5, t6])
+    c.show()

gdsfactory/samples/09_pack.py

@@ -0,0 +1,14 @@
+"""Group components in a cell using pack."""
+
+if __name__ == "__main__":
+    import gdsfactory as gf
+
+    t1 = gf.components.text("1")
+    t2 = gf.components.text("2")
+    t3 = gf.components.text("3")
+    t4 = gf.components.text("4")
+    t5 = gf.components.text("5")
+    t6 = gf.components.text("6")
+
+    c = gf.pack([t1, t2, t3, t4, t5, t6])[0]
+    c.show()

gdsfactory/samples/12_component_refs.py

@@ -62,27 +62,31 @@ def crossing_arm(
     return c
 
 
-@gf.cell  # This decorator will generate a good name for the component
-def crossing() -> Component:
-    c = gf.Component()
-    arm = crossing_arm()
-
-    # Create two arm references. One has a 90Deg rotation
-    arm_h = arm.ref(position=(0, 0))
-    arm_v = arm.ref(position=(0, 0), rotation=90)
+@gf.cell
+def crossing(
+    arm=crossing_arm,
+    cross_section="strip",
+) -> Component:
+    """Waveguide crossing.
 
-    # Add each arm to the component
-    # Also add the ports
+    Args:
+        arm: arm spec.
+        cross_section: spec.
+    """
+    x = gf.get_cross_section(cross_section)
+    c = Component()
+    arm = gf.get_component(arm)
     port_id = 0
-    for a in [arm_h, arm_v]:
-        c.add(a)
-        for p in a.ports.values():
-            # Here we don't care too much about the name we give to the ports
-            # since they will be renamed. We just want the names to be unique
-            c.add_port(name=f"{port_id}", port=p)
+    for rotation in [0, 90]:
+        ref = c << arm
+        ref.drotate(rotation)
+        for p in ref.ports:
+            c.add_port(name=port_id, port=p)
             port_id += 1
 
     c.auto_rename_ports()
+    x.add_bbox(c)
+    c.flatten()
     return c
 
 

gdsfactory/samples/14_component_connectivity.py

@@ -15,7 +15,6 @@ def ring_single_sample(
     straight: ComponentSpec = "straight",
     bend: ComponentSpec = "bend_euler",
     cross_section: CrossSectionSpec = "strip",
-    **kwargs,
 ) -> Component:
     """Single bus ring made of a ring coupler.
 
@@ -31,7 +30,6 @@ def ring_single_sample(
         straight: straight function.
         bend: 90 degrees bend function.
         cross_section: spec.
-        kwargs: cross_section settings.
 
 
     .. code::
@@ -47,20 +45,22 @@ def ring_single_sample(
     """
     gap = gf.snap.snap_to_grid(gap, grid_factor=2)
 
-    xs = gf.get_cross_section(cross_section, **kwargs)
-
     coupler_ring_component = gf.get_component(
         coupler_ring,
         bend=bend,
         gap=gap,
         radius=radius,
         length_x=length_x,
-        cross_section=xs,
+        cross_section=cross_section,
+    )
+    straight_side = gf.get_component(
+        straight, length=length_y, cross_section=cross_section
+    )
+    straight_top = gf.get_component(
+        straight, length=length_x, cross_section=cross_section
     )
-    straight_side = gf.get_component(straight, length=length_y, cross_section=xs)
-    straight_top = gf.get_component(straight, length=length_x, cross_section=xs)
 
-    bend = gf.get_component(bend, radius=radius, cross_section=xs)
+    bend = gf.get_component(bend, radius=radius, cross_section=cross_section)
 
     c = Component()
     cb = c << coupler_ring_component
@@ -78,7 +78,7 @@ def ring_single_sample(
     br.connect(port="o2", other=wt.ports["o1"])
     wr.connect(port="o1", other=br.ports["o1"])
 
-    c.add_port("o2", port=cb.ports["o2"])
+    c.add_port("o2", port=cb.ports["o4"])
     c.add_port("o1", port=cb.ports["o1"])
     return c
 
@@ -88,6 +88,6 @@ def test_ring_single_sample() -> None:
 
 
 if __name__ == "__main__":
-    c = ring_single_sample(width=2, gap=1, layer=(2, 0))
-    print(c.ports)
+    c = ring_single_sample()
+    c.pprint_ports()
     c.show()

gdsfactory/samples/17_ports.py

@@ -25,14 +25,12 @@ def component_with_port(
         length: in um.
         width: waveguide width in um.
         layer: layer.
-
     """
-    y = width
-    x = length
-
     c = gf.Component()
-    c.add_polygon([(0, 0), (x, 0), (x, y), (0, y)], layer=layer)
-    c.add_port(name="o1", center=(0, y / 2), width=y, orientation=180, layer=layer)
+    c.add_polygon([(0, 0), (length, 0), (length, width), (0, width)], layer=layer)
+    c.add_port(
+        name="o1", center=(0, width / 2), width=width, orientation=180, layer=layer
+    )
     assert len(c.ports) == 1
     return c
 

gdsfactory/samples/22_add_pads.py

@@ -3,20 +3,10 @@
 from __future__ import annotations
 
 import gdsfactory as gf
-from gdsfactory.samples.big_device import big_device
+from gdsfactory.samples.big_device_electrical import big_device
 
 if __name__ == "__main__":
     w = h = 18 * 50
-    cross_section = "metal3"
-    c = big_device(nports=10, cross_section=cross_section)
-    c = gf.routing.add_fiber_array(
-        component=c,
-        cross_section=cross_section,
-        grating_coupler="pad",
-        gc_port_name="e1",
-        get_input_labels_function=None,
-        with_loopback=False,
-        straight_separation=15,
-        # bend='wire_corner'
-    )
+    c = big_device()
+    c = gf.routing.add_pads_top(c, fanout_length=500)
     c.show()