-

Author: derpycode

muffin.tex

@@ -7794,9 +7794,9 @@ \section{Miscellaneous data processing}
 
 \section{Model ensembles}
 
-The \textbf{muffindata} \textbf{MATLAB} file: \textsf{\footnotesize fun\_make\_ensemble\_2d.m} provides a simple/convenient way of generating ensembles of model experiments. By default, the function is designed for generating 2D ensembels of a first varying parameter vs. a second varying parameter. However, by specifying only a single value of the 2nd (or first) parameter, you'll obtain a 1D ensemble of just a single varuing parameter.
+The \textbf{muffindata} \textbf{MATLAB} file: \textsf{\footnotesize fun\_make\_ensemble\_2d.m} provides a simple/convenient way of generating ensembles of model experiments. By default, the function is designed for generating 2D ensembles of a first varying parameter vs. a second varying parameter. However, by specifying only a single value of the 2nd (or first) parameter, you'll obtain a 1D ensemble of just a single  parameter varying.
 
-Information about how to configure and generate an ensemble is provided as MATLAB help on this function:
+Information about how to configure and generate an ensemble is provided as \textbf{MATLAB} help on this function:
 \vspace{-2mm}
 \begin{verbatim}
 >> help fun_make_ensemble_2d
@@ -7805,29 +7805,74 @@ \section{Model ensembles}
 
 The function \textsf{\footnotesize fun\_make\_ensemble\_2d.m} requires 2 parameters (\textit{strings}) to be passed in the argument list, i.e.:
 \begin{verbatim}
->> plot_timeseries_biogem(PAR1,PAR2)
+>> fun_make_ensemble_2d.m(PAR1,PAR2)
 \end{verbatim}
 
 These are, in order:
 
-\vspace{1mm}
 \begin{enumerate}
-\item \texttt{STR\_TEMPLATE} -- \textit{string} \(\rightarrow\) is the name of the template user-config file (within the \textbf{muffindata} directory) used to generate the ensemble. An example template-file (\texttt{01\_user\_config\_ensemble\_template}) is included in \textbf{muffindata}.
-\item \texttt{STR\_PARAMS} -- \textit{string} \(\rightarrow\)  is the name of the parameter configuration file (omitting the '.dat' extension). The format of this file is provided in the MATLAB help for this function. An example parameter-file (\texttt{01\_user\_config\_params.dat}) is included in \textbf{muffindata}.
+\vspace{1mm}
+\item \texttt{STR\_TEMPLATE} -- \textit{string} \(\rightarrow\) is the name of the template \textit{user-config} file (within the \textbf{muffindata} directory) used to generate the ensemble. 
+\\Note that the \textit{user-config} may already contain a value for the varying parameter(s) -- the automatically-generated parameter values will be appended at the very end of the file, hence over-writing any previous values.
+\vspace{1mm}
+\item \texttt{STR\_PARAMS} -- \textit{string} \(\rightarrow\)  is the name of the parameter configuration file (omitting the '\textsf{\footnotesize .dat}' extension). The format of this file is plain text and takes a '\textsf{\footnotesize .dat}' extension. Example contents for this file are provided in the \textbf{MATLAB} help for this function.
 \end{enumerate}
 \vspace{2mm}
 
-A simple example usage with the files provided would be:
+An example example usage  would be:
 \begin{verbatim}
->> plot_timeseries_biogem('01_user_config_ensemble_template','01_user_config_params')
+>> fun_make_ensemble_2d.m('user_config_template','ensemble_params')
 \end{verbatim}
