\documentclass[12pt]{beamer}
\input{BEAMERoptions.tex}

% ----- Packages and libraries ----- %
\usepackage[T1]{fontenc} 				% cut/paste and search with "_"
\usepackage[english]{babel}
\usepackage{graphics}
\usepackage{verbatim}
\usepackage{times}
\usepackage{graphicx}
\usepackage{epsfig}
\usepackage{subfigure}
\usepackage{amssymb}
\usepackage{amsmath, amsfonts}
\usepackage{amsthm}
\usepackage{color}
\usepackage{alltt}
\usepackage{anyfontsize}
\usepackage{tikz}
   \usetikzlibrary{shapes, arrows, shadows}

\newcommand{\Frametitle}[1]{\frametitle{\includegraphics[width=0.25in]{esp_logo.png}
      \hspace{0.05in} #1}}

\newcommand{\FrameTitle}[1]{\frametitle{\includegraphics[width=0.3in]{caps_logo.png}
      \hspace{0.05in} #1}}

\setbeamertemplate{navigation symbols}{}
\setbeamertemplate{caption}[numbered]

%============================
% command to repeate a ~ n-times
%============================
\newcount\myloopcounter

\newcommand{\spaces}[1][10]{%
  \myloopcounter0% initialize the loop counter
  \loop\ifnum\myloopcounter < #1 % Test if the loop counter is < #1
  ~%
  \advance\myloopcounter by 1 %
  \repeat % start again
}
%============================

% ----- Presentation information ----- %
\title[AIM Software Structure]{
\includegraphics[width=1.0in]{caps_logo.png}\\
Computational Aircraft Prototype Syntheses\\
AIM Programming\\
AIM Software Structure\\[0.02in]
For {\tt ESP} Rev 1.28}

\author[Haimes]{
Bob Haimes \\
  {\footnotesize \textcolor{blue}{bob@geocentrictech.com}~~or~~\textcolor{blue}{haimes@mit.edu} \\[-0.03in]
    Geocentric Technologies LLC}
}

\date[July 2025]{}

% ----- Document follows ----- %

\begin{document}

\begin{frame}
  \titlepage
\end{frame}

\begin{frame}
  \FrameTitle{Execution Driven by Dependency}

  \vspace{-.085in}
  \begin{itemize}
    \item All CAPS Objects have a serial number -- an unsigned 64 bit integer (\textcolor{magenta}{uint64\_t}). The {\it active} SN starts at 1 when the Problem Object is initialized. 
    \item The SN is set to zero when an Object is created indicating it is unfilled and {\it dirty}. 
    \item When any Object is changed the {\it active} SN is incremented and set in that Object. This is automatically accomplished by setting/updating a Value.
    \item When data is requested in CAPS the dependencies for the {\it owner} of that information are examined. If any have a SN greater than
    the owner's SN then this part of the dependency tree is {\it dirty}. 
    \item {\it Links} are followed and override the any AnalysisIn data.
    {\it Links} are followed for any FieldIn data (which can cause a data transfer).
    \item Each connection is recursively examined and then execution is forward triggered to {\it clean} the state. This is done by incrementing 
    the {\it active} SN and setting it in the Object executed.
  \end{itemize}
  
  \end{frame}

\begin{frame}[fragile]
  \FrameTitle{capsValue Structure 1/6}

\footnotesize
The \textcolor{blue}{capsValue} Structure is simply the data found within a CAPS Value Object.\\
{\tt aimInputs} and {\tt aimOutputs} must fill the structure with the {\it type}, {\it form} and optionally {\it units} of the
data. {\tt aimInputs} also sets the default value(s) in the {\it vals} member. The structure's members listed below must be filled
(most have defaults).

\vspace{-0.04in}
\begin{block}{Value Type -- no default}
The value {\it type} can be one of:
\vspace{-0.1in}
{\tiny {\bf
\begin{verbatim}
enum capsvType {Boolean, Integer, Double, String, Tuple, Pointer, DoubleDeriv, PointerMesh};
\end{verbatim}
}}

\vspace{-0.1in}
{\scriptsize
Notes:
\begin{enumerate}
\vspace{-0.05in}
\item The {\tt Pointer}/{\tt PointerMesh} types are only supported at the AIM level to communicate\\ between AIMs.
Linkages should be used from {\it AnalysisOut} to {\it AnalysisIn} to make the connection. The {\tt units}
member of the Value Structure must match for a successful link.
\vspace{-0.05in}
\item {\tt DoubleDeriv} is a {\tt Double} with optional derivatives (GeometryOut, AnalysisOut \& AnalysisDynO only)
\end{enumerate}
}
\end{block}

\vspace{-0.05in}
\begin{block}{The tuple structure}
{\scriptsize
\begin{verbatim}
typedef struct {
  char *name;                   /* the name */
  char *value;                  /* the value for the pair */
} capsTuple;
\end{verbatim}
}
\end{block}

\end{frame}

\begin{frame}[fragile]
  \FrameTitle{capsValue Structure 2/6}

\footnotesize

\begin{block}{Shape of the Value -- 0 is the default}
{\it dim} can be one of:\\[0.05in]
  \begin{tabular}{ l l }
    \textcolor{espred}{0} & scalar only  \\
    \textcolor{espred}{1} & vector or scalar \\
    \textcolor{espred}{2} & scalar, vector or 2D array  \\
  \end{tabular}
\end{block}

\begin{block}{Value Dimensions -- 1 is the default}
{\it nrow} and {\it ncol} set the dimension of the Value. If both are 1 this has a {\tt scalar} shape. If
either {\it nrow} or {\it ncol} are one then the shape is {\tt vector}. If both are greater than 1 then
this represents a 2D array of values.
\end{block}

\begin{block}{Other enumerated constants}
{\scriptsize
\begin{verbatim}
enum capsFixed   {Change, Fixed};
enum capsNull    {NotAllowed, NotNull, IsNull, IsPartial};
enum capstMethod {Copy, Integrate, Average};
 \end{verbatim}
}
\end{block}

\end{frame}

\begin{frame}
  \FrameTitle{capsValue Structure 3/6}

\vspace{-0.05in}
\begin{block}{Varying Length -- the default is ``Fixed''}
The member {\it lfixed} indicates whether the length of the Value is allowed to change.
\end{block}

\vspace{-0.05in}
\begin{block}{Varying Shape -- the default is ``Fixed''}
The member {\it sfixed} indicates whether the {\it shape} (i.e., {\it dim}) of the Value is allowed to change.
\end{block}

\vspace{-0.05in}
\begin{block}{Can Value be NULL? -- the default is ``NotAllowed''}
The member {\it nullVal} indicates whether the Value is or can be \textcolor{magenta}{NULL}\\
Options are found in~~ {\tt enum capsNULL}
\end{block}

\vspace{-0.05in}
\begin{block}{A Note on String Storage}
Multiple Strings are not stored as a list of pointers, but as a contiguous block of memory where each
individual string is zero terminated.
\end{block}

\end{frame}

\begin{frame}
  \FrameTitle{capsValue Structure 4/6}

\vspace{-0.085in}
\footnotesize
\begin{block}{capsValue Member Usage Notes}
The AIM has complete access to the Value structure but should only modify the contents of AnalysisIn, AnalysisOut and AnalysisDynO
Values.
\begin{itemize}
\item {\it sfixed} \& {\it dim}\\
If the shape is ``Fixed'' then {\it nrow} and {\it ncol} must fit that shape. For example, if the shape is vector then both {\it nrow} and {\it ncol}
cannot be greater than 1.
\vspace{-0.02in}
\item {\it lfixed} \& {\it nrow}/{\it ncol} \\
If the length is ``Fixed'' then all updates of the Value(s) must match in both  {\it nrow} and {\it ncol} (which presumes a
``Fixed'' shape).
\vspace{-0.02in}
\item {\it nullVal} \& {\it nrow}/{\it ncol} \\
{\it nrow} and {\it ncol} should remain at their values even if the Value is \textcolor{magenta}{NULL} to maintain the
dimension (and possibly length) when ``Fixed''. To indicate a \textcolor{magenta}{NULL} all that is necessary is to
set {\it nullVal}  to ``IsNull''. The actual allocated storage can remain in the {\it vals} member or set to \textcolor{magenta}{NULL}.
\vspace{-0.02in}
\item Use {\tt AIM\_ALLOC} to allocate any memory required for the {\it vals} member.
\vspace{-0.02in}
\item After the Value has been created {\it sfixed} and {\it lfixed} must not be changed!

\end{itemize}
\end{block}
\end{frame}

 \begin{frame}[fragile]
\FrameTitle{capsValue Structure 5/6}
{\tiny
\begin{verbatim}
/*
 * structure for derivative data w/ CAPS Value structure
 *   only used with "real" (double) data and
 *   only with GeometryOut, AnalysisOut or AnalysisDynO Value Objects
 */
 
typedef struct {
  char   *name;                 /* the derivative with respect to */
  int    len_wrt;               /* the number of members in the derivative
                                   w.r.t. Value Object */
  double *deriv;                /* the derivative values
                                   - capsValue.length*len_wrt long */
} capsDeriv;


/*
 * structure for CAPS object -- VALUE
 */

 typedef struct {
  int          type;            /* value type -- capsvType */
  int          length;          /* number of values */
  int          dim;             /* the dimension */
  int          nrow;            /* number of rows */
  int          ncol;            /* the number of columns */
 \end{verbatim}
}
\end{frame}

 \begin{frame}[fragile]
\FrameTitle{capsValue Structure 6/6}
{\tiny
\begin{verbatim}

  int          lfixed;          /* length is fixed */
  int          sfixed;          /* shape is fixed */
  int          nullVal;         /* NULL handling */
  int          index;           /* index into collection of Values */
  int          pIndex;          /* DESPMTR index */
  int          gInType;         /* 0 -- DESPMTR (or not GeomIn), 1 -- CFGPMTR,
                                   2 -- CONPMTR */
  union {
    int        integer;         /* single int -- length == 1 */
    int        *integers;       /* multiple ints */
    double     real;            /* single double -- length == 1 */
    double     *reals;          /* mutiple doubles */
    char       *string;         /* character string (no single char) */
    capsTuple  *tuple;          /* tuple (no single tuple) */
    void       *AIMptr;         /* AIM pointer(s) */
  } vals;
  union {
    int        ilims[2];        /* integer limits */
    double     dlims[2];        /* double  limits */
  } limits;
  void         *lims;           /* per element limits [2*length*sizeof()] */
  char         *units;          /* the units for the values */
  char         *meshWriter;     /* the mesh writer (linked AnalysisIn) */
  capsObject   *link;           /* the linked object (or NULL) */
  int          linkMethod;      /* the link method */
  int          *partial;        /* NULL or vector/array element NULL handling */
  int          nderiv;          /* the number of derivatives */
  capsDeriv    *derivs;         /* the derivatives associated with the Value */
  double       *stepSize;       /* Finite Difference step size - DESPMTR only */
} capsValue;
 \end{verbatim}
}
\end{frame}

\begin{frame}
  \FrameTitle{AIM -- Registration/Initialization}
 \vspace{-0.1in}
%  \setbeamercolor{block title}{bg=red!80}
\begin{block}{Initialization Information for the AIM}
{\scriptsize

{\tt
icode = aimInitialize(\textcolor{magenta}{int} qFlag, \textcolor{magenta}{const char}  *uSys, \textcolor{magenta}{void} *aimInfo, \\
\spaces[22]\textcolor{magenta}{void} **instStore, \textcolor{magenta}{int} *major, \textcolor{magenta}{int} *minor,  \\
\spaces[22]\textcolor{magenta}{int} *nIn, \textcolor{magenta}{int} *nOut, \textcolor{magenta}{int} *nFields, \\
\spaces[22]\textcolor{magenta}{char} ***fnames, \textcolor{magenta}{int} **franks, \textcolor{magenta}{int} **fInOut)}

\begin{description}
\vspace{-0.03in}
\item[qFlag] $-1$ indicates a query and not a new analysis instance (0 or greater)
\item[uSys] a pointer to a character string declaring the unit system -- can be \textcolor{magenta} {NULL}
\item[aimInfo] the AIM context \textcolor{espred}{-- NULL if qFlag == -1}
\item[instStore] a returned pointer to a block of memory to be associated with this AIM instance\\
may be returned as \textcolor{magenta} {NULL} if no AIM state data is required
\item[major] the returned AIM major version number
\item[minor] the returned AIM minor version number
\item[nIn]  the returned number of Inputs (minimum of 1)
\item[nOut]  the returned number of possible Outputs
\item[nFields] \textcolor{gray}{the returned number of fields to responds to for DataSet filling}
\item[fnames] \textcolor{gray}{a returned pointer to a list of character strings with the field/DataSet names $\dagger$}
\item[franks] \textcolor{gray}{a returned pointer to a list of ranks associated with each field $\dagger$}
\item[fInOut] \textcolor{gray}{a returned pointer to a list of field flags (FIELDIN - input, FIELDOUT - output) $\dagger$}
\item[icode] integer return code
\end{description}}

\end{block}

\end{frame}

\begin{frame}
  \FrameTitle{AIM -- Initialization}

\vspace{-0.075in}
%  \setbeamercolor{block title}{bg=red!80}
\begin{block}{Return Analysis Inputs}
{\scriptsize

{\tt
icode = aimInputs(\textcolor{magenta}{void} *instStore, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} index,  \\
\hspace{1.13in} \textcolor{magenta}{char} **ainame, \textcolor{blue}{capsValue} *defval)}

\vspace{-0.025in}
\begin{description}

\item[instStore] the AIM {\it instance} storage -- \textcolor{magenta}{NULL} if called from {\tt caps\_getInput}
\vspace{-0.03in}
\item[aimInfo] the AIM context -- \textcolor{magenta}{NULL} if called from {\tt caps\_getInput}
\vspace{-0.03in}
\item[index] the Input index [1-{\tt nIn}]
\vspace{-0.03in}
\item[ainame] a returned pointer to the returned Analysis Input variable name
\vspace{-0.03in}
\item[defval] a pointer to the filled default value(s) and units -- any allocated memory will be freed
\vspace{-0.03in}
\item[icode] integer return code
\end{description}}

\end{block}

\vspace{-0.05in}
\begin{block}{Return Analysis Outputs}
{\scriptsize

{\tt
icode = aimOutputs(\textcolor{magenta}{void} *instStore, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} index, \\
\hspace{1.20in} \textcolor{magenta}{char} **aoname, \textcolor{blue}{capsValue} *form)}

\vspace{-0.025in}
\begin{description}
\item[instStore] the AIM {\it instance} storage -- \textcolor{magenta}{NULL} if called from {\tt caps\_getOutput}
\vspace{-0.03in}
\item[aimInfo] the AIM context -- \textcolor{magenta}{NULL} if called from {\tt caps\_getOutput}
\vspace{-0.03in}
\item[index] the Output index [1-{\tt nOut}]
\item[aoname] a returned pointer to the returned Analysis Output variable name
\vspace{-0.03in}
\item[form] a pointer to the Value Shape \& Units information -- to be filled\\
any actual values stored are ignored/freed
\vspace{-0.03in}
\item[icode] integer return code
\end{description}}

\end{block}

\end{frame}

\begin{frame}
  \FrameTitle{AIM -- PreAnalysis}

       \begin{block}{Set or Update the AIM's Internal State}
{\scriptsize

{\tt
icode = aimUpdateState(\textcolor{magenta}{void} *instStore, \textcolor{magenta}{void} *aimInfo, \\
\hspace{1.46in} \textcolor{blue}{capsValue} *inputs)}

\begin{description}

\item[instStore] the AIM {\it instance} storage
\item[aimInfo] the AIM context (used by the Utility Functions)
\item[inputs] the complete suite of Analysis inputs ({\tt nIn} in length) \\
\item[icode] integer return code
\end{description}}
\scriptsize
Notes: This function is always called first in the execution sequence (before {\tt aimDiscr}, {\tt aimPreAnalysis} or {\tt aimPostAnalysis}).
It should not write into the Analysis directory.
  \end{block}

\setbeamercolor{block title}{bg=espblue}
     \begin{block}{Parse Input data \& Generate Input File(s)}
{\scriptsize

{\tt
icode = aimPreAnalysis(\textcolor{magenta}{const void} *instStore, \textcolor{magenta}{void} *aimInfo, \\
\hspace{1.46in} \textcolor{blue}{capsValue} *inputs)}

\begin{description}

\item[instStore] the AIM {\it instance} storage
\item[aimInfo] the AIM context (used by the Utility Functions)
\item[inputs] the complete suite of Analysis inputs ({\tt nIn} in length) \\
\item[icode] integer return code
\end{description}}
  \end{block}

\end{frame}

\begin{frame}
  \FrameTitle{AIM -- Execute \& PostAnalysis}

%\vspace{-0.05in}
% \setbeamercolor{block title}{bg=red!80}
%     \begin{block}{Check on running Analysis -- Optional}
%{\scriptsize
%
%{\tt
%icode = aimCheck(\textcolor{magenta}{void} *instStore, \textcolor{magenta}{void} *aimInfo,   \textcolor{magenta}{int} *state)}
%
%\begin{description}
%
%\item[instStore] the AIM {\it instance} storage
%\item[aimInfo] the AIM context (used by the Utility Functions)
%\item[state] the returned status (0 - done, 1 - running) \\
%\item[icode] integer return code
%\end{description}}
%  \end{block}

\vspace{-0.075in}
     \begin{block}{Execute Analysis -- Optional}
{\scriptsize

{\tt
icode = aimExecute(\textcolor{magenta}{const void} *instStore, \textcolor{magenta}{void} *aimInfo,  \textcolor{magenta}{int} *state)}

\begin{description}

\item[instStore] the AIM {\it instance} storage
\vspace{-0.025in}
\item[aimInfo] the AIM context (used by the Utility Functions)
\vspace{-0.025in}
\item[state] the returned status (0 - done, 1 - running) -- currently unused
\vspace{-0.025in}
\item[icode] integer return code
\end{description}}
\vspace{-0.025in}
\scriptsize
Note: if this function exists it is an indication that the AIM can auto-execute. Otherwise the execution is driven explicitly and errors are raised
if data is requested from the {\it dirty} AIM instance.
  \end{block}

\vspace{-0.075in}
     \begin{block}{Processing after the Analysis is run}
{\scriptsize

{\tt
icode = aimPostAnalysis(\textcolor{magenta}{void} *instStore, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} restart, \\
\hspace{1.53in}  \textcolor{blue}{capsValue} *inputs)}

\begin{description}

\item[instStore] the AIM {\it instance} storage
\vspace{-0.025in}
\item[aimInfo] the AIM context (used by the Utility Functions)
\vspace{-0.025in}
\item[restart] restart state (0 - normal, 1 - restart invocation)
\vspace{-0.025in}
\item[inputs] the complete suite of Analysis inputs -- for restart ({\tt nIn} in length)
\vspace{-0.025in}
\item[icode] integer return code
\end{description}}
\vspace{-0.025in}
\scriptsize
Note: this function gets called by {\tt caps\_postAnalysis}, implicitly during {\tt caps\_execute},
during lazy execution (if auto-exec) and while restarting (only for the last invocation of an instance) to populate any internal state information
(and should not write into the Analysis directory).
  \end{block}


\end{frame}


\begin{frame}
  \FrameTitle{AIM -- Termination \& Output Parsing}

\vspace{-0.075in}
       \begin{block}{Free up any memory the AIM has stored}
{\scriptsize

{\tt
\textcolor{magenta}{void} aimCleanup(\textcolor{magenta}{void} *instStore)}

\begin{description}
\item[instStore] the block of memory associated with a particular instance
\end{description}}
    \vspace{0.05in}
  \scriptsize
  Note:
  \begin{itemize}
 \item  Called a number of times, once for each instance
 \end{itemize}
  \end{block}

     \begin{block}{Calculate/Retrieve Output Information}
{\scriptsize

{\tt
icode = aimCalcOutput(\textcolor{magenta}{void} *instStore, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} index, \\
\hspace{1.40in} \textcolor{blue}{capsValue} *val)}

\begin{description}

\item[instStore] the AIM {\it instance} storage
\item[aimInfo] the AIM context (used by the Utility Functions)
\item[index] the Output index [1-{\tt nOut}] for this single result
\item[val] a pointer to the capsValue data to fill -- CAPS will free any allocated memory
\item[icode] integer return code
\end{description}}
    \vspace{0.05in}
  \scriptsize
  Note:
  \begin{itemize}
 \item  Called in a {\it lazy} manner, only when the output is needed (and after the Analysis is run)
 \end{itemize}
  \end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

 \begin{block}{Function Status MACRO}
{\scriptsize
{\tt
AIM\_STATUS(\textcolor{magenta}{void} *aimInfo,  \textcolor{magenta}{int} status, ...)}

\begin{description}

\item[aimInfo] the AIM context
\item[status] return status from a function
\item[...] printf type format string and data
\end{description}}
\vspace{0.05in}
\scriptsize
Notes:
\begin{enumerate}
\item Tracks file, line, and function name backtrace information -- if \textcolor{espred}{status} < CAPS\_SUCCESS
\item Includes ``\textcolor{magenta}{goto} cleanup''  if \textcolor{espred}{status} < CAPS\_SUCCESS
\end{enumerate}
\end{block}

 \begin{block}{{\scriptsize Pseudo Code Examples}}
  {\tiny
\begin{alltt}
status = myfunc1(aimInfo, arg1, arg2);
AIM\_STATUS(aimInfo, status)

status = myfunc2(aimInfo, arg1, arg2);
AIM\_STATUS(aimInfo, status, "myfunc2 args \%d, \%d", arg1, arg2)
\end{alltt}
}
\end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

 \begin{block}{Function Status MACRO with NOTFOUND exception}
{\scriptsize
{\tt
AIM\_NOTFOUND(\textcolor{magenta}{void} *aimInfo,  \textcolor{magenta}{int} status, ...)}

\begin{description}

\item[aimInfo] the AIM context
\item[status] return status from a function
\item[...] printf type format string and data
\end{description}}
\vspace{0.05in}
\scriptsize
Notes:
\begin{enumerate}
\item Tracks file, line, and function name backtrace information -- if \textcolor{espred}{status} < CAPS\_SUCCESS and \textcolor{espred}{status} != CAPS\_NOTFOUND and \textcolor{espred}{status} != EGADS\_NOTFOUND
\item Includes ``\textcolor{magenta}{goto} cleanup''  if the check fails
\end{enumerate}
\end{block}

 \begin{block}{{\scriptsize Pseudo Code Examples}}
  {\tiny
\begin{alltt}
status = myfunc1(aimInfo, arg1, arg2);
AIM\_NOTFOUND(aimInfo, status)

status = myfunc2(aimInfo, arg1, arg2);
AIM\_NOTFOUND(aimInfo, status, "myfunc2 args \%d, \%d", arg1, arg2)
\end{alltt}
}
\end{block}

\end{frame}


\def\braces#1{[#1]}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

\vspace{-0.075in}
 \begin{block}{ANALYSISIN Error Message MACRO}
{\scriptsize

{\tt 
AIM\_ANALYSISIN\_ERROR(\textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{enum} index, \textcolor{magenta}{const char} *format, \\
\hspace{12em} ...)}

\begin{description}
\item[aimInfo] the AIM context
\item[index] index of ANALYSISIN
\item[format] printf format string
\item[...] printf data
\end{description}}
\scriptsize
\vspace{0.05in}
Note: Tracks file, line, and function name backtrace information
\end{block}

 \begin{block}{{\scriptsize Pseudo Code Examples}}
  {\tiny
\begin{alltt}
  mach = inputs[Mach-1].vals.real;
  if (mach < 0) \{
    AIM\_ANALYSISIN\_ERROR(aimInfo, Mach,
                         "Mach = %f must be >= 0{\textbackslash}n", mach);
    status = CAPS\_BADVALUE;
    goto cleanup;
  \}
\end{alltt}
}
\end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

\vspace{-0.075in}
 \begin{block}{Error Message MACRO}
{\scriptsize

{\tt
AIM\_ERROR(\textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{const char} *format, ...)}

\begin{description}
\item[aimInfo] the AIM context
\vspace{-0.05in}
\item[format] printf format string
\vspace{-0.05in}
\item[...] printf data
\end{description}}
\scriptsize
Note: Tracks file, line, and function name backtrace information
\end{block}

\vspace{-0.075in}
 \begin{block}{Message Add Line MACRO}
{\scriptsize

{\tt
AIM\_ADDLINE(\textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{const char} *format, ...)}

\begin{description}
\item[aimInfo] the AIM context
\vspace{-0.05in}
\item[format] printf format string
\vspace{-0.05in}
\item[...] printf data
\end{description}}
%\scriptsize
%Note: Tracks file, line, and function name backtrace information
\end{block}

\vspace{-0.075in}
 \begin{block}{{\scriptsize Pseudo Code Examples}}
  {\tiny
\begin{alltt}
status = aim\_getBodies(aimInfo, \&nBody, \&bodies);
AIM\_STATUS(aimInfo, status)

If (nBody != 1)  \{
  AIM\_ERROR(aimInfo, "Only one body expected, but nBody = \%d", nBody);
  AIM\_ADDLINE(aimInfo, "This aim can only work with one body");
  status = CAPS_BADVALUE;
  goto cleanup;
\}
\end{alltt}
}
\end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

\vspace{-0.05in}
 \begin{block}{Warning Message MACRO}
{\scriptsize

{\tt
AIM\_WARNING(\textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{const char} *format, ...)}

\begin{description}
\item[aimInfo] the AIM context
\item[format] printf type format string
\item[...] printf data
\end{description}}
\vspace{0.05in}
\scriptsize
Notes:
\begin{enumerate}
\item Tracks file, line, and function name backtrace information
\item Use {\tt AIM\_ADDLINE} to add additional lines
\end{enumerate}
\end{block}

 \begin{block}{{\scriptsize Pseudo Code Examples}}
  {\tiny
\begin{alltt}
status = aim\_getBodies(aimInfo, \&nBody, \&bodies);
AIM\_STATUS(aimInfo, status)

If (nBody > 1)  \{
  AIM\_WARNING(aimInfo, "Only one body will be used, but nBody = \%d", nBody);
  AIM\_ADDLINE(aimInfo, "This aim only uses one body");
\}
\end{alltt}
}
\end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

\vspace{-0.075in}
 \begin{block}{Informational Message MACRO}
{\scriptsize

{\tt
AIM\_INFO(\textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{const char} *format, ...)}

\begin{description}

\item[aimInfo] the AIM context
\vspace{-0.01in}
\item[format] printf type format string
\vspace{-0.01in}
\item[...] printf data
\end{description}}
\scriptsize
Notes:
\begin{enumerate}
\item Tracks file, line, and function name backtrace information
\item Use {\tt AIM\_ADDLINE} to add additional lines
\end{enumerate}
\end{block}

\vspace{-0.05in}
 \begin{block}{Remove Error Message}
{\scriptsize

{\tt
~~~~~aim\_removeError(\textcolor{magenta}{void} *aimInfo)}

\begin{description}
\item[aimInfo] the AIM context
\end{description}}
\end{block}

\vspace{-0.05in}
 \begin{block}{{\scriptsize Pseudo Code Example}}
  {\tiny
\begin{alltt}
status = myfunc3(aimInfo, arg1, arg2);
if (status == CAPS\_BADVALUE) \{
  aim\_removeError(aimInfo);
  /* Resolve CAPS\_BADVALUE error */
\} else \{
  AIM\_STATUS(aimInfo, status);
\}
\end{alltt}
}
\end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

\vspace{-0.075in}
% \setbeamercolor{block title}{bg=red!80}
 \begin{block}{Memory Allocation MACROs}
{\scriptsize

{\tt
AIM\_ALLOC(\textcolor{magenta}{void} *ptr, \textcolor{magenta}{size\_t} size, \textcolor{magenta}{type}, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} status)\\
AIM\_REALL(\textcolor{magenta}{void} *ptr, \textcolor{magenta}{size\_t} size, \textcolor{magenta}{type}, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} status)}

