Required Project Structure
==========================

It is very simple and follows convention. You need to structure your
logic design files in a directory with this structure to follow a
full-design flow.

The aim of this structure is that it allows a common interface to the
conventional design process of a photonic and electronic chip run. It
allows defining shared models, having source files, co-simulating,
creating analysis scripts in Python, allows common open-source tool
interfaces, and more.

This treats the selected design directories as parts of a python
package, whilst still enabling the standard microelectronics design flow
project structure.


Post Full-Flow Structure
------------------------

If you run the full flow, the design folder will look like:

::

   design_folder_name
       docs/
           README.md # Optional: Document your design
       design_folder_name/
           __init__.py
           analogue/
               __init__.py # Analog GDSFactory top-level layout files in here.
           components/
               __init__.py # Optional: Custom layout `gdsfactory` components in here.
               photonics/
                   __init__.py # `gdsfactory` components in here.
               analogue/
                   __init__.py # `gdsfactory` custom analogue layout in here.
               digital/
                   __init__.py # Any digital macros part of the OpenLane, `amaranth`, `cocotb` or other flows.
           io/
               pin_order.cfg # CUSTOM REQUIRED: OpenLane
           models/
               __init__.py # Optional: `gplugins` models in here.
               analogue/
                   __init__.py # `hdl21 SPICE` models too.
               frequency/
                   __init__.py # `sax` and related photonics models here.
               logic/
                   __init__.py # `digital` behavioural models here.
               physical/
                   __init__.py # `femwell`-generated models here on particular components.
               transient/
                   __init__.py # Photonic and specific behavioural analogue time-domain models in here.
           photonic/
               __init__.py # Photonic GDSFactory top-level layout files in here.
           scripts/
               openlane.sh # eg. generated by piel for automation with script based tools.
           sdc/
               design.sdc # Required: OpenLane SDC timing configuration files.
           src/
               source_files.v # Digital flow source files in here.
           runs/
               openlane_run_folder # AUTO GENERATED: OpenLane v1 digital layout outputs.
           tb/
               __init__.py
               Makefile # # AUTO GENERATED: cocotb in here
               test_design.py # # AUTO GENERATED: Required cocotb
               out/
                   output.csv # # AUTO GENERATED: Recommended: cocotb simulation output files go here.
           config.json # Optional, Required only for OpenLane V1
       .gitignore
       setup.py
       README.md

You need to configure the ``setup.py`` basic script so that this package
matches your design requirements.

You can install and interact with the corresponding project model and
some design files using:

.. code:: shell

   pip install -e .

In a tapeout, this design_folder could be treated as a standalone
package with version control via a ``.gitignore`` and local installation
via a packaged ``setup.py`` script. Documentation could be written
through ``Sphinx`` via ``python`` and ``verilog`` plugins.

Note that this structure is beneficial for a number of reasons. When
your design is imported, it can be used as a directory input to any
``piel`` function. As long as you have followed the structure of the
project, then you do not have to deal with filepaths, and you can
automate the design and simulation operations of the co-design tools.
This project structure enables compatibility in a design flow that uses
all the tools in ``piel``. This means you can do co-design of analogue,
digital and photonic chips in a single project without thinking of how
to structure your files or getting conflicts when you want to verify
with further tools down the line.

There are several ``piel`` functions that generate this project
structure for you so you can get cracking from the start. Check out the
examples.

Installing the cookiecutter project
------------------------------------

``piel`` provides a cookiecutter template of this project structure. It is really easy to use and the recommended way of creating a project. Run the following commands from the ``piel`` directory.

You can either install the ``piel`` development requirements to make sure you have the ``cookiecutter`` dependency installed. You can do either:

.. code-block:: shell

    pip install -r requirements_dev.txt --user
    # or
    pip install cookiecutter

.. code-block:: shell

    # In piel top directory
    cd environment
    cookiecutter piel_cookiecutter_template -o "<output_parent_directory_path>"

Then you just fill in the details.