-which creates a $2\times3$ ensemble (i.e. 6 new user-config files), by modifying the paramater \textit{bg\_ocn\_init\_8} with the vector [0.5 2.0] (i.e. multiplying the default paramater value 2.159E-06 with 0.5 and then with 2.0) and the parameter \textit{bg\_par\_atm\_force\_scale\_val\_3} with the vector [2.0 3.0 10.0]. Other examples are provided in the MATLAB help for this function.
+which creates an ensemble based on the \textit{user-config} file: \textsf{\footnotesize user\_config\_template} (example file name) and with varying parameter values specified in the file: \textsf{\footnotesize ensemble\_params.dat} (example file name).
+
+The \textit{user-config} (and hence experiment names) that are automatically generated end in \textsf{\footnotesize .xy}, where \textsf{\footnotesize x} represents the \(x+1th\) parameter value on the first axis, and \textsf{\footnotesize y} represents the \(y+1th\) parameter value on the second axis (the \textsf{\footnotesize .xy} notation starts counting at \textsf{\footnotesize .00}). For instance, \textsf{\footnotesize .00} would be an experiment taking the first parameter values specified in \textsf{\footnotesize ensemble\_params.dat} for both axes. \textsf{\footnotesize .10} would have the 2nd lister parameter value on the 1st axis, and the 1st lister on the 2nd axis. \textsf{\footnotesize .27} would have the 3rd parameter value on the 1st axis, and 8th listed parameter value on the 2nd axis. etc etc etc
+
+Also in \textbf{muffindata} you can find a BASH shell script for submitting the entire ensemble\footnote{Having first transferred all the \textit{user-config} files to the cluster to an appropriate \textsf{\footnotesize genie-userconfigs} folder} at the command line (within \textsf{\footnotesize genie-main}) -- \textsf{\footnotesize sub\_ens.muffin.sh}. NOTE: you have to specify the experiment parameters of your ensemble (e.g. \textit{base-config} and \textit{user-config} filenames, run duration, etc.) in the BASH file and you should be sure to have compiled the model (by running a brief experiment) with the required \textit{base-config} prior to using \textsf{\footnotesize sub\_ens.muffin.sh}.
+
+The lines requiring editing in \textsf{\footnotesize sub\_ens.muffin.sh} are clearly marked and these instructions are not repeated here.
+
+\newpage 
+
+Note that you may need to re-assigned an 'executable' permission after editing and saving \textsf{\footnotesize sub\_ens.muffin.sh}. To do this, from \textsf{\footnotesize genie-main}:
+\begin{verbatim}
+>> chmod a+x sub_ens.muffin.sh
+\end{verbatim}
+
+\vspace{-2mm}
+\noindent\rule{4cm}{0.5pt}
+\vspace{2mm}
+
+\noindent What do you then 'do' with a whole bunch of experiments with names ending in \textsf{\footnotesize .xy} ... ???
+
+You could of course, pick out individual ensemble member to plot and analyse, referring to the \textsf{\footnotesize ensemble\_params.dat} file where you specified the sequence of parameter values on both axes in order to identify the ensemble member you want. And/or ...
 
+The \textbf{muffindata} \textbf{MATLAB} file: \textsf{\footnotesize fun\_process\_ensemble\_2d.m} provides a simple/convenient way of processing and visualizing ensembles of model experiments.
 
