TheSyDeKick_tutorial.tex

\documentclass{sdkslides} 
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{amssymb,amsmath}
\usepackage{url}
\usepackage{lastpage}
\usepackage{epstopdf}
%\usepackage[pdfpagemode=None,colorlinks=true,urlcolor=red, linkcolor=black,citecolor=black,pdfstartview=FitH]{hyperref}
\usepackage{mdframed}
\usepackage{caption}
\usepackage{apacite}
\usepackage{listings}
\usepackage{adjustbox}
\usepackage[nomessages]{fp}

\usepackage{tikz}
\usetikzlibrary{positioning,shapes,shadows,arrows}
\tikzset{
  every overlay node/.style={
    %draw=black,fill=white,rounded corners,
    anchor=north west, inner sep=0pt,
  },
  thick/.style=      {line width=0.3mm},
}
\def\tikzoverlay{
   \tikz[remember picture, overlay]\node[every overlay node]
}%


%%%%%%%%%%%%%%%The functions are collected here %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\input{./aaltobeamerfunctions.tex}

%%%% To insert lecture date
%\newcommand{\lectdate}{19.11.2015}
\newcommand{\lectdate}{\today}
\newcommand{\slidetitle}{TheSyDeKick tutorial}
%%%%

\title{\slidetitle}

\author[Marko Kosunen]{Marko Kosunen}
\institute[MNT]{Department of Micro and Nanosciences\\
Aalto University, School of Electrical Engineering\\marko.kosunen@aalto.fi}

\sdkfootertext{Analog macro releases}{\lectdate}{\arabic{page}/\pageref{LastPage}\ }

\date{\lectdate}


\begin{document}

\lstset{language=python,
    basicstyle=\small,
    stringstyle=\ttfamily
} 

