
%\include{figures/plugability-diagram}
\section{Registries}\label{subsec:programmer-registry}\index{registry|textbf}
Each Software Estimation Model used by \nova{} is comprised of multiple components: 
attributes, case-studies, policies, scoring methods, evaluation methods.
All but attributes\footnote{Attributes are stored in the guess DB\subsec{guess-db}} 
are accessible from registeries \subsec{registry}\index{registry}. 
Registries are defined using \textit{defregistry}\index{macros!defregistry} 
See \code{wvu-lib:defregistry}.

\section{Search Engines}
\section{Model}
\subsection{Attributes and Ranges}\label{subsec:attributes-ranges}

Each model has inputs refered to by \nova{} as attributes.  These attributes usually have a range of values.
To manage the attributes anf values, \nova{} uses the guess-db defined in WVU-LIB.
To add your attributes to \nova{}, you register them as
a db default-configuration-list and initialize the guessing db. \code{register-mymodel-attributes}

\textit{register-db-default-configuration-list} takes 2 parameters.
The first parameter is the key to the default-configuration-list,
which can used to overwrite an existing default configuration list.
The second parameter is an \textit{associated list}. The car is the symbol used to refer to the attribute and
the cdr is the range of values for this particular attribute in the form of a \textit{guessable object}.
A \textit{guessable object} is an instance of a struct or class that has the generic function \textit{guess} defined for it.

\lstinputlisting[language=lisp,caption=Registering MyModel Attibutes and Values,label=code:register-mymodel-attributes,firstline=20,lastline=24]
{code/mymodel/model/mymodel-defaults.lisp}

\subsection{Scoring Methods}\label{subsec:programmer-scoring-methods}\index{scoring-methods!programmer|textbf}
Since \textit{scoring methods} usually come directly from the models \subsec{user-scoring-methods}, they are useful 
for two functions in \nova:
\begin{enumerate}
\item reports \subsec{sec:programmer-reports}
\item guiding search engines (via \textit{evaluation methods}\index{evaluation method} \subsec{subsec:programmer-evaluation-methods})
\end{enumerate}

Once \textit{Attributes} and \textit{Ranges} have been defined in \nova{} \subsec{attributes-ranges}, they can be used by \textit{scoring methods}.
\textit{Scoring methods} combine the model attributes into a score defined by the models.

As an example, scoring functions for \textit{MyModel} will be defined.
Even though \textit{MyModel} is simple, it has two scoring methods: \textit{Duration} and \textit{Cost}

\input{calculations/mymodel-duration}
\input{tables/mymodel-psize-duration-lookup}

\lstinputlisting[language=lisp,caption=MyModel: Duration in Lisp,label=code:mymodel:duration,firstline=20,lastline=27]
{code/mymodel/scoring-methods/duration.lisp}

