coriolis/documentation/content/pages/python-tutorial/Introduction.rst

.. -*- Mode: rst -*-


1. Introduction
===============

This tutorial is aimed at two goals :

* Presenting how to use Python scripts to control |Coriolis|.

* Make a basic introduction about the |Hurricane| database and its
  concepts.

While this tutorial is aimed at presenting the |Hurricane| database,
do not feel limited by it. You can use |Hurricane| objects as attributes
of |Python| objects or use |Python| containers to store them.
The only limitation is that you may not use |Hurricane| classes as base
classes in |Python|.

All the example scripts given in this tutorial con be found under: ::

    <CORIOLIS_INSTALL>/share/doc/coriolis2/examples/scripts/

Provided scripts:

=======================  ==============================================================
**Script**               **Feature**
=======================  ==============================================================
:cb:`coriolisLogo.py`    Draw a layout of the |Coriolis| logo
:cb:`diagonals.py`       Test the :cb:`Hurricane::Diagonal` class
:cb:`polygons.py`        Test the :cb:`Hurricane::Polygon` class
:cb:`rectilinear.py`     Test the :cb:`Hurricane::rectilinear` class
:cb:`invertor.py`        Procedural build of the layout of an invertor standard cell
:cb:`fulladder.py`       Procedural build of a small netlist along with it's manual
                         placement and the routing of one net (:cb:`"a"`)
:cb:`toolengines.py`     Build the netlist (only) of the full adder then call the
                         place and route engines
=======================  ==============================================================


1.1 Terminology
~~~~~~~~~~~~~~~

In the |Hurricane| database, the *logical* (netlist) and *physical* (layout)
views are fused. As the main goal of the database is to support place & route
tools, we usually starts with a *pure* netlist which is progessively enriched
to become a layout. Cell, in particular, is able to be in any intermediate
state. Many of our objects have self-explanatory names, but some
don't. Thus we summarize below the more important ones:

===============  =====================================================
**Class**        **Meaning**
===============  =====================================================
Cell_            The model. A Cell does not have terminals, only nets
                 flagged as *external*
Instance_        An instance of a model
Net_             A grouping of electrically connected components
Plug_            A terminal of an instance
RoutingPad_      A physical connexion (*pin*) to an instance
===============  =====================================================


1.2 Generalities
~~~~~~~~~~~~~~~~

The C++ API has been exported in Python as closely as possible. Meaning
that, save for a slight change in syntax, any code written in |Python|
could be easily transformed into C++ code. There is no specific documentation
written for the |Python| interface, you may directly use the C++ one.

Mostly:

* C++ namespaces are exported as |Python| modules.
* The *scope resolution operator* :fboxtt:`::` converts into :fboxtt:`.`.
* C++ blocks (between braces :fboxtt:`{}`) are replaced by indentations.
* In C++, names are managed through a dedicated ``Name`` class.
  It has not been exported to the |Python| interface, you only have
  to use ``string``.
* Coordinates are expressed in ``DbU`` which are ``long`` with a special
  semantic (see ??).
* All |Hurricane| objects implements the |Python| ``__str__()`` function,
  they print the result of the C++ method ``::getString()``.

In ``hurricane/Net.h`` header we have:

.. code-block:: c++

   namespace Hurricane {

      class Net : public Entity {
        public:
	  class Direction {
            public: enum Code { DirIn        = 0x0001
                              , DirOut       = 0x0002
                              , DirUndefined = 0x0000
                              , ConnTristate = 0x0100
                              , ConnWiredOr  = 0x0200
                              , UNDEFINED    = DirUndefined
                              , IN           = DirIn
                              , OUT          =         DirOut
                              , INOUT        = DirIn | DirOut
                              , TRISTATE     =         DirOut | ConnTristate
                              , TRANSCV      = DirIn | DirOut | ConnTristate
                              , WOR_OUT      =         DirOut | ConnWiredOr
                              , WOR_INOUT    = DirIn | DirOut | ConnWiredOr
                              , DirMask      = DirIn | DirOut | DirUndefined
                              };
            // [The rest of Class Direction]
         };
        public:
          static       Net*       create       ( Cell* , const Name& );
                       bool       isGlobal     ();
                       bool       isExternal   ();
                 const Direction& getDirection ();
                       void       setName      ( Name );
                       void       setGlobal    ( bool );
                       void       setExternal  ( bool );
                       void       setDirection ( const Direction& );
          // [The rest of Class Net]
      };

   }


So we can use it the following way in C++:
 
.. code-block:: c++

   #include "hurricane/Net.h"

   using namespace Hurricane;

   void  addNetToCell ( Cell* cell )
   {
      Net* net = Net::create( cell, "new_net" );
      net->setGlobal   ( false );
      net->setExternal ( true );
      net->setDirection( Net.Direction.IN );
      cout << "Created " << net << endl;
      return net;
   }


The equivalent |Python| code will be:

.. code-block:: Python

   from Hurricane import Net

   def addNetToCell ( cell ):
       net = Net.create( cell, "new_net" )
       net.setGlobal  ( False )
       net.setExternal( True )
       net.setDirection( Net.Direction.IN )
       print( "Created", net )
       return net