\begin{description}
\item[ptr] pointer assigned allocation (must be \textcolor{magenta}{NULL} for AIM\_ALLOC)
\item[size] number of  \textcolor{magenta}{type} allocations
\item[type] data type for the allocation
\item[aimInfo] the AIM context
\item[status] function return status
\end{description}}
\vspace{0.05in}
\scriptsize
Notes:
\begin{enumerate}
\item Tracks file, line, and function name backtrace information
\item Includes ``\textcolor{magenta}{goto} cleanup'' on error and sets \textcolor{espred}{status} = EGADS\_MALLOC
\end{enumerate}
\end{block}

 \begin{block}{Free Memory}
{\scriptsize

{\tt
AIM\_FREE(\textcolor{magenta}{void} *ptr)}

\begin{description}
\item[ptr] frees pointer memory and sets \textcolor{espred}{ptr} = \textcolor{magenta}{NULL}
\end{description}}
\end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}

\vspace{-0.075in}
 \begin{block}{String Duplication MACRO}
{\scriptsize

{\tt
AIM\_STRDUP(\textcolor{magenta}{char} *ptr, \textcolor{magenta}{const char} *str, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} status)}

\begin{description}
\item[ptr] pointer assigned allocation (must be \textcolor{magenta}{NULL})
\vspace{-0.01in}
\item[str] string for duplication
\vspace{-0.01in}
\item[aimInfo] the AIM context
\vspace{-0.01in}
\item[status] function return status
\end{description}}
\vspace{0.05in}
\scriptsize
Notes:
\begin{enumerate}
\item Tracks file, line, and function name backtrace information
\item Includes ``\textcolor{magenta}{goto} cleanup'' on error and sets \textcolor{espred}{status} = EGADS\_MALLOC
\end{enumerate}
\end{block}

 \begin{block}{Enum Name Creation MACRO}
{\scriptsize

{\tt
\textcolor{magenta}{char} *AIM\_NAME(\textcolor{magenta}{enum} Name)}

\begin{description}
\item[Name] enumeration
\end{description}}
\scriptsize
Notes:
Converts enumeration Index ``Name'' to a string and returns a duplicate string
\end{block}

