initiation of mxpic

README.md

@@ -1,3 +1,78 @@
-# mxpic_forge
+# <span style="color: #6decff;">mxPIC Quick-Reference Style Guide</span>
 
-Private repository of maxwell-PIC design library
+Welcome to the collaboration of the repository of **mxPIC** program. This repository is aimed for a self-designed PDK that based on ***nazca***, ***gdstk*** and other libraries for the functional build up of photonic integrated circuits (PIC).
+
+This is the fast-track guide to contributing to **mxPIC**. Adherence to these rules is mandatory to pass the automated CI/CD pipeline.
+
+### <span style="color: #ff57c7;">0. Installation dependencies</span>
+- python 3.10.1
+- nazca 0.6.1
+- numpy 1.12.0
+- pandas 0.12.0
+- 
+
+
+## <span style="color: #ff57c7;">1. Annotation & Documentation</span>
+We strictly use **Type Hints** (PEP 484) and **NumPy-Style Docstrings**.
+
+* <span style="color: #d2a8ff;">**Rule:**</span> Every function MUST have its parameter types and return type explicitly declared.
+* <span style="color: #d2a8ff;">**Rule:**</span> Use `"""` for docstrings, broken into `Parameters` and `Returns` sections.
+
+```diff
+- class Waveguide(length, width):
+-     """Builds a Mach-Zehnder."""
+-     pass
+
++ class Waveguide(length: float, width: float = 0.5) -> nazca.Cell:
++     """
++     Generates an MZM layout.
++     
++     Parameters
++     ----------
++     length : float
++         Arm length in microns.
++     width : float, optional
++         Waveguide width in microns.
++         
++     Returns
++     -------
++     list[tuple]
++         Polygon vertices.
++     """
++     pass
+```
+
+---
+## <span style="color: #ff57c7;">2. Class mangement of devices</span>
+The devices are divided into four major types, which is <span style="color: #d2a8ff;">**primitives, composite, electronics, and others**</span>. All photonic and electronic devices are built within the for types.   
+In the definitial of classes, compulsary keys are required, including **name** , **show_pins** , all defaults are None.  
+All classes are cored at the **cell** class of **nazca**, which is generated through an internal method named "generate_gds" 
+
+``` python
+class GratingCoupler():
+    def __init__(self,name:"str"=None,....,show_pins:bool=None)
+        ...
+        ...
+
+        self.cell = self.generate_gds() ## the generation of cell
+
+    def generate_gds(self) -> nazca.Cell:
+        """ Creating the cell of the device """
+        with nd.Cell(name=self.name,inst) as C:
+        
+        return C 
+```
+---
+## <span style="color: #ff57c7;">3. Port information formatting</span>
+The basic routing algorthium is based the information between nodes, which is the **pin** attribute inside each file. The formatting of **pin** name will be important.  
+
+**<span style="color: #bf0000;">Note</span>**: The pin name should only be related to different functionalities instead of material, layer or shaped. Say, the pin name of a *silicon directional coupler* is the same as a *silicon nitride directional coupler*.
+
+ |Catagory| Prefix | name | index | expample | device instance
+|---|---|---|---|---|---|
+| Optical| opt_   | a    | 1~x   | opt_a1   | direction_coupler
+| Optical (Sinlge IO to waveguide)| opt_   | a    | 1~x   | opt_a1   |grating_coupler
+| Electrical| ele_   | a    | 1~x   | ele_a1   | heater/resistor
+| PN diodes| ele_   | ka/an    | 1~x   | ele_an1   | modulator/p-i-n waveuigde
+| Transistors (BJT)| ele_   | ba/em/cl    | 1~x   | ele_cl1   | BJT
+| Transistors (MOS)| ele_   | gt/su/dr    | 1~x   | ele_gt1   | MOSFET