1.3 Various Kinds of Constructors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Regarding the memory allocation, the |Hurricane| database contains two kind of objects.

#. Objects that are linked to others in the database and whose creation or deletion
   implies coherency operations. This is the case for Net_ or Horizontal_.
   They must be created using the static :cb:`create()` method of their class
   and destroyed with their :cb:`destroy()` method.

   And, of course, they cannot be copied (the copy constructor has been disabled).

   .. code-block:: Python

      net = Net.create( cell, 'tmp' )  # Call the static Net.create() function.
                                       # Work with this net.
                                       # ...
      net.destroy()                    # Call the dynamic destroy() method.

#. Objects that are *standalone*, like Point_ or Box_, uses the usual construction
   methods. They also use the |Python| garbage collector mechanism and do not need
   to be explicitly deleted.

   .. code-block:: Python

      from Hurricane import DbU, Box

      def myfunc():
          bb = Box( DbU.fromLambda( 0.0)
                  , DbU.fromLambda( 0.0)
                  , DbU.fromLambda(15.0)
                  , DbU.fromLambda(50.0) )
          return                            # bb will be freed at that point.


1.4 Collections and Iterators
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Hurricane Collection_ behave like containers under |Python| and provide
support for the :cb:`iterator` protocol.

   .. code-block:: Python

      from Hurricane import Net, Horizontal

      def delAllHorizontals ( net ):
          horizontals = []
          for component in net.getComponents():
	      if isinstance(component,Horizontal):
                  horizontals.append( component )
          # Now we can remove the Horizontals.
          for horizontal in horizontals:
	      horizontal.destroy()

.. note:: **Never remove an element from a Collection_ while iterating over it**.
          You must save the to be removed elements in an auxiliary container
	  then remove them, like shown in the example above


1.5 Dynamically decorating data-base objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When writing algorithms directly in Python, it may come in handy to be
able to add attributes over the Hurricane data-base objects. As C++
objects exposed to the Python realm cannot natively do so (it would
means to be able to modify a C++ aobject attributes *at runtime*),
we add a special Property tasked with handling the extra Python
attributes. The syntax has been made as simple as possible.

.. code-block:: python

   from Hurricane import PythonAttributes
	  
   class MyAttribute ( object ):
       count = 0
   
       def __init__ ( self ):
           self.value = MyAttribute.count 
           print( '{} has been created'.format(self) )
           MyAttribute.count += 1
   
       def __del__ ( self ):
           print( '{} has been deleted'.format(self) )
   
       def __str__ ( self ):
           return '<MyAttribute {}>'.format(self.value)
   
   
   def demoAttributes ( cell ):
       PythonAttributes.enable( cell )
       cell.myAttribute0 = MyAttribute()
       cell.myAttribute1 = MyAttribute()
       print( 'cell.myAttribute0 =', cell.myAttribute0 )
       del cell.myAttribute0
       PythonAttributes.disable( cell )


Detailing the life cycle of Python attributes on a DBo_:

1. Enabling the addition of Python attribute on a DBo_:

   .. code-block:: python

      PythonAttributes.enable( cell )

2. Adding/removing properties on the DBo_:

   .. code-block:: python

      cell.myAttribute0 = MyAttribute()
      cell.myAttribute1 = MyAttribute()
      print( 'cell.myAttribute0 =', cell.myAttribute0 )
      del cell.myAttribute0

3. And finally disabling the use of Python attributes on the DBo.
   Any still attached Python attributes will be released.

   .. code-block:: python

      PythonAttributes.disable( cell )

   .. note:: 

      When the attributes of a DBo_ are released it does not automatically
      imply that they are removed. Their reference count is decreased, and
      if they are only referenced here, they will be deleted. But if other
      variables still holds reference onto them, they will stay allocateds.

4. There is no need to keep track of all the DBo_ that have Python
   attributes to disable them. One can directly call:

   .. code-block:: python

      PythonAttributes.disableAll()
	 

1.6 Adapting C++ : Overlay
~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes, the use of a wrapped C++ feature would be counter intuitive regarding
the |Python| feature. For those cases the :cb:`overlay` module provide an
adaptation of the C++ API for a more *Python-like* code. A typical example is
with the UpdateSession_ mechanism.

Using directly the C++ wrapper, we would write a code like this:

.. code-block:: python

   from Hurricane import UpdateSession, Net, Vertical
   from helpers   import l

   def editCell ( cell ):
       UpdateSession.open()
       net = Net.create( cell, "nwell" )
       Vertical.create( net, nwell, l(7.5), l(15.0), l(27.0), l(51.0) )
       # Continued cell's layout building.
       # ...
       UpdateSession.close()


But, using the :cb:`overlay` we got the more *pythonic* code:

.. code-block:: python

   from Hurricane       import Net, Vertical
   from helpers         import l
   from helpers.overlay import UpdateSession

   def editCell ( cell ):
       with UpdateSession():
           net = Net.create( cell, "nwell" )
           Vertical.create( net, nwell, l(7.5), l(15.0), l(27.0), l(51.0) )
           # Continued cell's layout building.
           # ...