-Also in \textbf{muffindata} you can find a BASH script for submitting the entire ensemble\footnote{Having first transferred all the \textit{user-config} files to the cluster to an appropriate genie-userconfigs folder} at the command line (within \textsf{\footnotesize genie-main}) -- \textsf{\footnotesize sub\_ens.muffin.sh}. NOTE: you have to specify the experiment parameters of your ensemble (e.g. base-config and user-config filenames, run duration etc.) in the BASH file and you should be sure to have compiled the model with the required \textit{base-config} prior to using \textsf{\footnotesize sub\_ens.muffin.sh}. An example BASH script (\textit{sub\_ens.muffin\_LAB\_4.sh}) for the $2\times3$ ensemble created above is included in \textbf{muffindata}. This ensemble can be submitted by typing:
-\\\texttt{\$ ./sub\_ens.muffin\_LAB\_4.sh}\\
-within \textsf{\footnotesize genie-main}.
+Information about how to configure and generate an ensemble is provided as \textbf{MATLAB} help on this function:
+\vspace{-2mm}
+\begin{verbatim}
+>> help fun_process_ensemble_2d
+\end{verbatim}
+\vspace{-2mm}
+
+The function \textsf{\footnotesize fun\_make\_ensemble\_2d.m} requires 3 parameters to be passed in the argument list, i.e.:
+\begin{verbatim}
+>> fun_process_ensemble_2d.m(PAR1,PAR2,PAR3)
+\end{verbatim}
+
+These are, in order:
+
+\begin{enumerate}
+\vspace{1mm}
+\item \texttt{PAR1} -- \textit{string} \(\rightarrow\) is simply the ensemble name, but omitting the \textsf{\footnotesize .xy} numerical code of individual ensemble members). 
+\vspace{1mm}
+\item \texttt{PAR2} -- \textit{number} \(\rightarrow\) is the year of model data to extract. e.g. \texttt{9999.5} for the last year of a 10,000 year long run.
+\vspace{1mm}
+\item \texttt{PAR3} -- \textit{string} \(\rightarrow\) is a name to assign to the output files (e.g. giving you a potentially more meaningful set of filenames than simply re-using \texttt{PAR1}.
+\end{enumerate}
+\vspace{2mm}
 
+\noindent Within the code of \textsf{\footnotesize fun\_process\_ensemble\_2d.m} are instructions/directions as to how to extract specific variables. More advanced usage can statistically compare to data and calculate the goodness of fit of al the ensembles members, and even automatically identify and further process the 'best' (depending on the specific criteria for 'best').
 
 %----------------------------------------------------------------------------------------
 %       CHAPTER X
@@ -13520,6 +13565,67 @@ \subsubsection{Adding (and testing) a basic tracer biogeochemical cycle}
 \end{verbatim}\vspace{-1mm}\normalsize
 (ca. L2961), e.g. following the examples of Fe scavenging and H2S reaction with organic matter (treated as a form of 'scavenging' for simplicity of code structure), plus a corresponding subroutine added in which is the scavenged particulate tracer concentration is calculated and the removal of the corresponding dissolved tracers set.
 
+%------------------------------------------------
+
+\newpage
+
+%------------------------------------------------
+%
+\section{Other Modifications!}
+
+%------------------------------------------------
+%
+\subsection*{Add a new functional type to ECOGEM}\label{functionaltype}
+
+
+\begin{enumerate}[noitemsep]
+
+\vspace{1mm}
+\item First, define the new PFT in:
+\\\textsf{\footnotesize \(\sim\)/cgenie.muffin/genie-ecogem/src/fortran/ecogem\_data.f90}
+
+In the subroutine \textsf{\footnotesize sub\_init\_plankton}, add a set of definitions for a new PFT consistent with the formatting -- the PFT has a name and various true/false statements as to what it does, e.g.
+\small\begin{verbatim}
+if (pft(jp).eq.'new_PFT') then
+          NO3up(jp)       = 0.0
+          Nfix(jp)        = 0.0
+          calcify(jp)     = 0.0
+          silicify(jp)    = 0.0
+          autotrophy(jp)  = 1.0
+          heterotrophy(jp)= 0.0
+          palatability(jp)= 1.0
+\end{verbatim}\normalsize
+
+\vspace{1mm}
+\item Define parameters relevant to the PFT such as size-scaling parameters
+(\texttt{a},\texttt{b},\texttt{c}) for \texttt{vmax}. (See existing manual section for adding parameters.)
+
+\vspace{1mm}
+\item Use the new parameters to update the PFT parameter definitions in
+\textsf{\footnotesize \(\sim\)/cgenie.muffin/genie-ecogem/src/fortran/ecogem\_data.f90}, using the PFT name defined in step 1:
+
+\small\begin{verbatim}
+ ! generic maximum photosynthetic rate
+vmax(iDIC,:)    = (vmaxDIC\_a  + log10(volume(:))) / (vmaxDIC\_b + vmaxDIC\_c
+* log10(volume(:)) + log10(volume(:))**2) * autotrophy(:)
+
+! modify rates for new functional types
+vmax(iDIC,:)    = merge(vmaxDIC\_a\_pft\_newPFT * volume(:) **
+vmaxDIC\_b\_pft\_newPFT,vmax(iDIC,:),pft.eq.'new\_PFT')
+\end{verbatim}\normalsize
+
+\vspace{1mm}
+\item Set up a plankton definition file in
+\textsf{\footnotesize \(\sim\)cgenie.muffin/genie-ecogem/data/input/new\_PFT\_setup.eco} that includes the name of the new PFT defined in step 1 and the cell size.
+
+\end{enumerate}
+
+\vspace{2mm}
+\noindent Note that to date, only the growth rate parameters (\texttt{Vmax} for DIC) have been changed, and this approach has worked. No changes in other parameters,
+specifically for PFTs such as quotas or other nutrient uptake, have been tested but I guess
+it would be similar. Overall, this is a little bit clumsy in that it requires new at
+least 2-3 new parameter definitions for each PFT.
+
 %----------------------------------------------------------------------------------------
 %       CHAPTER -- EXAMPLES
 %----------------------------------------------------------------------------------------