\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Memory \& Error Handling}


\vspace{-0.075in}
 \begin{block}{Memory \& Error Handling}
{\scriptsize

{\tt
AIM\_NOTNULL(\textcolor{magenta}{char} *ptr, \textcolor{magenta}{void} *aimInfo, \textcolor{magenta}{int} status)}

\begin{description}
\item[ptr] pointer checked
\vspace{-0.01in}
\item[aimInfo] the AIM context
\vspace{-0.01in}
\item[status] function return status
\end{description}}
\scriptsize
Notes:
If \textcolor{espred}{ptr} == \textcolor{magenta}{NULL}, sets \textcolor{espred}{status} = CAPS\_NULLVALUE and then  ``\textcolor{magenta}{goto} cleanup''
\end{block}

 \begin{block}{{\scriptsize Pseudo Code Example}}
  {\tiny
\begin{alltt}
enum aimInputs \{
  Mach = 1,         /* index is 1-based */
  NUMINPUT = Mach   /* Total number of inputs */
\};
...
  if (index == Mach) \{
    *ainame = AIM_NAME(Mach);
    ...
  \}
  AIM\_NOTNULL(*ainame, aimInfo, status);
\end{alltt}
}
\end{block}

\end{frame}

\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~1/10}
  
  {\tiny
\begin{verbatim}
#include <string.h>
#include <math.h>
#include "aimUtil.h"

//#define DEBUG

enum aimInputs
{
  InputVariable = 1,           /* index is 1-based */
  num,
  Mach,
  Mesh_Format,
  Table,
  NUMINPUT = Table             /* Total number of inputs */
};

enum aimOutputs
{
  sqrtNum = 1,                 /* index is 1-based */
  NUMOUT  = sqrtNum            /* Total number of outputs */
};


typedef struct {
  int nBody;
  ego *tess;
} aimStorage;

\end{verbatim}
}
  
  \end{frame}
  
  \begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~2/10}
  
  {\tiny
\begin{verbatim}
int aimInitialize(int inst, const char *unitSys, void *aimInfo,
                  void **instStore, int *major, int *minor, int *nIn, int *nOut,
                  int *nFields,  char ***fnames, int **franks, int **fInOut)
{
  int        status;
  aimStorage *aimStore = NULL;

#ifdef DEBUG
  printf("\n myAIM/aimInitialize  instance = %d  unitSys = %s!\n",
         inst, unitSys);
#endif
  
  /* specify the rev of this AIM */
  *major = 1;
  *minor = 0;

  /* specify the number of analysis inputs and outputs */
  *nIn  = NUMINPUT;
  *nOut = NUMOUT;

  /* return if "query" only */
  if (inst == -1) return CAPS_SUCCESS;

  /* specify the field variables this analysis can generate and consume */
  *nFields = 0;
  
  /* setup our AIM specific state */
  AIM_ALLOC(aimStore, 1, aimStorage, aimInfo, status);
  *instStore = aimStore;
\end{verbatim}
}
  
 \end{frame}
  
  \begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~3/10}
  
  {\tiny
\begin{verbatim}
  /* populate our instance storage */
  aimStore->nBody = 0;
  aimStore->tess  = NULL;

  return CAPS_SUCCESS;
  
cleanup:
  return status;
}


