Index: DamEngine/trunk/doc/Work/Python integration in Dam Engine.tex =================================================================== diff -u --- DamEngine/trunk/doc/Work/Python integration in Dam Engine.tex (revision 0) +++ DamEngine/trunk/doc/Work/Python integration in Dam Engine.tex (revision 3464) @@ -0,0 +1,149 @@ +\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} + + \references{-} + + \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} +