Notice in \code{mymodel:duration}, to reference the current values for an attribute, the function \textit{!}\index{"!} is used.
\textit{!} is function belonging to the guess db.  It guesses a value and stores it.
If you then call \textit{!} again, it will return the same value.  The value will be cleared when \textit{zaps}\index{zaps} is called.
In \nova{}, you don't need to worry about calling \textit{zaps}.  \textit{zaps} is called by \nova{}, but only after all scoring methods have been called.

\input{calculations/mymodel-cost}
\input{tables/mymodel-psize-cost-lookup}

\lstinputlisting[language=lisp,caption=MyModel: Cost in Lisp,label=code:mymodel:cost,firstline=20,lastline=28]
{code/mymodel/scoring-methods/cost.lisp}

Now that both functions have been written in lisp, they can be registered.  There are four parameters to register a scoring funciton.
The first is the key.  This key is how this scoring function fill be refered to.
The second parameter is a name of the function which can be used in reports.
The final two parameters are functions.  Parameter three is the scoring-method function, and the
fourth is the comparison function to be used for this scoring method.
Certain certain search engines and reports need to know how to order results based on scores.

\lstinputlisting[language=lisp,caption=MyModel: Registering Duration,label=code:mymodel:register-duration,firstline=29,lastline=29]
{code/mymodel/scoring-methods/duration.lisp}
\lstinputlisting[language=lisp,caption=MyModel: Registering Cost,label=code:mymodel:register-cost,firstline=30,lastline=30]
{code/mymodel/scoring-methods/cost.lisp}

\subsection{Evaluation Methods}\label{subsec:programmer-evaluation-methods}\index{evaluation-methods!programmer|textbf}
When \nova{} is searching, it needs a special scoring methods, called \textit{evaluation method}.
\glossary{name={evaluation-method},description={Special scoring method used by nova-learn during searching.}}
Evaluation methods are usually defined to combine the standard scoring functions of model.

\lstinputlisting[language=lisp,caption=MyModel: Energy,label=code:mymodel:experiments,firstline=19,lastline=22]
{code/mymodel/evaluation-methods/energy.lisp}\index{MyModel!Energy}

\lstinputlisting[language=lisp,caption=MyModel: Registering Evaluation Methods,label=code:mymodel:register-evaluation-method,firstline=24,lastline=30]
{code/mymodel/evaluation-methods/energy.lisp}

\subsubsection{Evaluation Method Augmentor}

\section{Reports}\label{sec:reports}
\section{Experiments}



\lstinputlisting[language=lisp,caption=MyModel: Experiments,label=code:mymodel:experiments,firstline=19]
{code/mymodel/experiments/experiments.lisp}

\section{Scenarios}\label{subsec:programmer-experiment-scenarios}\index{experiments!scenario}

In \code{mymodel:register-scenario}, \textit{make-experiment-scenario-by-ids} is used.  It is a 
convience constructor. Instead of accepting a \textit{case study} and \textit{policy}, it accepts 
a case-study-id and policy-id.  The appropriate lookup functions are used by the constructor
to retrieve the \textit{case study} and \textit{policy}.

\lstinputlisting[language=lisp,caption=MyModel: Registering Scenarios,label=code:mymodel:register-scenario,firstline=19,lastline=28]
{code/mymodel/experiments/scenarios.lisp}

\subsection{Case Studies}\index{case study}

\textit{Case Studies} are expressed as a list of lists.  The inner lists are composed of the attribute symbol followed by the constraint values.  
For \textit{num}\index{num} valued attributes, the values are minimum value and maximum value.  
For \textit{bag}\index{bag} valued attributes, the values are any allowable value.  
If only value exist in the constraint values, then the value of the attribute will be fixed to that value.

\lstinputlisting[language=lisp,caption=MyModel: Registering Case Studies,label=code:mymodel:register-case-study,firstline=20,lastline=38]
{code/mymodel/case-studies/my-case-studies.lisp}

\subsection{Policies}\index{policy}
\textit{Policies} are expressed as a list of attribute symbols.  When this policy is applied, only the specified attributes 
will be modified during searches.

\lstinputlisting[language=lisp,caption=MyModel: Registering Policies,label=code:mymodel:register-policy,firstline=19,lastline=22]
{code/mymodel/policies/all.lisp}

\section{Treatments}\label{subsec:programmer-experiment-treatments}\index{experiments!treatment|textbf}

The standard \textit{experiment-treatment} is defined with slots for evaluation-method, search-engine,find-best-state-method.
When the treatment is ``applied'' using \textit{apply-treatment}, those values from the slots are passed to \textit{nova-learn}\index{nova-learn}.
See \subsec{programmer-experiment-treatments-apply-treatment} for more information on extending treatments.

\lstinputlisting[language=lisp,caption=MyModel: Registering Treatments,label=code:mymodel:register-treatment,firstline=19]
{code/mymodel/experiments/treatments.lisp}

\subsection{apply-treatment}\label{subsec:programmer-experiment-treatments-apply-treatment}\index{apply-treatment|textbf}

\textit{generate-experiment-data}\index{generate-experiment-data} uses \textit{apply-treatment} to generate a 
\textit{result}\index{result} based on the \textit{treatment}\index{scenario} and \textit{scenario}\index{scenario}.

\textit{apply-treatment} calls \textit{nova-learn} with parameters from the \textit{treatment} and \textit{scenario}.  
To allow treatments to be extendable, the parameters passed to \textit{nova-learn} are retrieved using
five generic functions.  Each generic function accepts two parameters:  treatment and scenario.

\begin{description}
\item[retrieve-evaluation-method] Default: evaluation-method from slot on treatment.
\item[retrieve-search-engine] Default: search-engine from slot on treatment.
\item[retrieve-find-best-state-method] Default: find-best-state-method from slot on treatment.
\item[retrieve-constraints] Default: constraints from case-study on slot of scenario.
\item[retrieve-modifiable-attributes] Default: modifiable-attributes from policy on slot of scenario.
\end{description}
