diff --git a/Lectures/L03_Requirements/Requirements.pdf b/Lectures/L03_Requirements/Requirements.pdf
index 68756cdd4595a7d7d565f7131d0ff88e02e2397d..d06da441ca4a778b1f96bbb17860803b05f61e6b 100644
Binary files a/Lectures/L03_Requirements/Requirements.pdf and b/Lectures/L03_Requirements/Requirements.pdf differ
diff --git a/Lectures/L03_Requirements/Requirements.tex b/Lectures/L03_Requirements/Requirements.tex
index 68376b7e74fe77d9d9910c16079c59396b5227ad..8be9a49c93ac588b4ec78ed9e51314721d7107ea 100755
--- a/Lectures/L03_Requirements/Requirements.tex
+++ b/Lectures/L03_Requirements/Requirements.tex
@@ -22,7 +22,7 @@
\usepackage{multicol}
\usepackage{array}
-\bibliographystyle{plainnat}
+\bibliographystyle{plain}
%\usetheme{Iimenau}
@@ -34,7 +34,7 @@
\input{../def-beamer}
-\newcommand{\topic}{03 Requirements DRAFT}
+\newcommand{\topic}{03 Requirements}
\input{../titlepage}
@@ -49,18 +49,15 @@
\bi
\item Administrative details
-\item Questions: project choices, software tools
-\item License and copyright
+\item Questions: project choices?, software tools?
\item Problem statement and example
-\item Motivation
-\begin{itemize}
+\item Software Engineering for Scientific Computing literature
\item Scientific Computing Software Qualities
-\item Challenges to Developing Quality Scientific Software
-\end{itemize}
+\item Motivation: Challenges to Developing Quality Scientific Software
\item Requirements documentation for scientific computing
-\item A new requirements template
+\item A requirements template
\item Advantages of new template and examples
-\item The new template from a software engineering perspective
+\item The template from a software engineering perspective
\item Concluding remarks
\item References
\ei
@@ -72,8 +69,9 @@
\frametitle{Administrative Details}
\bi
-\item Add me to your GitHub repos, my GitHub id is \texttt{smiths}
+\item Add \texttt{smiths} to your GitHub repos
\item Linked-In
+\item \structure{Assign the instructor an issue to review your problem statement}
\ei
\end{frame}
@@ -81,50 +79,150 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{frame}
-\frametitle{Administrative Details: Report Deadlines}
+\frametitle{Administrative Details: Deadlines}
~\newline
\begin{tabular}{l l l}
\textbf{Problem Statement} & Week 02 & Sept 15\\
-System Requirements Specification (SRS) & Week 05 & Oct 4\\
-Verification and Validation Plan & Week 07 & Oct 25\\
-Module Guide (MG) & Week 09 & Nov 8\\
-Module Interface Specification (MIS) & Week 11 & Nov 22\\
+SRS Present & Week 04 & Week of Sept 25\\
+SRS & Week 05 & Oct 4\\
+V\&V Present & Week 06 & Week of Oct 16\\
+V\&V Plan & Week 07 & Oct 25\\
+MG Present & Week 08 & Week of Oct 30\\
+MG & Week 09 & Nov 8\\
+MIS Present & Week 10 & Week of Nov 13\\
+MIS & Week 11 & Nov 22\\
+Impl.\ Present & Week 12 & Week of Nov 27\\
Final Documentation & Week 13 & Dec 6\\
\end {tabular}
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Questions?}
+\begin{itemize}
+\item Questions about project choices?
+\item Questions about software tools?
\bi
-\item The written deliverables will be graded based on the repo contents as of
-11:59 pm of the due date
-\item If you need an extension, please ask
-\item Two days after each major deliverable, your GitHub issues will be due
+\item git?
+\item LaTex?
\ei
+\item Partial tex files in the blank project template
+\item \href{https://gitlab.cas.mcmaster.ca/smiths/cas741/blob/master/BlankProjectTemplate/Doc/ProblemStatement/ProblemStatement.tex}{Problem statement}
+\end{itemize}
+\end{frame}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Problem Statement}
+\bi
+\item Written in LaTeX
+\item Due electronically (on GitLab) by deadline
+\item Comments might be typed directly into your source
+\item For later assignments with LaTeX source, include the LaTeX
+ commands for comments
+\item \textbf{What} problem are you trying to solve?
+\item \textbf{Not how} you are going to solve the problem
+\item Why is this an important problem?
+\item What is the context of the problem you are solving?
+\bi
+\item Who are the stakeholders?
+\item What is the environment for the software?
+\ei
+\item A page description should be sufficient
+\ei
\end{frame}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{frame}
-\frametitle{Administrative Details: Presentations}
+\frametitle{Sample Project Statements}
-~\newline
-\begin{tabular}{l l l}
-SRS Present & Week 04 & Week of Sept 25\\
-V\&V Present & Week 06 & Week of Oct 16\\
-MG Present & Week 08 & Week of Oct 30\\
-MIS Present & Week 10 & Week of Nov 13\\
-Implementation Present & Week 12 & Week of Nov 27\\
-\end {tabular}
+\bi
+\item \href{https://gitlab.cas.mcmaster.ca/ThisTooShallParse/3XA3_CParser}{CParser}
+\item \href{https://gitlab.cas.mcmaster.ca/theateam/FloppyFishGroup}{FloppyFish}
+\item
+ \href{https://gitlab.cas.mcmaster.ca/screenholders/screenholders}{Screenholders}
+\item Template in repo
+\ei
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{SE For SC Literature}
+\begin {itemize}
+
+\item CAS 741 process is document driven, adapted
+from the waterfall model~\cite{GhezziEtAl2003, VanVliet2000}
+\item Many say a document driven process is not used by, nor suitable for,
+scientific software.
\bi
-\item Tentative dates
-\item Specific schedule depends on final class registration and need
-\item Informal presentations with the goal of improving everyone's written
- deliverables
+\item Scientific developers naturally use an agile
+ philosophy~\cite{AckroydEtAl2008, CarverEtAl2007, EasterbrookAndJohns2009, Segal2005},
+\item or an amethododical process~\cite{Kelly2013}
+\item or a knowledge acquisition driven process~\cite{Kelly2015}.
\ei
+\item Scientists do not view rigid, process-heavy approaches,
+ favorably~\cite{CarverEtAl2007}
+\item Reports for each stage of development are counterproductive~\cite[p.~373]{Roache1998}
+\item Up-front requirements are
+impossible~\cite{CarverEtAl2007, SegalAndMorris2008}
+\item \structure{What are some arguments in favour of a rational document driven
+ process?}
+\end{itemize}
\end{frame}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Counter Arguments}
+
+\begin {itemize}
+
+\item Just because document driven is not used, does not mean it will not work
+\item Documentation provides many
+benefits~\cite{Parnas2010}:
+\bi
+\item easier reuse of old designs
+\item better communication about requirements
+\item more useful design reviews
+\item easier integration of separately
+written modules
+\item more effective code inspection
+\item more effective testing
+\item more efficient corrections and improvements.
+\ei
+\item Actually faking a rational design process
+\item Too complex for up-front requirements sounds like an excuse
+\bi
+\item Laws of physics/science slow to change
+\item Often simple design patterns
+\item Think program family, not individual member
+\ei
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Definition of Software Qualities}
+
+\begin{itemize}
+\item Measures of the excellence or worth of a software product (code or document) or process
+with respect to some aspect
+\item \structure{What are some important aspects (qualties) for scientific softwarwe?}
+\item User Satisfaction = The Important Qualities are High + Within Budget
+\end{itemize}
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{frame}
@@ -165,6 +263,293 @@ Implementation Present & Week 12 & Week of Nov 27\\
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{frame}
+\frametitle{Correctness Versus Reliability Versus Robustness}
+
+What is the difference between these 3 qualities?\\
+~\\
+Can you assess correctness without a requirements specification?
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Correctness}
+
+\begin{itemize}
+\item A software product is correct if it satisfies its requirements specification
+\item Correctness is extremely difficult to achieve because
+\begin{itemize}
+\item The requirements specification may be imprecise, ambiguous, inconsistent,
+ based on incorrect knowledge, or nonexistent
+\item Requirements often compete with each other
+\item It is virtually impossible to produce ``bug-free'' software
+\item It is very difficult to verify or measure correctness
+\end{itemize}
+\item If the requirements specification is formal, correctness can in theory and
+ possibly in practise be
+\begin{itemize}
+\item Mathematically defined
+\item Proven by mathematical proof
+\item Disproven by counterexample
+\end{itemize}
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Reliability}
+
+\begin{itemize}
+\item A software product is reliable if it usually does what is intended to do
+\item Correctness is an absolute quality, while reliability is a relative quality
+\item A software product can be both reliable and incorrect
+\item Reliability can be statistically measured
+\item Software products are usually much less reliable than other engineering
+ products
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Robustness}
+
+\begin{itemize}
+\item A software product is robust if it behaves reasonably even in
+ unanticipated or exceptional situations
+% example of saving a file and power is lost
+\item A correct software product need not be robust
+\begin{itemize}
+\item Correctness is accomplished by satisfying requirements
+\item Robustness is accomplished by satisfying unstated requirements
+\end{itemize}
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Question on Correctness. Reliability and Robustness}
+
+Reliable programs are a superset of correct programs AND robust programs are a
+superset of reliable programs. Is this statement True or False?
+\begin{enumerate}[A.]
+\item True
+\item False %answer - robust programs may or may not be correct or reliable
+\end{enumerate}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Performance}
+
+What are some ways you could measure software performance?\\
+~\\
+What are some ways you could specify performance requirements to make them
+unambiguous and verifiable?
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Performance}
+
+\begin{itemize}
+\item The performance of a computer product is the efficiency with which the
+ product uses its resources (memory, time, communication)
+\item Performance can be evaluated in three ways
+\begin{itemize}
+\item Empirical measurement
+\item Analysis of an analytic model
+\item Analysis of a simulation model
+\end{itemize}
+\item Poor performance often adversely affects the usability and scalability of
+ the product
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Usability}
+
+What are some examples of excellent usability?\\
+~\\
+When you go to a friend's house, you can likely operate their microwave without
+reading the manual. What did human factors engineers do to make this possible?
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Usability}
+
+\begin{itemize}
+\item The usability of a software product is the ease with which a typical human
+ user can use the product
+\item Usability depends strongly on the capabilities and preferences of the user
+\item The user interface of a software product is usually the principle factor
+ affecting the product's usability
+\item Human computer interaction (HCI) is a major interdisciplinary subject
+ concerned with understanding and improving interaction between humans and
+ computers
+\end{itemize}
+% talk about IBM usability lab and other things that Muir mentioned
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Verifiability}
+
+\begin{itemize}
+\item The verifiability of a software product is the ease with which the
+ product's properties (such as correctness and performance) can be verified
+\item Verifiability can be both an internal and an external quality
+%\item What is the relationship between verifiability and correctness?
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Maintainability}
+
+\begin{itemize}
+\item The maintainability of a software product is the ease with which the
+ product can be modified after its initial release
+\item Maintenance costs can exceed 60\% of the total cost of the software product
+\item There are three main categories of software maintenance
+\begin{enumerate}
+\item Corrective: Modifications to fix residual and introduced errors
+\item Adaptive: Modifications to handle changes in the environment in which the product is used
+\item Perfective: Modifications to improve the qualities of the software
+\end{enumerate}
+\item Software maintenance can be divided into two separate qualities
+\begin{enumerate}
+\item Repairability: The ability to correct defects
+\item Evolvability: The ability to improve the software and to keep it current
+\end{enumerate}
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Maintainability}
+
+What do software developers do to promote maintainability?
+
+% documentation, traceability, separation of concerns, modularity, design for
+% change, design for generality
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Reusability}
+
+What are the advantages of reusing code?\\
+~\\
+Why doesn't it happen more often?
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Reusability}
+
+\begin{itemize}
+\item A software product or component is reusable if it can be used to create a
+ new product
+\item Reuse comes in two forms
+\begin{enumerate}
+\item Standardized, interchangeable parts
+\item Generic, instantiable components
+\end{enumerate}
+\item Reusability is a bigger challenge in software engineering than in other
+ areas of engineering
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Portability}
+
+\begin{itemize}
+\item A software product is portable if it can run in different environments
+\item The environment for a software product includes the hardware platform, the
+ operating system, the supporting software and the user base
+\item Since environments are constantly changing, portability is often crucial
+ to the success of a software product
+\item Some software such as operating systems and compilers, is inherently
+ machine specific
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Understandability}
+
+\begin{itemize}
+\item The understandability of a software product is the ease with which the
+ requirements, design, implementation, documentation, etc. can be understood
+\item Understandability is an internal quality that has an impact on other
+ qualities such as verifiability, maintainability, and reusability
+\item There is often a tension between understandability and the performance of
+ a software product
+\item Some useful software products completely lack understandability
+ (e.g. those for which the source code is lost)
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Relationship between Qualities}
+
+Draw a diagram showing the relationships between the various software qualities
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{frame}
+\frametitle{Measurement of Quality}
+
+\begin{itemize}
+\item A software quality is only important if it can be measured - without
+ measurement there is no basis for claiming improvement
+\item A software quality must be precisely defined before it can be measured
+\item Most software qualities do not have universally accepted
+\item Can you directly measure maintainability?
+\item How might you measure maintainability?
+\end{itemize}
+
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\begin{frame}
\frametitle{Problems with Developing Quality Scientific Computing Software}
@@ -193,7 +578,7 @@ programs}}
\begin{frame}
-\frametitle{Adapt Software Engineering Methodologies}
+\frametitle{Adapt Software Engineering Methods}
\begin{itemize}
@@ -249,7 +634,6 @@ programs}}
\begin{itemize}
\item Background on requirements elicitation, analysis and documentation
-\item Tabular expressions
\item Why requirements analysis for engineering computation?
\item System Requirements Specification and template for beam analysis software
@@ -304,45 +688,6 @@ programs}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\begin{frame}
-\frametitle{Tabular Expressions}
-
-\begin{flushleft}
-\scalebox{0.75}{
-\begin{tabular}{||r|p{6cm}||}
-\hhline{=|=}
-Composition rule & $\cup_{i=1}^{4} H_2[i] \cap (\cap_{j=1}^{2} H_1[j] ~;~ G[i,j])$ \\
-\hhline{=|=}
-\end{tabular}
-}
-\end{flushleft}
-
-%\begin{center}
-\begin{tabular}{|l|p{0.3cm}|l|l|}
-\multicolumn{4}{c}{} \\
-\multicolumn{2}{c}{} & \multicolumn{2}{>{\large}c}{$H_1$} \\
-\hhline{|~|~|-|-|}
-\multicolumn{2}{c|}{} & $S_{GET}'\cup =$ & $ErrorMsg'+=$ \\
-\hhline{|~|~|-|-|}
-\multicolumn{4}{c}{} \\
-\hhline{|-|~|-|-|}
-$x_1 < 0$ & & $\emptyset$ & $InvalidInput\_x_1$ \\
-\hhline{|-|~|-|-|}
-$0 \le x_1 < min_d$ & & $\emptyset$ & $x_1\_TooSmall$ \\
-\hhline{|-|~|-|-|}
-$x_1 > max_d$ & & $\emptyset$ & $x_1\_TooLarge$ \\
-\hhline{|-|~|-|-|}
-$min_d \le x_1 \le max_d$ & & $\{@{x_1}\}$ & $NULL$ \\
-\hhline{|-|~|-|-|}
-\multicolumn{2}{c}{} & \multicolumn{2}{r}{$\land ChangeOnly(S_{GET}, ErrorMsg)$}\\
-\multicolumn{2}{>{\large}c}{$H_2$} & \multicolumn{2}{>{\large}c}{$G$} \\
-\end{tabular}
-%\end{center}
-
-\end{frame}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
\begin{frame}
\frametitle{Why Requirements Analysis?}
%\begin{figure}
@@ -612,7 +957,7 @@ PS1.a & $L$ & & &... & &... & & & $\surd$ & ... & & ... & ... \\
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\frame{\frametitle{More on the New Template}
+\frame{\frametitle{More on the Template}
\begin{itemize}%[<+-| alert@+>]%[iacolor=gray]
\item Why a new template?
\item The new template
@@ -787,6 +1132,16 @@ displacement of the system, or mathematically $\delta U = 0$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{frame}
+\frametitle{Examples}
+\begin{itemize}
+\item \href{https://github.com/smiths/swhs}{Solar Water Heating System}
+\item \href{https://github.com/JacquesCarette/literate-scientific-software/tree/master/CaseStudies/glass/Documentation/SRS}{GlassBR}
+\end{itemize}
+\end{frame}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\begin{frame}
\frametitle{Concluding Remarks}
\begin{itemize}