int aimInputs(void *instStore, void *aimInfo, int index,
              char **ainame, capsValue *defval)
{
  int       i, status = CAPS_SUCCESS;
  capsTuple *tuple = NULL;
  
#ifdef DEBUG
  printf(" myAIM/aimInputs  instance = %d  index  = %d!\n",
         aim_getInstance(aimInfo), index);
#endif

  /* fill in the required members based on the index */
 if (index == InputVariable) {
    *ainame              = AIM_NAME(InputVariable);
    defval->type         = Boolean;
    defval->vals.integer = false;
    
  } else if (index == num) {
    *ainame           = AIM_NAME(num);
    defval->type      = Double;
    defval->vals.real = 8.0;
\end{verbatim}
}
\end{frame}

  \begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~4/10}
  
  {\tiny
\begin{verbatim}
  } else if (index == Mach) {
    *ainame              = AIM_NAME(Mach); // Mach number
    defval->type         = Double;
    defval->nullVal      = IsNull;
    defval->units        = NULL;
    defval->lfixed       = Change;
    defval->dim          = Scalar;

  } else if (index == Mesh_Format) {
    *ainame              = AIM_NAME(Mesh_Format);
    defval->type         = String;
    defval->lfixed       = Change;
    AIM_STRDUP(defval->vals.string, "AFLR3", aimInfo, status);

  } else if (index == Table) {
    /* an example of filling in a Tuple */
    *ainame = AIM_NAME(Table);

    AIM_ALLOC( tuple, 3, capsTuple, aimInfo, status);
    for (i = 0; i < 3; i++) {
      tuple[i].name  = NULL;
      tuple[i].value = NULL;
    }
    AIM_STRDUP(tuple[0].name , "Entry1", aimInfo, status);
    AIM_STRDUP(tuple[1].name , "Entry2", aimInfo, status);
    AIM_STRDUP(tuple[2].name , "Entry3", aimInfo, status);
    AIM_STRDUP(tuple[0].value, "Value1", aimInfo, status);
    AIM_STRDUP(tuple[1].value, "Value2", aimInfo, status);
    AIM_STRDUP(tuple[2].value, "Value3", aimInfo, status); 
\end{verbatim}
}
\end{frame}