\newcommand{\setlines}[2][1]{
    \FPeval{\firstline}{clip(#1)}
    \FPeval{\lines}{clip(#2)}
    \FPeval{\lastline}{clip(\firstline+\lines-1)}
}
\newcommand{\nextlines}[1][\lines]{
    \FPeval{\firstline}{clip(\lastline+1)}
    \FPeval{\lines}{clip(#1)}
    \FPeval{\lastline}{clip(\firstline+\lines-1)}
}

\newcommand{\codeclip}[2][python]{
    \FPeval{\scale}{min(clip(0.44/25*\lines),0.44)}
    \begin{adjustbox}{height=\scale\textheight , keepaspectratio}
    \lstinputlisting[
        frame=L, 
        numbers=left, 
        showlines=true
        language=#1, 
        firstline=\firstline, 
        lastline=\lastline, 
        firstnumber=\firstline]{#2}
    \end{adjustbox}
}
\newcommand{\setol}[1][0]{
    \FPeval{\oln}{clip(#1)}
}
\newcommand{\incol}{
    \FPeval{\oln}{clip(\oln+1)}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Generates the titleframe
\sdktitleframe
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%% CONTENTS %%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Outline}
\section*{\sectionname}
\begin{frame}[c]
    \frametitle{\sectionname}
    \tableofcontents
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Prerequisites}
\section*{\sectionname}
\begin{frame}[t]
    \frametitle{\sectionname}
    \begin{itemize}
        \item Project template is available at
            \emph{https://github.com/TheSystemDevelopmentKit/thesdk\_template}.
        \item If you have access to any valid, up-to-date clone of the
            template, you can use that as well.
    \end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[TheSyDeKick project structure]


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Directory structures of TheSyDeKick project}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname}
    \begin{itemize}
            \item All TheSyDeKick projects look the same
        \end{itemize}
    \adjustbox{height=0.4\textheight}{%
\begin{lstlisting}
TheSyDeKick_project
    init_submodules.sh     
    configure              
    sourceme.csh           
    pip3userinstall.sh   
    Entities                  <- All design modules are ``entities''
        thesdk                <- The SyDeKick core entity
        rtl                   <- rtl entity for rtl simulations
        spice                 <- spice entity for analog simulations
        thesdk_helpers
            shell
                initentity.sh <- Shell script for creating new entities
        inverter_tests
        inverter_testbench
        inverter              <- Example entity inverter. All entities look the same
            init_submodules.sh
            configure
            doc
            sv
            spice
            vhdl
            simulations      <- Temporary directory for simulation results
                rtlsim
            inverter
                __init__.py   <- Python description of the entity
                controller.py <- Additional entity related Python
\end{lstlisting}
}
\end{frame}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{TheSyDeKick project structure}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
            \item All TheSyDeKick projects look the same
            \item TheSydeKick entities are git submodules initiated in the
                \emph{init\_submodules.sh}
            \item TheSydeKick entitities are transferable to any
                TheSyDeKick project.
            \item TheSydeKick entities are transferable to any
                TheSyDeKick project.
            \item TheSydeKick entities do not run stand-alone. They need the
                project.
            \item Obey the structure. It is not yours to change.
            \item New entities are initiated with
                \emph{thesdk\_helpers/shell/initentity.sh}
        \end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[Testing the environment]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Testing the environment}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
            \item To test TheSyDeKick installation, do the following
        \end{itemize}
%    \adjustbox{height=0.4\textheight}{%
\begin{lstlisting}
cd TheSyDeKick_project
./init_submodules.sh     
./configure              
source sourceme.csh           
pip3userinstall.sh   
\end{lstlisting}
%}
\begin{itemize}
    \item Then \textbf{check the Python versions from Thesdk.config}. Release
        v1.10 is tested with Python 3.10.
    \item Thesdk.config is created and will be overwritten by the configure
        script. Usually no need to re-run it. 
\end{itemize}

\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Testing the environment}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
            \item Then we test the simulation execution
        \end{itemize}
%    \adjustbox{height=0.4\textheight}{%
\begin{lstlisting}
cd Entities/inverter     
./configure              
python3 inverter/__init__.py  
\end{lstlisting}
%}
\begin{itemize}
    \item Simulation of an inverter modeled in Python, verilog (icarus), vhdl
        (ghdl) and ngspice is executed. 
    \item Press \emph{Return} to close the figures
    \item This is the elementary way of running simulations, i.e.you provide
        the scriptfile to python shell.
    \item The ''production way'' is 
\end{itemize}
\begin{lstlisting}
./configure  && make sim          
\end{lstlisting}
\begin{itemize}
    \item Try it. If it works, you are good to go for the next step.
\end{itemize}
\end{frame}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[Creating a new Entity]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Creating a new Entity}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item All the Entities are eventually git submodules.
        \item Go through the following steps and try to think what happens in
            in term of version control
        \item The <my\_entity> refers to the entity you are creating. \emph{it should be
            replaced with your entity name}
        \item By default, the remote points to GitHub, and you do not have
            push permissions there.
        \end{itemize}
\adjustbox{height=0.21\textheight}{%
\begin{lstlisting}
cd entities
./thesdk_helpers/shell/initentity -h
./thesdk_helpers/shell/initentity <my_entity>
cd Entities/<my_entity>
#This is just to test the operation 
python3 <my_entity>/__init__.py  
git remote -v
git remote remove origin
git remote add origin \
    <URL of your TheSyDeKickgroup/<my_entity>.git 
git push --set-upstream origin master 
\end{lstlisting}
}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Converting the new entity to submodule}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item Go through the following steps and try to think what happens in
            in term of git submodules
    \end{itemize}
%    \adjustbox{height=0.4\textheight}{%
\begin{lstlisting}
cd TheSyDeKick_project
rm -rf Entities/<my_entity>
git submodule add  \
    <URL of your TheSyDeKickgroup/<my_entity>.git Entities/<my_module>
\end{lstlisting}
    \begin{itemize}
        \item Edit the ./init\_submodules.sh script to contain\\
            \emph{Entities/<my\_entity>}. Then:
    \end{itemize}
\begin{lstlisting}
./init_submosules.sh
\end{lstlisting}
%}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Working with the submodules}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item If you want to edit a submodule \emph{within the master project}
                this is how it goes
    \end{itemize}
%    \adjustbox{height=0.4\textheight}{%
\begin{lstlisting}
cd Entities/<my_entity>
git chekout master # Or your favorite branch
# Do your edits

git add -i `#Add and select the files you want to commit
git commit # You may use -m, but follow the good practices
           # https://chris.beams.io/posts/git-commit/
git push
# Now comes the trick
cd ../
git add <my_entity>
git commit -m``Update <my_entity> submodule''
git push
# To test if everything went as you really wanted
# ../init_submodules.sh
\end{lstlisting}
%}
\end{frame}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[Simplifying the model to the bone]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{The simplest TheSyDeKick model}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item The template (<my\_entity>) contains features that support
            python,eldo and rtl simulations.
        \item Next, we will remove all the parts from the model, and leave
            only the python model in place.
    \end{itemize}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[The target code] 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{The target code}
\section*{\sectionname}
\setlines{21}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item Edit the \emph{Docstring}
    \end{itemize}
    \codeclip{./myentity/myentity/__init__.py}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{The target code}
\section*{\sectionname}
\nextlines[8]
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item Edit the \emph{package imports}
    \end{itemize}
    \codeclip{./myentity/myentity/__init__.py}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{The target code}
\section*{\sectionname}
\nextlines[52]
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item Edit the \emph{Class definition}
    \end{itemize}
    \codeclip{./myentity/myentity/__init__.py}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{The target code}
\section*{\sectionname}
\nextlines[45]
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item Edit the \emph{Main script}
    \end{itemize}
    \codeclip{./myentity/myentity/__init__.py}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{The target code}
\section*{\sectionname}
\nextlines[45]
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item Now you are ready to run you model
    \end{itemize}
\begin{lstlisting}
cd Entities/<my_entity>
#This is just to test operation 
python3 <my_entity>/__init__.py  
\end{lstlisting}
    \begin{itemize}
        \item The result should look like this:
    \end{itemize}
    \begin{center}
        \includegraphics[width=0.6\textwidth]{./Pics/inv_py.eps}
    \end{center}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{The target code}
\section*{\sectionname}
\nextlines[45]
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item You can now try to run the test with the ``Production method''
    \end{itemize}
\begin{lstlisting}
#cd Entities/<my_entity>
./configure
make sim
\end{lstlisting}
    \begin{itemize}
        \item The result should be the same:
    \end{itemize}
    \begin{center}
        %This is generated by make
        \includegraphics[width=0.6\textwidth]{./Pics/inv_py.eps}
    \end{center}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[Documentation with Doctrings]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Building the documentation}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item TheSyDeKick takes also care for you basic documentation needs
        \item We are ysing Python Docstrings for that. You may do a web search
            to figure out what it means.
        \item Create the documentation or your module with:

    \end{itemize}
\begin{lstlisting}
#cd Entities/<my_entity>
./configure
make doc
\end{lstlisting}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Reading the documentation}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item You may read the documentation with
    \end{itemize}
\begin{lstlisting}
#cd Entities/<my_entity>
firefox ./doc/build/html/index.html
\end{lstlisting}
    \begin{itemize}
        \item Compare the documentation to your source code. You may already
            guess how it is created.
    \end{itemize}
    \begin{center}
        \includegraphics[width=0.7\textwidth]{./Pics/Documentation.png}
    \end{center}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[Getting production ready]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Production version}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname}
    \begin{itemize}
        \item To minimize the need for documentation, TheSydeKick follows the
            following principles
            \begin{itemize}
                \item \emph{./init\_submodules.sh} gets the submodules
                \item \emph{configure} does the configuration and creates the
                    Makefile
                \item \emph{make} does the actual work with some functional
                    defaults, and creates the documentation.
            \end{itemize}
        \item You are now ready to build you module for 'production' use.
    \end{itemize}
\begin{lstlisting}
#cd Entities/<my_entity>
configure && make
\end{lstlisting}
    \begin{itemize}
        \item Press \emph{Return} close the figure.
        \item This runs the simulation and generates the documentation. 
        \item You may study the structure of \emph{configure}
        \item You are now ready to release your module:
    \end{itemize}
\begin{lstlisting}
git add -i  #Select the files you have edited
git commit `# Give a nice and clean commit message
git push    
\end{lstlisting}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Working with the submodules, again}
\section*{\sectionname}
\begin{frame}[t,fragile]
    \frametitle{\sectionname} 
    \begin{itemize}
        \item As you are workin \emph{within the master project}
                remember to update it
    \end{itemize}
%    \adjustbox{height=0.4\textheight}{%
\begin{lstlisting}
cd Entities/
git add <my_entity>
git commit -m``Update <my_entity> submodule''
git push
# To test if everything went as you really wanted
# ../init_submodules.sh
\end{lstlisting}
%}
\end{frame}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\renewcommand{\sectionname}{Next Steps}
\subsection*{\sectionname}
\begin{frame}[c]
    \frametitle{\sectionname}
    \begin{itemize}
        \item Once you understand how to one entity is constructed,please
            familiarize yoursel to \emph{inverter\_testbenchses} and
            \emph{inverter\_tests} enetities.
        \item By studying them yous should learn how to connect entities
            together, and how to construct simulations for different
            simulators.
    \end{itemize}
\end{frame}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\sectiontitle[Congratulations, You are DONE!]

\end{document}