Fix for #110 and #30:

* Add global AlgorithmParameters
* Clarify what happens when in a repeated task
* Explicitly call out the 'seed' parameter.

specification/level-1-version-4/sources/sedml.tex

@@ -12,13 +12,14 @@ \subsection{\element{SED-ML} top level element}
 	\item \DataGenerator (for the definition of post-processing),
 	\item \hyperref[class:output]{Output} (for the specification of plots and reports).
 	\item \hyperref[class:style]{Style} \changed{(for the specification of plot element styles)}.
+	\item \AlgorithmParameter \changed{(for the definition of global algorithm parameters)}.
 \end{itemize}
 
 A SED-ML document needs to have the SED-ML namespace defined through the mandatory \hyperref[sec:xmlns]{\element{xmlns}} attribute. In addition, the SED-ML \hyperref[sec:level]{\element{level}} and \hyperref[sec:version]{\element{version}} attributes are required.
 
-The root element of each SED-ML XML file is the \code{sedML} element, encoding \hyperref[sec:level]{\element{level}} and \hyperref[sec:version]{\element{version}} of the file, and setting the necessary namespaces. Nested inside the \code{sedML} element are the six optional lists serving as containers for the encoded information: \hyperref[class:listOfDataDescriptions]{\element{listOfDataDescriptions}} for all external data, \hyperref[class:listOfModels]{\element{listOfModels}} for all models, \hyperref[class:listOfSimulations]{\element{listOfSimulations}} for all simulations, \hyperref[class:listOfTasks]{\element{listOfTasks}} for all tasks, \hyperref[class:listOfDataGenerators]{\element{listOfDataGenerators}} for all post-processing definitions, \hyperref[class:listOfOutputs]{\element{listOfOutputs}} for all output definitions, \changed{and \ListOfStyles for all style definitions}.
+The root element of each SED-ML XML file is the \code{sedML} element, encoding \hyperref[sec:level]{\element{level}} and \hyperref[sec:version]{\element{version}} of the file, and setting the necessary namespaces. Nested inside the \code{sedML} element are the six optional lists serving as containers for the encoded information: \hyperref[class:listOfDataDescriptions]{\element{listOfDataDescriptions}} for all external data, \hyperref[class:listOfModels]{\element{listOfModels}} for all models, \hyperref[class:listOfSimulations]{\element{listOfSimulations}} for all simulations, \hyperref[class:listOfTasks]{\element{listOfTasks}} for all tasks, \hyperref[class:listOfDataGenerators]{\element{listOfDataGenerators}} for all post-processing definitions, \hyperref[class:listOfOutputs]{\element{listOfOutputs}} for all output definitions, \changed{\ListOfStyles for all style definitions. and \ListOfAlgorithmParameters for parameters that apply to processing this SED-ML file as a whole}.
 
-\sedfig[width=0.76\textwidth]{images/uml/sed-ml}{The SED-ML class}{fig:sed-mlMain}
+\sedfig[width=0.7\textwidth]{images/uml/sed-ml}{The SED-ML class}{fig:sed-mlMain}
 
 
 The basic XML structure of a SED-ML file is shown in listing \vref{lst:sedmlRoot}.
@@ -48,6 +49,9 @@ \subsection{\element{SED-ML} top level element}
 	<listOfStyles>
 		[DEFINITION OF STYLES]
 	</listOfStyles>
+	<listOfAlgorithmParameters>
+		[PARAMETERS TO APPLY TO THE ENTIRE SIMULATION PROCESS]
+	</listOfAlgorithmParameters>
 </sedML>
 \end{myXmlLst}
 
@@ -73,7 +77,7 @@ \subsubsection{\element{version}}
 % ~~~ LIST OF DATA DESCRIPTIONS ~~~
 \subsubsection{\element{listOfDataDescriptions}}
 \label{class:listOfDataDescriptions}
