\documentclass{deltares_report}
\usepackage{listings}
\usepackage[titletoc]{appendix}
\usepackage{tikz}
\usetikzlibrary{shapes.geometric}
\newcommand{\warningsign}{\tikz[baseline=-.75ex] \node[shape=regular polygon, regular polygon sides=3, inner sep=0pt, draw, thick, red] {\textbf{!}};}

%-----------------------------------------------
\lstset{ %
	basicstyle=\footnotesize,        % the size of the fonts that are used for the code listings
}

\begin{document}
	\pagestyle{empty}
	\cleardoublepage
	%
	
	\newcommand{\DamEngine}{Dam Engine\xspace}
	\newcommand{\Python}{Python integration\xspace}

	\title{\Python in Dam Engine}
	\author{John Bokma}
	\partner{-}
	\subtitle{Pre Design: Research the options}
	\projectnumber{}
	\client{Deltares - DSC}
	\contact{}
	\documentid{-}
	\reference{}
	\classification{-}

	\date{July 2021}
	\version{0.1}

	\keywords{\DamEngine, \Python}


	\summary{This document contains a description of the research into the \Python in \DamEngine. \newline
		\newline
		\textbf{\footnotesize{Samenvatting - NL}} \newline
		Dit document bevat een beschrijving van onderzoek naar de Python integratie in de \DamEngine.}

	\versioni{0.1}
	\datei{July 2021}
	\authori{John Bokma}
	\organisationi{Deltares}
	\revieweri{Tom The}
	\approvali{Hans van Putten}
    \publisheri{Deltares}
    \status{draft}
    \disclaimer{This is a draft report, intended for discussion purposes only. 
    	No part of this report may be relied upon by either principals or third parties.}

	\deltarestitle
	
%------------------------------------------------------------------------------

\chapter{Introduction} 
\label{sec:Introduction}

\section{About this document} 
\label{sec:PurposeAndScope}

This document describes the research done into the Python integration in the Dam Engine. 

\section{Versions} 
\label{sec:Versions}
This is a description of the different versions of this document.
\subsection{Version 0.1} \label{sec:Version0_1}
Initial version.

%------------------------------------------------------------------------------
\chapter{Solution as used in Delta Shell} 
\label{sec:SolutionDeltaShell}

Delta Shell currently offers \Python in its products. 
It even offers the integration in two different ways. 

First, they opened up their entire data structure and classes for third party access by exposing that structure and those classes publicly. 
We will call this the open structure method for now.  

Secondly, they used Iron Python (a special version of Python) to enable scripting directly, even from within the UI of Delta Shell.
We will call this the Iron Python method for now.

\section{Open structure methode} 
\label{sec:OpenStructureMethod}

The open structure method gives full access to the entire \DamEngine.
Therefore it is most flexible from the view point of the initial script writer.
The writer can do (almost) any thing that's thinkable and script-able.
Also any version, dialect and/or libraries of Python can be used in order to create the scripts.

With this openness comes its greatest possible downfall too.
Any change in data or method(s) in the \DamEngine that are used in a script will most likely cause that script to fail.
Or even worse, it will alter the outcome of an existing script without the script user being aware of this.

Writing scripts will demand a great deal of knowledge about the \DamEngine, its data-structure and classes.
The only form of support that can be offered is proving the technical documentation.
This lists all used classes, properties and methods.   

Pro's:
\begin{itemize}
	\item Any Python version/dialect can be used by the end user.
	\item Anything the user can think of and that can be scripted using Python is possible.
\end{itemize} 

Con's:
\begin{itemize}
	\item It will be hard if not impossible to provide support beyond proving documentation.
	\item When structure/classes changes, existing scripts will most likely fail.
	\item The user has access to all our data and classes.
	\item Hard to roll out when Python itself needs to be distributed as well.
\end{itemize} 

\section{Iron Python method} 
\label{sec:IronPythonMethod}

The Iron Python method uses a special version of Python called Iron Python. 
This is a predefined package which offers scripting in Python style but it limits the possibilities to libraries included in that package. 
This package is (at this moment) not extensible.
  
The Iron Python method needs to be configured to gain access to the \DamEngine. 
Data, methods and classes from within \DamEngine need to be exposed to the Iron Python method in order to be used by it. 
From the view point of the script writer, this has advantages (a guaranteed interface) 
as well as disadvantages (not everything will be exposed).

Using Iron Python offers the possibility to provide the script writer with an editor (or scripting host) that supports code completion.
This will support the script writer a great deal in speed as well as keeping the learning curve for getting to know the \DamEngine data-structure far less steep.
Also, from this editor predefined libraries can be accessed and used to fulfill frequently used tasks.

Pro's: 
\begin{itemize}
	\item Scripts will keep running even when the data structure and/or classes in the \DamEngine are changed.
	\item An editor (or scripting host) can be provided with real time development support (code completion for methods and properties).
	\item In the future, the editor could even be incorporated with a Dam UI (current one/future one/user created one).
	\item Predefined libraries for "standard" usages could be provided.
	\item Can be rolled out with ease.
	\item We can control access to those parts of the \DamEngine we really like to expose whilst keeping other parts hidden.
\end{itemize} 

Con's:
\begin{itemize}
	\item Only the Iron Python libraries can be used. They do not allow the use of other popular Python libraries such as Num.py and Sci.py.
	\item Scripting is only possible for exposed data and/or class items.
\end{itemize} 

\end{document}