\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~5/10}
  
  {\tiny
\begin{verbatim}
    defval->type       = Tuple;
    defval->dim        = Vector;
    defval->nrow       = 1;
    defval->ncol       = 3;
    defval->vals.tuple = tuple;
  }

  AIM_NOTNULL(*ainame, aimInfo, status);

cleanup:
  return status;
}


int aimUpdateState(void *instStore, void *aimInfo, capsValue *inputs)
{
  int status;
  
  printf("\n");
#ifdef DEBUG
  printf(" myAIM/aimUpdateState        instance = %d!\n",
         aim_getInstance(aimInfo));
#endif
  
  status = aim_newGeometry(aimInfo);
  printf(" myAIM/aimUpdateState aim_newGeometry = %d!\n", status);

  return status;
}
\end{verbatim}
}
\end{frame}

\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~6/10}
  
  \vspace{-0.1in}
  {\tiny
\begin{verbatim}
int aimPreAnalysis(const void *instStore, void *aimInfo, capsValue *inputs)
{
  int        i, n, status = CAPS_SUCCESS;
  const char *name;
  double     mach;
  capsValue  *val;
#ifdef DEBUG
  printf("\n myAIM/aimPreAnalysis instance = %d!\n", aim_getInstance(aimInfo));
#endif

  /* look at the CSM design parameters */
  printf("\n   GeometryIn:\n");
  n = aim_getIndex(aimInfo, NULL, GEOMETRYIN);
  for (i = 0; i < n; i++) {
    status = aim_getName(aimInfo, i+1, GEOMETRYIN, &name);
    if (status != CAPS_SUCCESS) continue;
    status = aim_getValue(aimInfo, i+1, GEOMETRYIN, &val);
    if (status == CAPS_SUCCESS)
      printf("       %d: %s  %d  (%d,%d)\n", i+1, name,
             val->type, val->nrow, val->ncol);
  }
  
  /* look at the CSM output parameters */
  printf("\n   GeometryOut:\n");
  n = aim_getIndex(aimInfo, NULL, GEOMETRYOUT);
  for (i = 0; i < n; i++) {
    status = aim_getName(aimInfo, i+1, GEOMETRYOUT, &name);
    if (status != CAPS_SUCCESS) continue;
    status = aim_getValue(aimInfo, i+1, GEOMETRYOUT, &val);
    if (status == CAPS_SUCCESS)
      printf("       %d: %s  %d  (%d,%d)\n", i+1, name,
             val->type, val->nrow, val->ncol);
  }
\end{verbatim}
}
\end{frame}

\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~7/10}
  
  \vspace{-0.1in}
  {\tiny
\begin{verbatim}
  /* write out input list of values */
  if (inputs != NULL) {
    printf("\n   AnalysisIn:\n");
    for (i = 0; i < NUMINPUT; i++) {
      status = aim_getName(aimInfo, i+1, ANALYSISIN, &name);
      AIM_STATUS(aimInfo, status);
      printf("       %d: %s  %d  (%d,%d) %s\n", i+1, name,
             inputs[i].type, inputs[i].nrow, inputs[i].ncol, inputs[i].units);
    }
    mach = inputs[Mach-1].vals.real;
    if (mach < 0) {
      AIM_ANALYSISIN_ERROR(aimInfo, Mach, "Mach number must be >= 0\n");
      AIM_ADDLINE(aimInfo, "Negative mach = %f is non-physical\n", mach);
      status = CAPS_BADVALUE;
      goto cleanup;
    }
  }
  printf("\n");
  
cleanup:
  return status;
}