-In order to reference data in a simulation experiment, the data files along with a description on how to access such files and what information to extract from them have to be defined. The \hyperref[class:sed-ml]{SED-ML document} uses the \concept{\element{listOfDataDescriptions}} container to define \hyperref[class:dataDescription]{DataDescription}s for referencing external data (\fig{sed-mlMain}). The \concept{\element{listOfDataDescriptions}} is optional and may contain zero to many \hyperref[class:dataDescription]{DataDescriptions}.
+In order to reference data in a simulation experiment, the data files along with a description on how to access such files and what information to extract from them have to be defined. The \hyperref[class:sed-ml]{SED-ML document} uses the \concept{\element{listOfDataDescriptions}} container to define \hyperref[class:dataDescription]{DataDescription}s for referencing external data (\fig{sed-mlMain}). The \concept{\element{listOfDataDescriptions}} is optional and may contain zero or more \hyperref[class:dataDescription]{DataDescriptions}.
 
 \lsttext{listOfDataDescriptions}{listOfDataDescriptions}
 
@@ -103,7 +107,7 @@ \subsubsection{\element{listOfDataDescriptions}}
 % ~~~ LIST OF MODELS ~~
 \subsubsection{\element{listOfModels}}
 \label{class:listOfModels}
-The models used in a simulation experiment are defined in the \concept{\element{listOfModels}} container (\fig{sed-mlMain}). The \concept{\element{listOfModels}} is optional and may contain zero to many \Models. However, if a \hyperref[class:sed-ml]{SED-ML document} contains one or more \hyperref[class:abstractTask]{Tasks}, at least one \Model must be defined to which the \hyperref[class:abstractTask]{Task} elements refer (see Section~\ref{sec:modelReference}).
+The models used in a simulation experiment are defined in the \concept{\element{listOfModels}} container (\fig{sed-mlMain}). The \concept{\element{listOfModels}} is optional and may contain zero or more \Models. However, if a \hyperref[class:sed-ml]{SED-ML document} contains one or more \hyperref[class:abstractTask]{Tasks}, at least one \Model must be defined to which the \hyperref[class:abstractTask]{Task} elements refer (see Section~\ref{sec:modelReference}).
 
 \lsttext{listOfModels}{listOfModels}
 
@@ -120,7 +124,7 @@ \subsubsection{\element{listOfModels}}
 % ~~~ LIST OF SIMULATIONS ~~
 \subsubsection{\element{listOfSimulations}}
 \label{class:listOfSimulations}
-The \concept{\element{listOfSimulations}} element is the container for \Simulation descriptions (\fig{sed-mlMain}). The \concept{\element{listOfSimulations}} is optional and may contain zero to many \Simulations. However, if the \hyperref[class:sed-ml]{SED-ML document} contains one or more \hyperref[class:abstractTask]{Tasks}, at least one \Simulation element must be defined to which the \hyperref[class:abstractTask]{Task} elements refer (see Section \ref{sec:simulationReference}).
+The \concept{\element{listOfSimulations}} element is the container for \Simulation descriptions (\fig{sed-mlMain}). The \concept{\element{listOfSimulations}} is optional and may contain zero or more \Simulations. However, if the \hyperref[class:sed-ml]{SED-ML document} contains one or more \hyperref[class:abstractTask]{Tasks}, at least one \Simulation element must be defined to which the \hyperref[class:abstractTask]{Task} elements refer (see Section \ref{sec:simulationReference}).
 
 \lsttext{listOfSimulations}{listOfSimulation}
 \begin{myXmlLst}{The SED-ML \element{listOfSimulations} element, containing two simulation setups}{lst:listOfSimulations}
@@ -137,7 +141,7 @@ \subsubsection{\element{listOfSimulations}}
 % ~~~ LIST OF TASKS ~~~
 \subsubsection{\element{listOfTasks}}
 \label{class:listOfTasks}
-The \concept{\element{listOfTasks}} element contains the defined \hyperref[class:task]{tasks} for the simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfTasks}} is optional and may contain zero to many tasks, each of which is an instance of a subclass of \AbstractTask.
+The \concept{\element{listOfTasks}} element contains the defined \hyperref[class:task]{tasks} for the simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfTasks}} is optional and may contain zero or more tasks, each of which is an instance of a subclass of \AbstractTask.
 
 \lsttext{listOfTasks}{listOfTasks}
 \begin{myXmlLst}{The SED-ML \code{listOfTasks} element, defining one task}{lst:listOfTasks}
@@ -151,7 +155,7 @@ \subsubsection{\element{listOfTasks}}
 % ~~~ LIST OF DATA GENERATORS ~~~
 \subsubsection{\element{listOfDataGenerators}}
 \label{class:listOfDataGenerators}
-The \concept{\element{listOfDataGenerators}} container holds the \hyperref[class:dataGenerator]{dataGenerator} definitions of a simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfDataGenerators}} is optional and in general may contain zero to many \DataGenerators.
+The \concept{\element{listOfDataGenerators}} container holds the \hyperref[class:dataGenerator]{dataGenerator} definitions of a simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfDataGenerators}} is optional and in general may contain zero or more \DataGenerators.
 
 In SED-ML, all variable and parameter values used in the \hyperref[class:output]{Output} class need to be defined as a \DataGenerator beforehand.
 
@@ -172,7 +176,7 @@ \subsubsection{\element{listOfDataGenerators}}
 % ~~ LIST OF OUTPUTS ~~~
 \subsubsection{\element{listOfOutputs}}
 \label{class:listOfOutputs}
-The \concept{\element{listOfOutputs}} container holds the \hyperref[class:output]{Output} definitions of a simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfOutputs}} is optional and may contain zero to many outputs.
+The \concept{\element{listOfOutputs}} container holds the \hyperref[class:output]{Output} definitions of a simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfOutputs}} is optional and may contain zero or more outputs.
 
 \lsttext{listOfOutputs}{listOfOutputs}
 \begin{myXmlLst}{The \concept{listOfOutput} element}{lst:listOfOutputs}
@@ -191,10 +195,10 @@ \subsubsection{\element{listOfOutputs}}
 % ~~ LIST OF STYLES ~~~
 \subsubsection{\element{listOfStyles}}
 \label{class:listOfStyles}
-The \concept{\element{listOfStyles}} container holds the \Style definitions of a simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfStyles}} is optional and may contain zero to many styles.
+The \concept{\element{listOfStyles}} container holds the \Style definitions of a simulation experiment (\fig{sed-mlMain}). The \concept{\element{listOfStyles}} is optional and may contain zero or more styles.
 
 \lsttext{listOfStyles}{listOfStyles}
-\begin{myXmlLst}{The \concept{listOfStyle} element}{lst:listOfStyles}
+\begin{myXmlLst}{The \concept{listOfStyles} element}{lst:listOfStyles}
 <listOfStyles>
 	<style id="redline">
 		[STYLE DEFINITION FOLLOWING]
@@ -205,3 +209,17 @@ \subsubsection{\element{listOfStyles}}
 </listOfStyles>
 \end{myXmlLst}
 \end{blockChanged}
+
+\begin{blockChanged}
+% ~~ LIST OF ALGORITHM PARAMETERS ~~~
+\subsubsection{\element{listOfAlgorithmParameters} (global)}
+\label{class:globalListOfAlgorithmParameters}
+The \concept{\element{listOfAlgorithmParameters}} container holds the \AlgorithmParameter objects that apply globally.  This can include parameters like a seed (\code{KISAO:0000488}) that apply to the simulation experiment as a whole, as well as algorithm parameters that might apply to all tasks of a particular type, such as the absolute tolerance (\code{KISAO:0000211}).  If an \AlgorithmParameter is defined for a particular \Simulation, it will take precedent over any global \AlgorithmParameter with the same KiSAO ID.  The \concept{\element{listOfAlgorithmParameters}} is optional and may contain zero or more parameters.
+
+\begin{myXmlLst}{The global \concept{listOfAlgorithParameters} element}{lst:globalListOfAlgorithmParameters}
+<listOfAlgorithmParameters>
+	<algorithmParameter name="seed" kisaoID="KISAO:0000211" value="23"/> 
+	<algorithmParameter name="absolute tolerance" kisaoID="KISAO:0000488" value="1001"/> 
+</listOfAlgorithmParameters>
+\end{myXmlLst}
+\end{blockChanged}

specification/level-1-version-4/sources/simulation.tex

@@ -147,9 +147,13 @@ \subsubsection{\element{AlgorithmParameter}}
 \label{class:algorithmParameter}
 The \concept{AlgorithmParameter} class allows to parameterize a particular simulation \hyperref[class:algorithm]{algorithm}. The set of possible parameters for a particular instance is determined by the algorithm that is referenced by the \element{kisaoID} of the enclosing \hyperref[class:algorithm]{algorithm} element (\fig{simulation}). Parameters of simulation algorithms are unambiguously referenced by the mandatory \hyperref[sec:kisaoid]{\element{kisaoID}} attribute. Their value is set in the mandatory \hyperref[sec:algorithmParameterValue]{\element{value}} attribute.  \changed{An \AlgorithmParameter may also have child \AlgorithmParameter elements through a \ListOfAlgorithmParameters.}
 