int aimExecute(const void *instStor, void *aimInfo, int *state)
{
#ifdef DEBUG
  printf(" myAIM/aimExecute instance = %d!\n", aim_getInstance(aimInfo));
#endif

  *state = 0;
  return CAPS_SUCCESS;
}
\end{verbatim}
}
\end{frame}

\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~8/10}
  
  \vspace{-0.1in}
  {\tiny
\begin{verbatim}
int aimPostAnalysis(void *instStore, void *aimInfo,  int restart, capsValue *inputs)
{
#ifdef DEBUG
  printf(" myAIM/aimPostAnalysis instance = %d!\n", aim_getInstance(aimInfo));
#endif
  
  return CAPS_SUCCESS;
}


int aimOutputs(void *instStore,  void *aimInfo, int index, char **aoname, capsValue *form)
{
  int status = CAPS_SUCCESS;
#ifdef DEBUG
  printf(" myAIM/aimOutputs instance = %d  index  = %d!\n",
         aim_getInstance(aimInfo), index);
#endif
  
  if (index == sqrtNum) {
    *aoname = AIM_NAME(sqrtNum);
    form->type = Double;
  } else {
    printf(" myAIM/aimOutputs: Unknown index = %d!\n", index);
    status = CAPS_BADINDEX;
  }

  return status;
}
\end{verbatim}
}
\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~~9/10}
  
  \vspace{-0.1in}
  {\tiny
\begin{verbatim}
int aimCalcOutput(void *instStore, void *aimInfo, int index, capsValue *val)
{
  int        status = CAPS_SUCCESS;
  double     myNum;
  capsValue  *myVal;
#ifdef DEBUG
  const char *name;

  status = aim_getName(aimInfo, index, ANALYSISOUT, &name);
  printf(" myAIM/aimCalcOutput instance = %d  index = %d %s %d!\n",
         aim_getInstance(aimInfo), index, name, status);
#endif

  if (index == sqrtNum) {
    /* default return */
    val->vals.real = -1;

    /* get the input num */
    status = aim_getValue(aimInfo, num, ANALYSISIN, &myVal);
    if (status != EGADS_SUCCESS) {
        printf("ERROR:: aim_getValue -> status=%d\n", status);
        goto cleanup;
    }

    if ((myVal->type != Double) || (myVal->length != 1)) {
      printf("ERROR:: aim_getValue -> type=%d, len = %d\n",
             myVal->type, myVal->length);
      status = CAPS_BADTYPE;
      goto cleanup;
    }
    
\end{verbatim}
}
\end{frame}


\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example~~10/10}
  {\tiny
\begin{verbatim}
    myNum = myVal->vals.real;
    val->vals.real = sqrt(myNum);
    
  } else {
  
    status = CAPS_BADVALUE;
    
  }

cleanup:
  return status;
}