+\changed{Any \AlgorithmParameter defined in a \Simulation overrides any global \AlgorithmParameter defined in the \SedDocument.  And in the reverse, any \AlgorithmParameter left undefined in a \Simulation may be defined by a global \AlgorithmParameter element.}
+
+\changed{NOTE:  the global \ListOfAlgorithmParameters was added to SED-ML in \currentLV.  As such, the only place to define a random seed (\code{KISAO:0000211)} for the simulation experiment as a whole in previous versions was in a \Simulation, which might be part of a \RepeatedTask.  Rather than indicating that each repeat was to receive the same seed, resulting in identical traces, users would generally use the 'seed' parameter to indicate that the experiment as a whole was to be replicable from one run to the next.  Current users of SED-ML should use a global \AlgorithmParameter for this purpose, but older versions or older files may use the previous scheme.}
 
 \paragraph*{\element{value}}
-The attribute \element{value} of type \element{string} should contain a value that makes sense for the \element{kisaoID} in question:  if the KiSAO term is a value, the string should contain a number; if the KiSAO term is a Boolean, the string should contain the string \val{true} or \val{false}, etc.
+\label{sec:algorithmParameterValue}
+The \concept{\element{value}} sets the value of the \hyperref[class:algorithmParameter]{AlgorithmParameter}.  For XML purposes, it is of type \element{string}, but should contain a value that makes sense for the \element{kisaoID} in question:  if the KiSAO term is a value, the string should contain a number; if the KiSAO term is a Boolean, the string should contain the string \val{true} or \val{false}, etc.
 
 \begin{myXmlLst}{The SED-ML \concept{\code{algorithmParameter}} element setting the parameter value for the simulation algorithm. \code{KISAO:0000032} refers to the \emph{explicit fourth-order Runge-Kutta method}; \code{KISAO:00000211} refers to the \emph{absolute tolerance}.}{lst:algorithmParameter}
 <algorithm kisaoID="KISAO:0000032"> 
@@ -197,7 +201,4 @@ \subsubsection{\element{AlgorithmParameter}}
 \end{blockChanged}
 
 
-\paragraph*{\element{value}}
-\label{sec:algorithmParameterValue}
-The \concept{\element{value}} sets the value of the \hyperref[class:algorithmParameter]{AlgorithmParameter}.
 

specification/level-1-version-4/sources/task.tex

@@ -65,9 +65,17 @@ \subsubsection{\element{Repeated Task}}
 
 The order of activities within each iteration of a \concept{RepeatedTask} is as follows:
 \begin{itemize} 
-	\item The \Model is reset if specified by the \hyperref[sec:resetModel]{\element{resetModel}} attribute. 
-	\item Any changes to the model specified by \hyperref[class:setValue]{SetValue} objects in the \hyperref[sec:changesRepeatedTask]{\element{listOfChanges}} are applied to the \Model. 
-	\item Finally, all \hyperref[class:subTask]{{subTasks}} in the \hyperref[class:listOfSubTasks]{\element{listOfSubtasks}} are executed in the order specified by their \hyperref[sec:subTaskOrder]{\element{order}} element.
+        \item \changed{Any \AlgorithmParameter children of the associated \Simulation are applied (with the possible exception of the \code{seed}; see Section \ref{class:algorithmParameter}).}
+	\item The \changed{entire} \Model state is reset if specified by the \hyperref[sec:resetModel]{\element{resetModel}} attribute.
+	\item Any changes to the model specified by \hyperref[class:setValue]{SetValue} objects in the \hyperref[sec:changesRepeatedTask]{\element{listOfChanges}} are applied to the \Model.
+\end{itemize}
+
+\changed{Then, for each \SubTask child of the \RepeatedTask, in the order specified by its \hyperref[sec:subTaskOrder]{\element{order}} attribute:}
+\begin{itemize}
+        \item \changed{Any \AlgorithmParameter of the associated \Simulation are applied.}
+        \item \changed{Any \SetValue children of the \SubTask are applied to the relevant \Model.}
+        \item \changed{The referenced \Task of the \SubTask is executed.}
+
 \end{itemize}