void aimCleanup(void *instStore)
{
  aimStorage *aimStore = NULL;
#ifdef DEBUG
  printf(" myAIM/aimCleanup!\n");
#endif

  aimStore = (aimStorage *) instStore;
  if (aimStore == NULL) return;
  AIM_FREE(aimStore->tess);
  AIM_FREE(aimStore);
}
\end{verbatim}
}
\end{frame}

\begin{frame}[fragile]
  \FrameTitle{Simple AIM Example -- Python script}
  
 \vspace{-0.085in}
  {\tiny
\begin{verbatim}
import pyCAPS
from   pyOCSM import esp

# Instantiate our CAPS problem "myProblem"
print("Loading file into our Problem")
myProblem = pyCAPS.Problem(problemName="myExample", capsFile="case.csm")

# Load our session aim
myAIM = myProblem.analysis.create(aim = "myAIM")

# Get current value of our first input
value = myAIM.input.num
print("Default num =", value)
myAIM.input.num = 16.0
value = myAIM.input.num
print("Current num =", value)

# AIM autoExecutes

# Get outputs
myGeometry = myProblem.geometry
value = myGeometry.outpmtr["pVol"].value
print(" ")
print("parentVolume =", value)
assert(abs(value - 34.6415248071731) < 1.e-7)
value = myGeometry.outpmtr["cVol"].value
print("childVolume  =", value)
assert(abs(value - 7.296559648508515) < 1.e-7)

value = myAIM.output.sqrtNum
print("sqrtNum      =", value)
assert(value == 4.0)
print(" ")
\end{verbatim}
}
\end{frame}

\begin{frame}
\FrameTitle{Exercises}

\begin{itemize}
\item Note the {\tt test} directory and execute the tests via {\tt make test}
\item Build the AIM and run it
\item Edit {\tt myAIM.c} and set the {\it define} DEBUG
\item Run it again and note the execution sequence
\item In the Python script ask for {\it sqrtNum} before the Volumes\\
Does this new execution sequence  make sense?
\item Change the value of {\it Mach} at the end of {\tt session07.py} and ask for {\it sqrtNum}.
Does the geometry get rebuilt?\\[0.2in]
\item Add your own Analysis input(s) and set a default\textcolor{red}{*}
\item Play around with additional Analysis output(s)\textcolor{red}{*}
\end{itemize}

\vspace{0.1in}
\footnotesize
\textcolor{red}{*} Note: When building up an AIM it is a good idea to start with the bare minimum of inputs and outputs.
This way you can get things up and running and later incrementally add additional functionality.
  
 \end{frame}

\end{document}

