diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..17d68a5 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.vtk filter=lfs diff=lfs merge=lfs -text diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f9ea0ed --- /dev/null +++ b/.gitignore @@ -0,0 +1,279 @@ +## Core latex/pdflatex auxiliary files: +*.aux +*.lof +*.log +*.lot +*.fls +*.out +*.toc +*.fmt +*.fot +*.cb +*.cb2 +.*.lb + +## Intermediate documents: +*.dvi +*.xdv +*-converted-to.* +# these rules might exclude image files for figures etc. +# *.ps +# *.eps +# *.pdf + +## Generated if empty string is given at "Please type another file name for output:" +.pdf + +## Bibliography auxiliary files (bibtex/biblatex/biber): +*.bbl +*.bcf +*.blg +*-blx.aux +*-blx.bib +*.run.xml + +## Build tool auxiliary files: +*.fdb_latexmk +*.synctex +*.synctex(busy) +*.synctex.gz +*.synctex.gz(busy) +*.pdfsync + +## Build tool directories for auxiliary files +# latexrun +latex.out/ + +## Auxiliary and intermediate files from other packages: +# algorithms +*.alg +*.loa + +# achemso +acs-*.bib + +# amsthm +*.thm + +# beamer +*.nav +*.pre +*.snm +*.vrb + +# changes +*.soc + +# comment +*.cut + +# cprotect +*.cpt + +# elsarticle (documentclass of Elsevier journals) +*.spl + +# endnotes +*.ent + +# fixme +*.lox + +# feynmf/feynmp +*.mf +*.mp +*.t[1-9] +*.t[1-9][0-9] +*.tfm + +#(r)(e)ledmac/(r)(e)ledpar +*.end +*.?end +*.[1-9] +*.[1-9][0-9] +*.[1-9][0-9][0-9] +*.[1-9]R +*.[1-9][0-9]R +*.[1-9][0-9][0-9]R +*.eledsec[1-9] +*.eledsec[1-9]R +*.eledsec[1-9][0-9] +*.eledsec[1-9][0-9]R +*.eledsec[1-9][0-9][0-9] +*.eledsec[1-9][0-9][0-9]R + +# glossaries +*.acn +*.acr +*.glg +*.glo +*.gls +*.glsdefs +*.lzo +*.lzs + +# uncomment this for glossaries-extra (will ignore makeindex's style files!) +# *.ist + +# gnuplottex +*-gnuplottex-* + +# gregoriotex +*.gaux +*.gtex + +# htlatex +*.4ct +*.4tc +*.idv +*.lg +*.trc +*.xref + +# hyperref +*.brf + +# knitr +*-concordance.tex +# TODO Comment the next line if you want to keep your tikz graphics files +*.tikz +*-tikzDictionary + +# listings +*.lol + +# luatexja-ruby +*.ltjruby + +# makeidx +*.idx +*.ilg +*.ind + +# minitoc +*.maf +*.mlf +*.mlt +*.mtc[0-9]* +*.slf[0-9]* +*.slt[0-9]* +*.stc[0-9]* + +# minted +_minted* +*.pyg + +# morewrites +*.mw + +# nomencl +*.nlg +*.nlo +*.nls + +# pax +*.pax + +# pdfpcnotes +*.pdfpc + +# sagetex +*.sagetex.sage +*.sagetex.py +*.sagetex.scmd + +# scrwfile +*.wrt + +# sympy +*.sout +*.sympy +sympy-plots-for-*.tex/ + +# pdfcomment +*.upa +*.upb + +# pythontex +*.pytxcode +pythontex-files-*/ + +# tcolorbox +*.listing + +# thmtools +*.loe + +# TikZ & PGF +*.dpth +*.md5 +*.auxlock + +# todonotes +*.tdo + +# vhistory +*.hst +*.ver + +# easy-todo +*.lod + +# xcolor +*.xcp + +# xmpincl +*.xmpi + +# xindy +*.xdy + +# xypic precompiled matrices and outlines +*.xyc +*.xyd + +# endfloat +*.ttt +*.fff + +# Latexian +TSWLatexianTemp* + +## Editors: +# WinEdt +*.bak +*.sav + +# Texpad +.texpadtmp + +# LyX +*.lyx~ + +# Kile +*.backup + +# gummi +.*.swp + +# KBibTeX +*~[0-9]* + +# TeXnicCenter +*.tps + +# auto folder when using emacs and auctex +./auto/* +*.el + +# expex forward references with \gathertags +*-tags.tex + +# standalone packages +*.sta + +# Makeindex log files +*.lpz + +# DS_Store file from Mac computers +.DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..742b5c9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +Open source projects should include a Contributing file that describes how someone in the community can contribute to the project. The Mozilla Science Lab has an article on [Wrangling Web Contributions: How to Build a CONTRIBUTING.md](https://mozillascience.github.io/working-open-workshop/contributing/) \ No newline at end of file diff --git a/CodeOfConduct.md b/CodeOfConduct.md new file mode 100644 index 0000000..a231ddd --- /dev/null +++ b/CodeOfConduct.md @@ -0,0 +1,4 @@ +You should incorporate a [code of +conduct](https://opensource.guide/code-of-conduct/) into your project. Some +potential codes of conduct options include the [open code of conduct +page](https://github.com/todogroup/opencodeofconduct) and the [Contributor Covenant](https://www.contributor-covenant.org/). \ No newline at end of file diff --git a/ExceptionsGranted.md b/ExceptionsGranted.md new file mode 100644 index 0000000..6206954 --- /dev/null +++ b/ExceptionsGranted.md @@ -0,0 +1,6 @@ +This file is entirely capstone specific. (It would not exist in a project +outside the context of this course.) If your project is not suited to the +standard template for folder structure and naming, you should discuss this with +the course instructor. Assuming an exception is granted, you should record the +details of the exception in this file. This will allow the TAs and course +instructor to quickly review the exceptions, especially in advance of grading. \ No newline at end of file diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..432abb3 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,2 @@ +Instructions for installing your software. You should also include uninstall +instructions. \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..65106f2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,23 @@ + + +MIT License + +Copyright (c) 2022 Spencer Smith + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..a8352ff --- /dev/null +++ b/README.md @@ -0,0 +1,15 @@ +# Project Name + +Developer Names: + +Date of project start: + +This project is ... + +The folders and files for this project are as follows: + +docs - Documentation for the project +refs - Reference material used for the project, including papers +src - Source code +test - Test cases +etc. \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..84fe1f8 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,245 @@ +## Core latex/pdflatex auxiliary files: +*.aux +*.lof +*.log +*.lot +*.fls +*.out +*.toc +*.fmt +*.fot +*.cb +*.cb2 +.*.lb + +## Intermediate documents: +*.dvi +*.xdv +*-converted-to.* +# these rules might exclude image files for figures etc. +# *.ps +# *.eps +# *.pdf + +## Generated if empty string is given at "Please type another file name for output:" +.pdf + +## Bibliography auxiliary files (bibtex/biblatex/biber): +*.bbl +*.bcf +*.blg +*-blx.aux +*-blx.bib +*.run.xml + +## Build tool auxiliary files: +*.fdb_latexmk +*.synctex +*.synctex(busy) +*.synctex.gz +*.synctex.gz(busy) +*.pdfsync + +## Auxiliary and intermediate files from other packages: +# algorithms +*.alg +*.loa + +# achemso +acs-*.bib + +# amsthm +*.thm + +# beamer +*.nav +*.pre +*.snm +*.vrb + +# changes +*.soc + +# cprotect +*.cpt + +# elsarticle (documentclass of Elsevier journals) +*.spl + +# endnotes +*.ent + +# fixme +*.lox + +# feynmf/feynmp +*.mf +*.mp +*.t[1-9] +*.t[1-9][0-9] +*.tfm + +#(r)(e)ledmac/(r)(e)ledpar +*.end +*.?end +*.[1-9] +*.[1-9][0-9] +*.[1-9][0-9][0-9] +*.[1-9]R +*.[1-9][0-9]R +*.[1-9][0-9][0-9]R +*.eledsec[1-9] +*.eledsec[1-9]R +*.eledsec[1-9][0-9] +*.eledsec[1-9][0-9]R +*.eledsec[1-9][0-9][0-9] +*.eledsec[1-9][0-9][0-9]R + +# glossaries +*.acn +*.acr +*.glg +*.glo +*.gls +*.glsdefs + +# gnuplottex +*-gnuplottex-* + +# gregoriotex +*.gaux +*.gtex + +# htlatex +*.4ct +*.4tc +*.idv +*.lg +*.trc +*.xref + +# hyperref +*.brf + +# knitr +*-concordance.tex +# TODO Comment the next line if you want to keep your tikz graphics files +*.tikz +*-tikzDictionary + +# listings +*.lol + +# makeidx +*.idx +*.ilg +*.ind +*.ist + +# minitoc +*.maf +*.mlf +*.mlt +*.mtc[0-9]* +*.slf[0-9]* +*.slt[0-9]* +*.stc[0-9]* + +# minted +_minted* +*.pyg + +# morewrites +*.mw + +# nomencl +*.nlg +*.nlo +*.nls + +# pax +*.pax + +# pdfpcnotes +*.pdfpc + +# sagetex +*.sagetex.sage +*.sagetex.py +*.sagetex.scmd + +# scrwfile +*.wrt + +# sympy +*.sout +*.sympy +sympy-plots-for-*.tex/ + +# pdfcomment +*.upa +*.upb + +# pythontex +*.pytxcode +pythontex-files-*/ + +# thmtools +*.loe + +# TikZ & PGF +*.dpth +*.md5 +*.auxlock + +# todonotes +*.tdo + +# easy-todo +*.lod + +# xmpincl +*.xmpi + +# xindy +*.xdy + +# xypic precompiled matrices +*.xyc + +# endfloat +*.ttt +*.fff + +# Latexian +TSWLatexianTemp* + +## Editors: +# WinEdt +*.bak +*.sav + +# Texpad +.texpadtmp + +# Kile +*.backup + +# KBibTeX +*~[0-9]* + +# auto folder when using emacs and auctex +./auto/* +*.el + +# expex forward references with \gathertags +*-tags.tex + +# standalone packages +*.sta + +# generated if using elsarticle.cls +*.spl + +# DS_Store +*.DS_Store diff --git a/docs/Checklists/Code-Checklist.pdf b/docs/Checklists/Code-Checklist.pdf new file mode 100644 index 0000000..797967c Binary files /dev/null and b/docs/Checklists/Code-Checklist.pdf differ diff --git a/docs/Checklists/Code-Checklist.tex b/docs/Checklists/Code-Checklist.tex new file mode 100644 index 0000000..aeeb8b0 --- /dev/null +++ b/docs/Checklists/Code-Checklist.tex @@ -0,0 +1,76 @@ +\documentclass[12pt]{article} + +\usepackage{hyperref} +\hypersetup{colorlinks=true, + linkcolor=blue, + citecolor=blue, + filecolor=blue, + urlcolor=blue, + unicode=false} +\urlstyle{same} + +\usepackage{enumitem,amssymb} +\newlist{todolist}{itemize}{2} +\setlist[todolist]{label=$\square$} +\usepackage{pifont} +\newcommand{\cmark}{\ding{51}}% +\newcommand{\xmark}{\ding{55}}% +\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}% +\hspace{-2.5pt}} +\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}} + +\input{../Comments} + +\begin{document} + +\title{Source Code Checklist} +\author{Spencer Smith} +\date{\today} + +\maketitle + +% Show an item is done by \item[\done] Frame the problem +% Show an item will not be fixed by \item[\wontfix] profit + +\begin{itemize} + +\item Identifier naming + \begin{todolist} + \item Identifier names are consistent + \item Identifier names are meaningful + \end{todolist} + +\item Coding + \begin{todolist} + \item Source code in the src folder + \item Comments on ``what'' not ``how'' + \item Avoid hard-coded constants (other than maybe 0 or 1) + \item Consistent indentation + \item Explicit identification of coding standard being followed + \item Code standard is followed + \item Parameters in the same order for all functions + \end{todolist} + +\item Relation to other documents + \begin{todolist} + \item Descriptive name for source code files + \item Mapping to module guide (system architecture) is clear, may require a + document explicitly mapping between modules and code files + \item Show mapping between MIS symbols (low-level design document) and code + symbols + \end{todolist} + +\item Readability + \begin{todolist} + \item Code is reasonably understandable to someone that knows the + programming language, but is new to the project + \item Esoteric language features avoided when a simpler language feature + could be used + \item Incomplete code is flagged with a suitable marker, such as ``TO DO''? + \end{todolist} + +\item \wss{This checklist is not exhaustive. More items should be added.} + +\end{itemize} + +\end{document} diff --git a/docs/Checklists/MG-Checklist.pdf b/docs/Checklists/MG-Checklist.pdf new file mode 100644 index 0000000..fae4dc3 Binary files /dev/null and b/docs/Checklists/MG-Checklist.pdf differ diff --git a/docs/Checklists/MG-Checklist.tex b/docs/Checklists/MG-Checklist.tex new file mode 100644 index 0000000..31e4b32 --- /dev/null +++ b/docs/Checklists/MG-Checklist.tex @@ -0,0 +1,77 @@ +\documentclass[12pt]{article} + +\usepackage{hyperref} +\hypersetup{colorlinks=true, + linkcolor=blue, + citecolor=blue, + filecolor=blue, + urlcolor=blue, + unicode=false} +\urlstyle{same} + +\usepackage{enumitem,amssymb} +\newlist{todolist}{itemize}{2} +\setlist[todolist]{label=$\square$} +\usepackage{pifont} +\newcommand{\cmark}{\ding{51}}% +\newcommand{\xmark}{\ding{55}}% +\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}% +\hspace{-2.5pt}} +\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}} + +\begin{document} + +\title{MG Checklist} +\author{Spencer Smith} +\date{\today} + +\maketitle + +% Show an item is done by \item[\done] Frame the problem +% Show an item will not be fixed by \item[\wontfix] profit + +\begin{itemize} + +\item Follows writing checklist (full checklist provided in a separate document) + \begin{todolist} + \item \LaTeX{} points + \item Structure + \item Spelling, grammar, attention to detail + \item Avoid low information content phrases + \item Writing style + \end{todolist} + +\item Module Decomposition + \begin{todolist} + \item One module one secret (unless an explicit exception is made, with a good + reason) - all ``and''s should be checked. + \item The uses relation is a hierarchy. + \item Secrets are nouns (generally). + \item Traceability matrix between modules and requirements shows every + requirement is satisfied by at least on module + \item Traceability matrix between modules and requirements shows that every + module is used to satisfy at least one requirement + \item Traceability matrix between likely changes and modules shows a one to + one mapping, or, if this is not the case, explains the exceptions to this + rule. + \item Level 1 of the decomposition by secrets shows: Hardware-Hiding, + Behaviour-Hiding and Software Decision Hiding. + \item Behaviour-Hiding modules are related to the requirements + \item Software-Decision hiding modules are concepts that need to be + introduced, but are not detailed in the requirements + \item Each Software Decision Hiding module is used by at least one + Behaviour-Hiding Module (if this isn't the case, an explanation should be + provided) + \item Uses relation is not confused with a data flow chart + \item Anticipated changes are a superset of the likely changes in the SRS + \end{todolist} + +\item MG quality + \begin{todolist} + \item Follow template + \item Low coupling + \item Satisfies information hiding + \end{todolist} +\end{itemize} + +\end{document} diff --git a/docs/Checklists/MIS-Checklist.pdf b/docs/Checklists/MIS-Checklist.pdf new file mode 100644 index 0000000..c4b8a0c Binary files /dev/null and b/docs/Checklists/MIS-Checklist.pdf differ diff --git a/docs/Checklists/MIS-Checklist.tex b/docs/Checklists/MIS-Checklist.tex new file mode 100644 index 0000000..b023d69 --- /dev/null +++ b/docs/Checklists/MIS-Checklist.tex @@ -0,0 +1,131 @@ +\documentclass[12pt]{article} + +\usepackage{hyperref} +\hypersetup{colorlinks=true, + linkcolor=blue, + citecolor=blue, + filecolor=blue, + urlcolor=blue, + unicode=false} +\urlstyle{same} + +\usepackage{enumitem,amssymb} +\newlist{todolist}{itemize}{2} +\setlist[todolist]{label=$\square$} +\usepackage{pifont} +\newcommand{\cmark}{\ding{51}}% +\newcommand{\xmark}{\ding{55}}% +\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}% +\hspace{-2.5pt}} +\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}} + +\begin{document} + +\title{MIS Checklist} +\author{Spencer Smith} +\date{\today} + +\maketitle + +% Show an item is done by \item[\done] Frame the problem +% Show an item will not be fixed by \item[\wontfix] profit + +\begin{itemize} + +\item Follows writing checklist (full checklist provided in a separate document) + \begin{todolist} + \item \LaTeX{} points + \item Structure + \item Spelling, grammar, attention to detail + \item Avoid low information content phrases + \item Writing style + \end{todolist} + +\item MIS Module Classifications + \begin{todolist} + \item Types that only hold data (records) are modelled as exported types. For + instance, the StdntAllocTypes module in A2: + \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A2/A2.pdf}) + \item Types that have data (state) and behaviour are modelled as ADTs. The + MIS should use the keyword \textbf{Template}. An example is the BoardT ADT + given at + \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A3/A3Soln/A3P1_Spec.pdf} + \item Abstract objects are used when there is only one instance. There is + state and behaviour. This most + often comes up for ``global'' reader and writer modules. For instance, a + module that does logging. Abstract objects do NOT use the word Template in + the main header. An example is given in the SALst module of A2: + \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A2/A2.pdf} + \item Library modules are used when there is only behaviour, no state. They + are defined as Modules, but State Variables and Environment Variable + fields say ``None.'' + \item If the module's MIS can be parameterized by type, then the keyword + \textbf{Generic} is used. Generic modules are usually also Template + modules, but not necessarily. An example is given in the Generic Stack + Module (Stack(T)) given in A3: + \url{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/blob/master/Assignments/A3/A3Soln/A3P1_Spec.pdf} + \item Abstract objects will have some kind of initialization method + \item Abstract objects will have an assumptions that programmers will + initialize first, or a state variable that is set from False to True when + the Abstract object is initialized - this state variable then needs to be + checked for each access program call + \end{todolist} + + \item MIS and Mathematical syntax + \begin{todolist} + \item Exported constants are ``hard-coded'' literal values, not variables. + Constants are values that are known at specification (and therefore compile) + time. Explicit constant values are provided in the MIS, not left to be + filled in later. (They can be changed later, but specific values should be given.) + \item Operations do not mix incorrect types. For instance, a character is not + added to an integer, an integer is not ``anded'' with a Boolean, etc. + \item Our + \href{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/-/blob/master/MISFormat/MISFormat.pdf} + {modified Hoffmann and Strooper notation} is used, or any new notation is + clearly defined. + \end{todolist} + +\item MIS Semantics for each module + \begin{todolist} + \item Each access program does something - either an output, or a state + transition + \item Access programs either change the state of something, or have an output. + Only rarely should an access program do both (as it does for the constructor + in an ADT.) + \item If there is an entry in the state transition, then the state of + something changes. The state change might be the local state variables, the + state variables for another module, or an environment variable. + \item Outputs use $out := ...$ + \item Exceptions use $exc := ...$ + \item If the state invariant is satisfied before an access program call, it + will remain satisfied after the call + \item State invariant is initially satisfied + \item Local functions make the specification easier to read (there is no + requirement that the local functions will actually be implemented in code) + \item Modules that deal with files, the keyboard, or the screen, have + environment variables to represent these respective entitites + \item Symbols are from SRS - not yet translated to code names (that is use + $\theta$, not \texttt{theta}) + \end{todolist} + +\item MIS Quality inspection for each module + \begin{todolist} + \item Consistent + \item Essential + \item General + \item Implementation independent + \item Minimal + \item High cohesion + \item Opaque (information hiding) + \end{todolist} + +\item MIS Completeness + \begin{todolist} + \item All types introduced in the spec are defined somewhere + \item All modules in MG are in the MIS + \item All required sections of the template are present for all modules + \end{todolist} + +\end{itemize} + +\end{document} diff --git a/docs/Checklists/ProbState-Checklist.pdf b/docs/Checklists/ProbState-Checklist.pdf new file mode 100644 index 0000000..115b0f5 Binary files /dev/null and b/docs/Checklists/ProbState-Checklist.pdf differ diff --git a/docs/Checklists/ProbState-Checklist.tex b/docs/Checklists/ProbState-Checklist.tex new file mode 100644 index 0000000..fc84978 --- /dev/null +++ b/docs/Checklists/ProbState-Checklist.tex @@ -0,0 +1,65 @@ +\documentclass[12pt]{article} + +\usepackage{hyperref} +\hypersetup{colorlinks=true, + linkcolor=blue, + citecolor=blue, + filecolor=blue, + urlcolor=blue, + unicode=false} +\urlstyle{same} + +\usepackage{enumitem, amssymb} +\newlist{todolist}{itemize}{2} +\setlist[todolist]{label=$\square$} +\usepackage{pifont} +\newcommand{\cmark}{\ding{51}}% +\newcommand{\xmark}{\ding{55}}% +\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}% +\hspace{-2.5pt}} +\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}} + +\begin{document} + +\title{Problem Statement and Goals Checklist} +\author{Spencer Smith} +\date{\today} + +\maketitle + +% Show an item is done by \item[\done] Frame the problem +% Show an item will not be fixed by \item[\wontfix] profit + +\begin{itemize} + +\item Uses the provided \texttt{tex} file as a base + \begin{todolist} + \item Includes the input for \texttt{Comments} + \item Includes a title in \texttt{Common.tex} + \item Includes author names in \texttt{Common.tex} + \item Revision history included for major revisions + \item Use \verb+\newif\ifcomments\commentsfalse+ to remove comments + \end{todolist} + +\item Follows \href{https://github.com/smiths/capTemplate/blob/main/docs/Checklists/Writing-Checklist.pdf} {writing checklist} + +\item Overall qualities of documentation + \begin{todolist} + \item Scope is clear + \item Document is abstract (for instance, it does not mention the programming + language (unless this is a true constraint) or the algorithm + choices (unless the algorithm is the ``what'' rather than the ``how'')) + \item Output of software is unambiguous + \item Inputs to software are unambiguous + \item Document is simple (for instance, there is no need for a table of + contents) + \item Stakeholders are clearly identified + \item Environment is clearly identified + \item Importance of the problem is convincingly stated + \item Goals provide selling features of the product + \item Goals are measurable +\end{todolist} + +\end{itemize} + +\end{document} diff --git a/docs/Checklists/SRS-Checklist.pdf b/docs/Checklists/SRS-Checklist.pdf new file mode 100644 index 0000000..fd0185c Binary files /dev/null and b/docs/Checklists/SRS-Checklist.pdf differ diff --git a/docs/Checklists/SRS-Checklist.tex b/docs/Checklists/SRS-Checklist.tex new file mode 100644 index 0000000..2847321 --- /dev/null +++ b/docs/Checklists/SRS-Checklist.tex @@ -0,0 +1,192 @@ +\documentclass[12pt]{article} + +\usepackage[round]{natbib} +\usepackage{hyperref} +\hypersetup{colorlinks=true, + linkcolor=blue, + citecolor=blue, + filecolor=blue, + urlcolor=blue, + unicode=false} +\urlstyle{same} + +\usepackage{enumitem,amssymb} +\newlist{todolist}{itemize}{2} +\setlist[todolist]{label=$\square$} +\usepackage{pifont} +\newcommand{\cmark}{\ding{51}}% +\newcommand{\xmark}{\ding{55}}% +\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}% +\hspace{-2.5pt}} +\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}} + +\begin{document} + +\title{SRS and CA Checklist} +\author{Spencer Smith} +\date{\today} + +\maketitle + +% Show an item is done by \item[\done] Frame the problem +% Show an item will not be fixed by \item[\wontfix] profit + +This checklist is specific to the Smith et al template \citep{SmithAndLai2005, +SmithEtAl2007} for documenting requirements for scientific software, but many of +the points can be abstracted and applied to other templates. + +\begin{itemize} + +\item Follows writing checklist (full checklist provided in a separate document) + \begin{todolist} + \item \LaTeX{} points + \item Structure + \item Spelling, grammar, attention to detail + \item Avoid low information content phrases + \item Writing style + \end{todolist} + +\item Follows the template, all parts present + \begin{todolist} + \item Table of contents + \item Pages are numbered + \item Revision history included for major revisions + \item Sections from template are all present + \item Values of auxiliary constants are given (constants are used to improve + maintainability and to increase understandability) + \item Symbolic names are used for quantities, rather than literal values + \end{todolist} + +\item Overall qualities of documentation + \begin{todolist} + \item No statement is repeated at the same level of abstraction (for instance + the scope should be more abstract than the assumptions, the goal statements + should be more abstract than the requirements, etc.) + \item Someone that meets the characteristics of the intended reader could + learn what they need to know + \item Someone that meets the characteristics of the intended reader could + verify all of the statement made in the SRS. That is, they do not have to + trust the SRS authors on any information. + \item Terminology, definitions, symbols, TMs and DDs can be given without + derivation, except possibly for a source (citation), but all GDs and IMs + should be derived/justified. At least check a representative sample for + this criteria. + \item SRS is unambiguous. At least check a representative sample. + \item SRS is consistent. At least check a representative sample. + \item SRS is validatable. At least check a representative sample. + \item SRS is abstract. At least check a representative sample. + \item SRS is traceable. At least check a representative sample. + \item Literal symbols (like numbers) do not appear, instead being + represented by SYMBOLIC\_CONSTANTS (constants are given in a table in the + Appendix) +\end{todolist} + +\item Reference Material + \begin{todolist} + \item All units introduced are listed (searching the document can help look + for other units that may be present, but not listed) + \item Units listed are each used at least once (manually searching the + document is a quick way to check this) + \item The names of units named after people are in lower-case + \item All symbols used in the document are listed in the table of symbols + \item All symbols listed in the table of symbols are used in the document + \item All abbreviations/acronyms used in the document are listed in the table + of abbreviations/acronyms + \item All abbreviations/acronyms listed in the table of abbreviations/acronyms + are used in the document + \item If a domain specific notation will be used, it has been defined in the + mathematical notation section + \end{todolist} + +\item Introduction + \begin{todolist} + \item Introductory blurb focuses on the problem domain + \item Introductory blurb Includes a ``roadmap'' + \item ``Purpose of the Document'' discusses the documentation's purpose, not + the program's purpose + \item Scope of the requirements is an abstract version of the assumptions. + Every item of the scope should be reflected in at least one assumption. + \item Characteristics of the intended reader are not confused with the user + characteristics + \item Characteristics of the intended reader are unambiguous + \end{todolist} + +\item General System Description + \begin{todolist} + \item System context includes a figure showing the relation between the + software system and external entities + \item If the software will depend on other software, such as other libraries, + this is part of the system context. Try to keep the libraries generic, + unless specific libraries are needed, which will mean software constaints + are also specified. + \item User characteristics are unambiguous (for instance, don't just say the user will know + physics, say they will know Newtonian mechanics as typically covered in the + first year of an engineering or science degree) + \item User characteristics are specific + \item System constraints have an appropriate rationale (a constraint without a + reason for that constraint is likely making the SRS less abstract than it + should be) + \end{todolist} + +\item Problem Description + \begin{todolist} + \item Each item of the physical system is identified and labelled + \item Goal statements are abstract + \item Goal statements use a minimal amount of technical language, + understandable by non-domain experts + \end{todolist} + +\item Solution Characteristics Specification + \begin{todolist} + \item Each assumption is ``atomic'' (no explicit or implicit ``ands'') + \item Assumptions are a refinement of the scope + \item Each assumption is referenced at least once in the document + \item If an assumption is listed as being referenced by another chunk (T, IM + etc), that other chunk should explicitly invoke the assumption in the + describing text or derivation + \item A link exists between each chunk and anything that references it + \item If the ``Ref.\ By'' field is filled in, the entities (model, definition, + assumption) listed explicitly include a reference to the original entity + (model, definition, assumption). + \item The rationale is given for assumptions that require justification + \item The derivation of all GDs as refinements from other models is clear + \item The derivation of all IMs as refinements from other models is clear + \item All DD are used (referenced) by at least one other model + \item The IMs remain abstract + \item Input data constraints are given, with a rationale where appropriate + \item Properties of a correct solution are given (or explicitly left blank) + \item Equations are balanced with respect to units of all terms + \end{todolist} + +\item Functional Requirements + \begin{todolist} + \item IMs and (possibly) TMs and GMs are referenced as appropriate by the + requirements. It is a sign that the IMs are not set correctly if there is + one or more IMs that are not referenced by any of the requirements. + \item All requirements are validatable + \item All requirements are abstract + \item Requirements are traceable to where the required details are found in + the document + \end{todolist} + +\item Nonfunctional Requirements + \begin{todolist} + \item NFRs are verifiable + \end{todolist} + +\item Likely and Unlikely changes + \begin{todolist} + \item Likely changes are feasible to hide in the design + \end{todolist} + +\item Traceability Matrices + \begin{todolist} + \item Traceability matrix is complete + \end{todolist} + +\end{itemize} + +\bibliographystyle {plainnat} +\bibliography{../../refs/References} + +\end{document} diff --git a/docs/Checklists/VnV-Checklist.pdf b/docs/Checklists/VnV-Checklist.pdf new file mode 100644 index 0000000..c09d1f0 Binary files /dev/null and b/docs/Checklists/VnV-Checklist.pdf differ diff --git a/docs/Checklists/VnV-Checklist.tex b/docs/Checklists/VnV-Checklist.tex new file mode 100644 index 0000000..a133a33 --- /dev/null +++ b/docs/Checklists/VnV-Checklist.tex @@ -0,0 +1,98 @@ +\documentclass[12pt]{article} + +\usepackage{enumitem,amssymb} +\newlist{todolist}{itemize}{2} +\setlist[todolist]{label=$\square$} +\usepackage{pifont} +\newcommand{\cmark}{\ding{51}}% +\newcommand{\xmark}{\ding{55}}% +\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}% +\hspace{-2.5pt}} +\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}} + +\begin{document} + +\title{System Verification and Validation Plan Checklist} +\author{Spencer Smith} +\date{\today} + +\maketitle + +% Show an item is done by \item[\done] Frame the problem +% Show an item will not be fixed by \item[\wontfix] profit + +\begin{itemize} + +\item Follows writing checklist (full checklist provided in a separate document) + \begin{todolist} + \item \LaTeX{} points + \item Structure + \item Spelling, grammar, attention to detail + \item Avoid low information content phrases + \item Writing style + \end{todolist} + +\item Follows the template, all parts present + \begin{todolist} + \item Table of contents + \item Pages are numbered + \item Revision history included for major revisions + \item Sections from template are all present + \item Values of auxiliary constants are given (constants are used to improve + maintainability and to increase understandability) + \end{todolist} + +\item Grammar, spelling, presentation + \begin{todolist} + \item No spelling mistakes (use a spell checker!) + \item No grammar mistakes (review, ask someone else to review (at least a few + sections)) + \item Paragraphs are structured well (clear topic sentence, cohesive) + \item Paragraphs are concise (not wordy) + \item No Low Information Content (LIC) phrases + (\href{https://www.webpages.uidaho.edu/range357/extra-refs/empty-words.htm}{List + of LIC phrases}) + \item All hyperlinks work + \item Every figure has a caption + \item Every table has a heading + \item Symbolic names are used for quantities, rather than literal values + \end{todolist} + +\item LaTeX + \begin{todolist} + \item Template comments do not show in the pdf version, either by + removing them, or by turning them off. + \item References and labels are used so that maintenance is feasible +\end{todolist} + +\item Overall qualities of documentation + \begin{todolist} +\item Test cases include SPECIFIC input +\item Test cases include EXPLICIT output +\item Description over specification, when appropriate +\item Plans for what to do with description data (performance, usability, etc). + This may involve saying what plots will be generated. +\item Plans to quantify error for scalar values using relative error +\item Plans to quantify error for vector and matrix values using a norm of an error + vector (matrix) +\item Plans are feasible (can be accomplished with resources available) +\item Plans are ambitious enough for an A+ effort +\item Survey questions for usability survey are in an Appendix (if appropriate) +\item Plans for task based inspection, if appropriate +\item Very careful use of random testing +\item Specific programming language is listed +\item Specific linter tool is listed (if appropriate) +\item Specific coding standard is given +\item Specific unit testing framework is given +\item Investigation of code coverage measuring tools +\item Specific plans for Continuous Integration (CI), or an explanation that CI + is not being done +\item Specific performance measuring tools listed (like Valgrind), if + appropriate +\item Traceability between test cases and requirements is summarized (likely in + a table) +\end{todolist} + +\end{itemize} + +\end{document} diff --git a/docs/Checklists/Writing-Checklist.pdf b/docs/Checklists/Writing-Checklist.pdf new file mode 100644 index 0000000..127ff23 Binary files /dev/null and b/docs/Checklists/Writing-Checklist.pdf differ diff --git a/docs/Checklists/Writing-Checklist.tex b/docs/Checklists/Writing-Checklist.tex new file mode 100644 index 0000000..dcd7021 --- /dev/null +++ b/docs/Checklists/Writing-Checklist.tex @@ -0,0 +1,169 @@ +\documentclass[12pt]{article} + +\usepackage{enumitem} + +\usepackage{amssymb} +\usepackage{amsfonts} +\usepackage{amsmath} + +\usepackage{hyperref} +\hypersetup{colorlinks=true, + linkcolor=blue, + citecolor=blue, + filecolor=blue, + urlcolor=blue, + unicode=false} +\urlstyle{same} + +\newlist{todolist}{itemize}{2} +\setlist[todolist]{label=$\square$} +\usepackage{pifont} +\newcommand{\cmark}{\ding{51}}% +\newcommand{\xmark}{\ding{55}}% +\newcommand{\done}{\rlap{$\square$}{\raisebox{2pt}{\large\hspace{1pt}\cmark}}% +\hspace{-2.5pt}} +\newcommand{\wontfix}{\rlap{$\square$}{\large\hspace{1pt}\xmark}} + +\begin{document} + +\title{Writing Checklist} +\author{Spencer Smith} +\date{\today} + +\maketitle + +% Show an item is done by \item[\done] Frame the problem +% Show an item will not be fixed by \item[\wontfix] profit + +The following checklist should be applied to the documents that you write. + +\begin{itemize} + +\item \LaTeX{} points + \begin{todolist} + \item Only tex file (and possibly pdf files, or image files) are under version + control (\texttt{aux} files etc. are not under version control) (\texttt{.gitignore} can help with this) + \item Opening and closing ``quotes'' are used (\verb|``quotes''|) + \item Periods that do not end sentences are followed by only one space + (\LaTeX{} inserts two by default): \verb|``I like Dr.\ Smith.''|, or for no + linebreaks: \verb|``I like Dr.~Smith.''| + \item Long names in math mode use either mathit or text, or equivalent: + $coeff$ (\verb|$coeff$|) versus $\mathit{coeff}$ (\verb|$\mathit{coeff}$|) + versus $\text{coeff}$ (\verb|$\text{coeff}$|). (By default \LaTeX{} + incorrectly thinks each letter is a separate variable and spaces + accordingly.) + \item The \texttt{Comments.tex} file is provided for ease of adding comments + to a LaTeX file. + \item Text lines should be 80 characters wide. That is, the text has a hard-wrap at + 80 characters. This is done to facilitate meaingful diffs between different + commits. (Some ideas on how to do this are given below.) + \item Template comments (plt) should not be shown in the pdf version, either + by removing them, or by turning them off. + \item References and labels are used so that maintenance is feasible + \item Cross-references between documents are used as appropriate + \item BibTeX is used for generating bibliographic references + \end{todolist} + +\item Structure + \begin{todolist} + \item There is always some text between section headings + \item There aren't instances of only one subsection within a section + \end{todolist} + +\item Spelling, Grammar and attention to detail + \begin{todolist} + \item Each punctuation symbol (period, comma, semicolon, question mark, + exclamation point) has no space before it. + \item Opening parentheses (brackets) have a space before, closing parentheses + have a space after the symbol. + \item Parentheses (brackets) occur in pairs, one opening and one closing + \item All sentences begin with a capital letter. + \item Document is spell checked! + \item Grammar has been checked (review, assign a team member an issue to review the grammar for each section). + \item That and which are used correctly + (\url{http://www.kentlaw.edu/academics/lrw/grinker/LwtaThat_Versus_Which.htm}) + \item Symbols used outside of a formula should be formatted the same way as + they are in the equation. For instance, when listing the variables in an + equation, you should still use math mode for the symbols. + \item Include a \texttt{.gitignore} file in your repo so that generated files + are ignored by git. More information is available on-line on + \href{https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory} + {Hidden files and hidden directories}. + \item All hyperlinks work + \item Every figure has a caption + \item Every table has a heading + \item Every figure is referred to by the text at some point + \item Every table is referred to be the text at some point + \item All acronyms are expanded on their first usage, using capitals to + show the source of each letter in the acronym. Defining the acronym only in + a table at the beginning of the document is not enough. + \end{todolist} + +\item Avoid Low Information Content phrases + (\href{https://www.webpages.uidaho.edu/range357/extra-refs/empty-words.htm}{List + of LIC phrases}) + + \begin{todolist} + \item ``in order to'' simplified to ``to'' + \item ... + \end{todolist} + +\item Writing style + \begin{todolist} + \item Avoid sentences that start with ``It.'' + \item Paragraphs are structured well (clear topic sentence, cohesive) + \item Paragraphs are concise (not wordy) + \end{todolist} + +\item GithHub + \begin{todolist} + \item Proper GitHub conventions are followed (see below) + \end{todolist} + +\end{itemize} + +\subsubsection*{Fixed Width \LaTeX{} Text} + +Having the \LaTeX{} text at a fixed width (hard-wrap) is useful when the source +is under version control. The fixed line lengths help with isolating the +changes between diffs. + +Although the checklist mentions an 80 column width, any reasonable fixed width +is fine. + +The hard-wrap shouldn't be done manually. Most editors will have some facility +for fixed width. In emacs it is called auto-fill. Some advice from previous +and current students: + +\begin{itemize} +\item In TEXMaker, you can do: User $>$ Run script $>$ hardwordwrap +\item Wrapping is easy in VSCode, Emacs, and Vim +\end{itemize} + +\subsubsection*{Using GitHub} + +\begin{itemize} +\item When closing an issue, include (where appropriate) the commit hash of the + commit that addresses the issue +\item Make small commits (sometimes a commit will be changing only one line, or + even just one word) +\item Make sure that all of the changes in a commit are related (you can change + more than one file, but the changes should all be related) +\item You can easily link to other issues in your issue description or + discussion comments by using the hash symbol followed by the number + of that other issue +\item You can include a smiley face :smile:, if you want to ensure that your + comments do not come across as more harsh than you intend +\item Close issues when they are done (the person assigned the issue is + generally the person that closes the issue) +\item + \href{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/-/blob/master/FAQ/GitAdvice.txt} + {Advice from Emily Horsman} on git commits +\end{itemize} + +There are many other +\href{https://gitlab.cas.mcmaster.ca/SEforSC/se4sc/-/wikis/Advice-and-Checklists-for-Repos-(including-a-list-of-recommended-artifacts)}{checklists} +available for scientific computing (research) software. Google can help find +even more checklists. + +\end{document} diff --git a/docs/Comments.tex b/docs/Comments.tex new file mode 100644 index 0000000..dbc377e --- /dev/null +++ b/docs/Comments.tex @@ -0,0 +1,18 @@ +%% Comments + +\usepackage{color} + +\newif\ifcomments\commentstrue %displays comments +%\newif\ifcomments\commentsfalse %so that comments do not display + +\ifcomments +\newcommand{\authornote}[3]{\textcolor{#1}{[#3 ---#2]}} +\newcommand{\todo}[1]{\textcolor{red}{[TODO: #1]}} +\else +\newcommand{\authornote}[3]{} +\newcommand{\todo}[1]{} +\fi + +\newcommand{\wss}[1]{\authornote{blue}{SS}{#1}} +\newcommand{\plt}[1]{\authornote{magenta}{TPLT}{#1}} %For explanation of the template +\newcommand{\an}[1]{\authornote{cyan}{Author}{#1}} diff --git a/docs/Common.tex b/docs/Common.tex new file mode 100644 index 0000000..14b9555 --- /dev/null +++ b/docs/Common.tex @@ -0,0 +1,14 @@ +%% Common Parts + +\newcommand{\progname}{ProgName} % PUT YOUR PROGRAM NAME HERE +\newcommand{\authname}{Team \#, Team Name +\\ Student 1 name and macid +\\ Student 2 name and macid +\\ Student 3 name and macid +\\ Student 4 name and macid} % AUTHOR NAMES + +\usepackage{hyperref} + \hypersetup{colorlinks=true, linkcolor=blue, citecolor=blue, filecolor=blue, + urlcolor=blue, unicode=false} + \urlstyle{same} + diff --git a/docs/Design/MG/MG.pdf b/docs/Design/MG/MG.pdf new file mode 100644 index 0000000..e488a60 Binary files /dev/null and b/docs/Design/MG/MG.pdf differ diff --git a/docs/Design/MG/MG.tex b/docs/Design/MG/MG.tex new file mode 100644 index 0000000..3cab495 --- /dev/null +++ b/docs/Design/MG/MG.tex @@ -0,0 +1,387 @@ +\documentclass[12pt, titlepage]{article} + +\usepackage{fullpage} +\usepackage[round]{natbib} +\usepackage{multirow} +\usepackage{booktabs} +\usepackage{tabularx} +\usepackage{graphicx} +\usepackage{float} +\usepackage{hyperref} +\hypersetup{ + colorlinks, + citecolor=blue, + filecolor=black, + linkcolor=red, + urlcolor=blue +} + +\input{../../Comments} +\input{../../Common} + +\newcounter{acnum} +\newcommand{\actheacnum}{AC\theacnum} +\newcommand{\acref}[1]{AC\ref{#1}} + +\newcounter{ucnum} +\newcommand{\uctheucnum}{UC\theucnum} +\newcommand{\uref}[1]{UC\ref{#1}} + +\newcounter{mnum} +\newcommand{\mthemnum}{M\themnum} +\newcommand{\mref}[1]{M\ref{#1}} + +\begin{document} + +\title{Module Guide for \progname{}} +\author{Author Name} +\date{\today} + +\maketitle + +\pagenumbering{roman} + +\section{Revision History} + +\begin{tabularx}{\textwidth}{p{3cm}p{2cm}X} +\toprule {\bf Date} & {\bf Version} & {\bf Notes}\\ +\midrule +Date 1 & 1.0 & Notes\\ +Date 2 & 1.1 & Notes\\ +\bottomrule +\end{tabularx} + +\newpage + +\section{Reference Material} + +This section records information for easy reference. + +\subsection{Abbreviations and Acronyms} + +\renewcommand{\arraystretch}{1.2} +\begin{tabular}{l l} + \toprule + \textbf{symbol} & \textbf{description}\\ + \midrule + AC & Anticipated Change\\ + DAG & Directed Acyclic Graph \\ + M & Module \\ + MG & Module Guide \\ + OS & Operating System \\ + R & Requirement\\ + SC & Scientific Computing \\ + SRS & Software Requirements Specification\\ + \progname & Explanation of program name\\ + UC & Unlikely Change \\ + \wss{etc.} & \wss{...}\\ + \bottomrule +\end{tabular}\\ + +\newpage + +\tableofcontents + +\listoftables + +\listoffigures + +\newpage + +\pagenumbering{arabic} + +\section{Introduction} + +Decomposing a system into modules is a commonly accepted approach to developing +software. A module is a work assignment for a programmer or programming +team~\citep{ParnasEtAl1984}. We advocate a decomposition +based on the principle of information hiding~\citep{Parnas1972a}. This +principle supports design for change, because the ``secrets'' that each module +hides represent likely future changes. Design for change is valuable in SC, +where modifications are frequent, especially during initial development as the +solution space is explored. + +Our design follows the rules layed out by \citet{ParnasEtAl1984}, as follows: +\begin{itemize} +\item System details that are likely to change independently should be the + secrets of separate modules. +\item Each data structure is implemented in only one module. +\item Any other program that requires information stored in a module's data + structures must obtain it by calling access programs belonging to that module. +\end{itemize} + +After completing the first stage of the design, the Software Requirements +Specification (SRS), the Module Guide (MG) is developed~\citep{ParnasEtAl1984}. The MG +specifies the modular structure of the system and is intended to allow both +designers and maintainers to easily identify the parts of the software. The +potential readers of this document are as follows: + +\begin{itemize} +\item New project members: This document can be a guide for a new project member + to easily understand the overall structure and quickly find the + relevant modules they are searching for. +\item Maintainers: The hierarchical structure of the module guide improves the + maintainers' understanding when they need to make changes to the system. It is + important for a maintainer to update the relevant sections of the document + after changes have been made. +\item Designers: Once the module guide has been written, it can be used to + check for consistency, feasibility and flexibility. Designers can verify the + system in various ways, such as consistency among modules, feasibility of the + decomposition, and flexibility of the design. +\end{itemize} + +The rest of the document is organized as follows. Section +\ref{SecChange} lists the anticipated and unlikely changes of the software +requirements. Section \ref{SecMH} summarizes the module decomposition that +was constructed according to the likely changes. Section \ref{SecConnection} +specifies the connections between the software requirements and the +modules. Section \ref{SecMD} gives a detailed description of the +modules. Section \ref{SecTM} includes two traceability matrices. One checks +the completeness of the design against the requirements provided in the SRS. The +other shows the relation between anticipated changes and the modules. Section +\ref{SecUse} describes the use relation between modules. + +\section{Anticipated and Unlikely Changes} \label{SecChange} + +This section lists possible changes to the system. According to the likeliness +of the change, the possible changes are classified into two +categories. Anticipated changes are listed in Section \ref{SecAchange}, and +unlikely changes are listed in Section \ref{SecUchange}. + +\subsection{Anticipated Changes} \label{SecAchange} + +Anticipated changes are the source of the information that is to be hidden +inside the modules. Ideally, changing one of the anticipated changes will only +require changing the one module that hides the associated decision. The approach +adapted here is called design for +change. + +\begin{description} +\item[\refstepcounter{acnum} \actheacnum \label{acHardware}:] The specific + hardware on which the software is running. +\item[\refstepcounter{acnum} \actheacnum \label{acInput}:] The format of the + initial input data. +\item ... +\end{description} + +\subsection{Unlikely Changes} \label{SecUchange} + +The module design should be as general as possible. However, a general system is +more complex. Sometimes this complexity is not necessary. Fixing some design +decisions at the system architecture stage can simplify the software design. If +these decision should later need to be changed, then many parts of the design +will potentially need to be modified. Hence, it is not intended that these +decisions will be changed. + +\begin{description} +\item[\refstepcounter{ucnum} \uctheucnum \label{ucIO}:] Input/Output devices + (Input: File and/or Keyboard, Output: File, Memory, and/or Screen). +\item ... +\end{description} + +\section{Module Hierarchy} \label{SecMH} + +This section provides an overview of the module design. Modules are summarized +in a hierarchy decomposed by secrets in Table \ref{TblMH}. The modules listed +below, which are leaves in the hierarchy tree, are the modules that will +actually be implemented. + +\begin{description} +\item [\refstepcounter{mnum} \mthemnum \label{mHH}:] Hardware-Hiding Module +\item ... +\end{description} + + +\begin{table}[h!] +\centering +\begin{tabular}{p{0.3\textwidth} p{0.6\textwidth}} +\toprule +\textbf{Level 1} & \textbf{Level 2}\\ +\midrule + +{Hardware-Hiding Module} & ~ \\ +\midrule + +\multirow{7}{0.3\textwidth}{Behaviour-Hiding Module} & ?\\ +& ?\\ +& ?\\ +& ?\\ +& ?\\ +& ?\\ +& ?\\ +& ?\\ +\midrule + +\multirow{3}{0.3\textwidth}{Software Decision Module} & {?}\\ +& ?\\ +& ?\\ +\bottomrule + +\end{tabular} +\caption{Module Hierarchy} +\label{TblMH} +\end{table} + +\section{Connection Between Requirements and Design} \label{SecConnection} + +The design of the system is intended to satisfy the requirements developed in +the SRS. In this stage, the system is decomposed into modules. The connection +between requirements and modules is listed in Table \ref{TblRT}. + +\wss{The intention of this section is to document decisions that are made + ``between'' the requirements and the design. To satisfy some requirements, + design decisions need to be made. Rather than make these decisions implicit, + they are explicitly recorded here. For instance, if a program has security + requirements, a specific design decision may be made to satisfy those + requirements with a password. In scientific examples, the choice of algorithm +could potentially go here, if that is a decision that is exposed by the +interface.} + +\section{Module Decomposition} \label{SecMD} + +Modules are decomposed according to the principle of ``information hiding'' +proposed by \citet{ParnasEtAl1984}. The \emph{Secrets} field in a module +decomposition is a brief statement of the design decision hidden by the +module. The \emph{Services} field specifies \emph{what} the module will do +without documenting \emph{how} to do it. For each module, a suggestion for the +implementing software is given under the \emph{Implemented By} title. If the +entry is \emph{OS}, this means that the module is provided by the operating +system or by standard programming language libraries. \emph{\progname{}} means the +module will be implemented by the \progname{} software. + +Only the leaf modules in the hierarchy have to be implemented. If a dash +(\emph{--}) is shown, this means that the module is not a leaf and will not have +to be implemented. + +\subsection{Hardware Hiding Modules (\mref{mHH})} + +\begin{description} +\item[Secrets:]The data structure and algorithm used to implement the virtual + hardware. +\item[Services:]Serves as a virtual hardware used by the rest of the + system. This module provides the interface between the hardware and the + software. So, the system can use it to display outputs or to accept inputs. +\item[Implemented By:] OS +\end{description} + +\subsection{Behaviour-Hiding Module} + +\begin{description} +\item[Secrets:]The contents of the required behaviours. +\item[Services:]Includes programs that provide externally visible behaviour of + the system as specified in the software requirements specification (SRS) + documents. This module serves as a communication layer between the + hardware-hiding module and the software decision module. The programs in this + module will need to change if there are changes in the SRS. +\item[Implemented By:] -- +\end{description} + +\subsubsection{Input Format Module (\mref{mInput})} + +\begin{description} +\item[Secrets:]The format and structure of the input data. +\item[Services:]Converts the input data into the data structure used by the + input parameters module. +\item[Implemented By:] [Your Program Name Here] +\item[Type of Module:] [Record, Library, Abstract Object, or Abstract Data Type] + [Information to include for leaf modules in the decomposition by secrets tree.] +\end{description} + +\subsubsection{Etc.} + + +\subsection{Software Decision Module} + +\begin{description} +\item[Secrets:] The design decision based on mathematical theorems, physical + facts, or programming considerations. The secrets of this module are + \emph{not} described in the SRS. +\item[Services:] Includes data structure and algorithms used in the system that + do not provide direct interaction with the user. + % Changes in these modules are more likely to be motivated by a desire to + % improve performance than by externally imposed changes. +\item[Implemented By:] -- +\end{description} + +\subsubsection{Etc.} + +\section{Traceability Matrix} \label{SecTM} + +This section shows two traceability matrices: between the modules and the +requirements and between the modules and the anticipated changes. + +% the table should use mref, the requirements should be named, use something +% like fref +\begin{table}[H] +\centering +\begin{tabular}{p{0.2\textwidth} p{0.6\textwidth}} +\toprule +\textbf{Req.} & \textbf{Modules}\\ +\midrule +R1 & \mref{mHH}, \mref{mInput}, \mref{mParams}, \mref{mControl}\\ +R2 & \mref{mInput}, \mref{mParams}\\ +R3 & \mref{mVerify}\\ +R4 & \mref{mOutput}, \mref{mControl}\\ +R5 & \mref{mOutput}, \mref{mODEs}, \mref{mControl}, \mref{mSeqDS}, \mref{mSolver}, \mref{mPlot}\\ +R6 & \mref{mOutput}, \mref{mODEs}, \mref{mControl}, \mref{mSeqDS}, \mref{mSolver}, \mref{mPlot}\\ +R7 & \mref{mOutput}, \mref{mEnergy}, \mref{mControl}, \mref{mSeqDS}, \mref{mPlot}\\ +R8 & \mref{mOutput}, \mref{mEnergy}, \mref{mControl}, \mref{mSeqDS}, \mref{mPlot}\\ +R9 & \mref{mVerifyOut}\\ +R10 & \mref{mOutput}, \mref{mODEs}, \mref{mControl}\\ +R11 & \mref{mOutput}, \mref{mODEs}, \mref{mEnergy}, \mref{mControl}\\ +\bottomrule +\end{tabular} +\caption{Trace Between Requirements and Modules} +\label{TblRT} +\end{table} + +\begin{table}[H] +\centering +\begin{tabular}{p{0.2\textwidth} p{0.6\textwidth}} +\toprule +\textbf{AC} & \textbf{Modules}\\ +\midrule +\acref{acHardware} & \mref{mHH}\\ +\acref{acInput} & \mref{mInput}\\ +\acref{acParams} & \mref{mParams}\\ +\acref{acVerify} & \mref{mVerify}\\ +\acref{acOutput} & \mref{mOutput}\\ +\acref{acVerifyOut} & \mref{mVerifyOut}\\ +\acref{acODEs} & \mref{mODEs}\\ +\acref{acEnergy} & \mref{mEnergy}\\ +\acref{acControl} & \mref{mControl}\\ +\acref{acSeqDS} & \mref{mSeqDS}\\ +\acref{acSolver} & \mref{mSolver}\\ +\acref{acPlot} & \mref{mPlot}\\ +\bottomrule +\end{tabular} +\caption{Trace Between Anticipated Changes and Modules} +\label{TblACT} +\end{table} + +\section{Use Hierarchy Between Modules} \label{SecUse} + +In this section, the uses hierarchy between modules is +provided. \citet{Parnas1978} said of two programs A and B that A {\em uses} B if +correct execution of B may be necessary for A to complete the task described in +its specification. That is, A {\em uses} B if there exist situations in which +the correct functioning of A depends upon the availability of a correct +implementation of B. Figure \ref{FigUH} illustrates the use relation between +the modules. It can be seen that the graph is a directed acyclic graph +(DAG). Each level of the hierarchy offers a testable and usable subset of the +system, and modules in the higher level of the hierarchy are essentially simpler +because they use modules from the lower levels. + +\begin{figure}[H] +\centering +%\includegraphics[width=0.7\textwidth]{UsesHierarchy.png} +\caption{Use hierarchy among modules} +\label{FigUH} +\end{figure} + +%\section*{References} + +\bibliographystyle {plainnat} +\bibliography{../../../refs/References} + +\end{document} \ No newline at end of file diff --git a/docs/Design/MG/Makefile b/docs/Design/MG/Makefile new file mode 100644 index 0000000..204e2a0 --- /dev/null +++ b/docs/Design/MG/Makefile @@ -0,0 +1,19 @@ +# Makefile +# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/ + +PROJECT=MG +TEX=pdflatex +BIBTEX=bibtex +BUILDTEX=$(TEX) $(PROJECT).tex + +all: + $(BUILDTEX) + $(BIBTEX) $(PROJECT) + $(BUILDTEX) + $(BUILDTEX) + +clean-all: + rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~ + +clean: + rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *.lof *.lot *~ \ No newline at end of file diff --git a/docs/Design/MG/README.md b/docs/Design/MG/README.md new file mode 100644 index 0000000..e41d35c --- /dev/null +++ b/docs/Design/MG/README.md @@ -0,0 +1,3 @@ +# Module Guide + +The folders and files for the module guide. diff --git a/docs/Design/MIS/MIS.pdf b/docs/Design/MIS/MIS.pdf new file mode 100644 index 0000000..3600d25 Binary files /dev/null and b/docs/Design/MIS/MIS.pdf differ diff --git a/docs/Design/MIS/MIS.tex b/docs/Design/MIS/MIS.tex new file mode 100644 index 0000000..e8a3b83 --- /dev/null +++ b/docs/Design/MIS/MIS.tex @@ -0,0 +1,241 @@ +\documentclass[12pt, titlepage]{article} + +\usepackage{amsmath, mathtools} + +\usepackage[round]{natbib} +\usepackage{amsfonts} +\usepackage{amssymb} +\usepackage{graphicx} +\usepackage{colortbl} +\usepackage{xr} +\usepackage{hyperref} +\usepackage{longtable} +\usepackage{xfrac} +\usepackage{tabularx} +\usepackage{float} +\usepackage{siunitx} +\usepackage{booktabs} +\usepackage{multirow} +\usepackage[section]{placeins} +\usepackage{caption} +\usepackage{fullpage} + +\hypersetup{ +bookmarks=true, % show bookmarks bar? +colorlinks=true, % false: boxed links; true: colored links +linkcolor=red, % color of internal links (change box color with linkbordercolor) +citecolor=blue, % color of links to bibliography +filecolor=magenta, % color of file links +urlcolor=cyan % color of external links +} + +\usepackage{array} + +\externaldocument{../../SRS/SRS} + +\input{../../Comments} +\input{../../Common} + +\begin{document} + +\title{Module Interface Specification for \progname{}} + +\author{Author Name} + +\date{\today} + +\maketitle + +\pagenumbering{roman} + +\section{Revision History} + +\begin{tabularx}{\textwidth}{p{3cm}p{2cm}X} +\toprule {\bf Date} & {\bf Version} & {\bf Notes}\\ +\midrule +Date 1 & 1.0 & Notes\\ +Date 2 & 1.1 & Notes\\ +\bottomrule +\end{tabularx} + +~\newpage + +\section{Symbols, Abbreviations and Acronyms} + +See SRS Documentation at \wss{give url} + +\wss{Also add any additional symbols, abbreviations or acronyms} + +\newpage + +\tableofcontents + +\newpage + +\pagenumbering{arabic} + +\section{Introduction} + +The following document details the Module Interface Specifications for +\wss{Fill in your project name and description} + +Complementary documents include the System Requirement Specifications +and Module Guide. The full documentation and implementation can be +found at \url{...}. \wss{provide the url for your repo} + +\section{Notation} + +\wss{You should describe your notation. You can use what is below as + a starting point.} + +The structure of the MIS for modules comes from \citet{HoffmanAndStrooper1995}, +with the addition that template modules have been adapted from +\cite{GhezziEtAl2003}. The mathematical notation comes from Chapter 3 of +\citet{HoffmanAndStrooper1995}. For instance, the symbol := is used for a +multiple assignment statement and conditional rules follow the form $(c_1 +\Rightarrow r_1 | c_2 \Rightarrow r_2 | ... | c_n \Rightarrow r_n )$. + +The following table summarizes the primitive data types used by \progname. + +\begin{center} +\renewcommand{\arraystretch}{1.2} +\noindent +\begin{tabular}{l l p{7.5cm}} +\toprule +\textbf{Data Type} & \textbf{Notation} & \textbf{Description}\\ +\midrule +character & char & a single symbol or digit\\ +integer & $\mathbb{Z}$ & a number without a fractional component in (-$\infty$, $\infty$) \\ +natural number & $\mathbb{N}$ & a number without a fractional component in [1, $\infty$) \\ +real & $\mathbb{R}$ & any number in (-$\infty$, $\infty$)\\ +\bottomrule +\end{tabular} +\end{center} + +\noindent +The specification of \progname \ uses some derived data types: sequences, strings, and +tuples. Sequences are lists filled with elements of the same data type. Strings +are sequences of characters. Tuples contain a list of values, potentially of +different types. In addition, \progname \ uses functions, which +are defined by the data types of their inputs and outputs. Local functions are +described by giving their type signature followed by their specification. + +\section{Module Decomposition} + +The following table is taken directly from the Module Guide document for this project. + +\begin{table}[h!] +\centering +\begin{tabular}{p{0.3\textwidth} p{0.6\textwidth}} +\toprule +\textbf{Level 1} & \textbf{Level 2}\\ +\midrule + +{Hardware-Hiding} & ~ \\ +\midrule + +\multirow{7}{0.3\textwidth}{Behaviour-Hiding} & Input Parameters\\ +& Output Format\\ +& Output Verification\\ +& Temperature ODEs\\ +& Energy Equations\\ +& Control Module\\ +& Specification Parameters Module\\ +\midrule + +\multirow{3}{0.3\textwidth}{Software Decision} & {Sequence Data Structure}\\ +& ODE Solver\\ +& Plotting\\ +\bottomrule + +\end{tabular} +\caption{Module Hierarchy} +\label{TblMH} +\end{table} + +\newpage +~\newpage + +\section{MIS of \wss{Module Name}} \label{Module} \wss{Use labels for + cross-referencing} + +\wss{You can reference SRS labels, such as R\ref{R_Inputs}.} + +\wss{It is also possible to use \LaTeX for hypperlinks to external documents.} + +\subsection{Module} + +\wss{Short name for the module} + +\subsection{Uses} + + +\subsection{Syntax} + +\subsubsection{Exported Constants} + +\subsubsection{Exported Access Programs} + +\begin{center} +\begin{tabular}{p{2cm} p{4cm} p{4cm} p{2cm}} +\hline +\textbf{Name} & \textbf{In} & \textbf{Out} & \textbf{Exceptions} \\ +\hline +\wss{accessProg} & - & - & - \\ +\hline +\end{tabular} +\end{center} + +\subsection{Semantics} + +\subsubsection{State Variables} + +\wss{Not all modules will have state variables. State variables give the module + a memory.} + +\subsubsection{Environment Variables} + +\wss{This section is not necessary for all modules. Its purpose is to capture + when the module has external interaction with the environment, such as for a + device driver, screen interface, keyboard, file, etc.} + +\subsubsection{Assumptions} + +\wss{Try to minimize assumptions and anticipate programmer errors via + exceptions, but for practical purposes assumptions are sometimes appropriate.} + +\subsubsection{Access Routine Semantics} + +\noindent \wss{accessProg}(): +\begin{itemize} +\item transition: \wss{if appropriate} +\item output: \wss{if appropriate} +\item exception: \wss{if appropriate} +\end{itemize} + +\wss{A module without environment variables or state variables is unlikely to + have a state transition. In this case a state transition can only occur if + the module is changing the state of another module.} + +\wss{Modules rarely have both a transition and an output. In most cases you + will have one or the other.} + +\subsubsection{Local Functions} + +\wss{As appropriate} \wss{These functions are for the purpose of specification. + They are not necessarily something that is going to be implemented + explicitly. Even if they are implemented, they are not exported; they only + have local scope.} + +\newpage + +\bibliographystyle {plainnat} +\bibliography {../../../refs/References} + +\newpage + +\section{Appendix} \label{Appendix} + +\wss{Extra information if required} + +\end{document} \ No newline at end of file diff --git a/docs/Design/MIS/Makefile b/docs/Design/MIS/Makefile new file mode 100644 index 0000000..917ebe9 --- /dev/null +++ b/docs/Design/MIS/Makefile @@ -0,0 +1,19 @@ +# Makefile +# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/ + +PROJECT=MIS +TEX=pdflatex +BIBTEX=bibtex +BUILDTEX=$(TEX) $(PROJECT).tex + +all: + $(BUILDTEX) + $(BIBTEX) $(PROJECT) + $(BUILDTEX) + $(BUILDTEX) + +clean-all: + rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~ + +clean: + rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *~ \ No newline at end of file diff --git a/docs/Design/MIS/README.md b/docs/Design/MIS/README.md new file mode 100644 index 0000000..fe3030a --- /dev/null +++ b/docs/Design/MIS/README.md @@ -0,0 +1,2 @@ +# Module Interface Specification # + diff --git a/docs/Design/README.md b/docs/Design/README.md new file mode 100644 index 0000000..da725cc --- /dev/null +++ b/docs/Design/README.md @@ -0,0 +1,5 @@ +# Design Documentation + +The folders and files for this folder are as follows: + +Describe ... diff --git a/docs/DevelopmentPlan/DevelopmentPlan.pdf b/docs/DevelopmentPlan/DevelopmentPlan.pdf new file mode 100644 index 0000000..7e72299 Binary files /dev/null and b/docs/DevelopmentPlan/DevelopmentPlan.pdf differ diff --git a/docs/DevelopmentPlan/DevelopmentPlan.tex b/docs/DevelopmentPlan/DevelopmentPlan.tex new file mode 100644 index 0000000..316d9ad --- /dev/null +++ b/docs/DevelopmentPlan/DevelopmentPlan.tex @@ -0,0 +1,77 @@ +\documentclass{article} + +\usepackage{booktabs} +\usepackage{tabularx} + +\title{Development Plan\\\progname} + +\author{\authname} + +\date{} + +\input{../Comments} +\input{../Common} + +\begin{document} + +\begin{table}[hp] +\caption{Revision History} \label{TblRevisionHistory} +\begin{tabularx}{\textwidth}{llX} +\toprule +\textbf{Date} & \textbf{Developer(s)} & \textbf{Change}\\ +\midrule +Date1 & Name(s) & Description of changes\\ +Date2 & Name(s) & Description of changes\\ +... & ... & ...\\ +\bottomrule +\end{tabularx} +\end{table} + +\newpage + +\maketitle + +\wss{Put your introductory blurb here.} + +\section{Team Meeting Plan} + +\section{Team Communication Plan} + +\section{Team Member Roles} + +\section{Workflow Plan} + +\begin{itemize} + \item How will you be using git, including branches, pull request, etc.? + \item How will you be managing issues, including template issues, issue + classificaiton, etc.? +\end{itemize} + +\section{Proof of Concept Demonstration Plan} + +What is the main risk, or risks, for the success of your project? What will you +demonstrate during your proof of concept demonstration to convince yourself that +you will be able to overcome this risk? + +\section{Technology} + +\begin{itemize} +\item Specific programming language +\item Specific linter tool (if appropriate) +\item Specific unit testing framework +\item Investigation of code coverage measuring tools +\item Specific plans for Continuous Integration (CI), or an explanation that CI + is not being done +\item Specific performance measuring tools (like Valgrind), if + appropriate +\item Libraries you will likely be using? +\item Tools you will likely be using? +\end{itemize} + +\section{Coding Standard} + +\section{Project Scheduling} + +\wss{How will the project be scheduled?} + +\end{document} \ No newline at end of file diff --git a/docs/DevelopmentPlan/Makefile b/docs/DevelopmentPlan/Makefile new file mode 100644 index 0000000..fe2795c --- /dev/null +++ b/docs/DevelopmentPlan/Makefile @@ -0,0 +1,19 @@ +# Makefile +# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/ + +PROJECT=DevelopmentPlan +TEX=pdflatex +BIBTEX=bibtex +BUILDTEX=$(TEX) $(PROJECT).tex + +all: + $(BUILDTEX) +# $(BIBTEX) $(PROJECT) +# $(BUILDTEX) + $(BUILDTEX) + +clean-all: + rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~ + +clean: + rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *~ \ No newline at end of file diff --git a/docs/DevelopmentPlan/README.md b/docs/DevelopmentPlan/README.md new file mode 100644 index 0000000..b6bfa0c --- /dev/null +++ b/docs/DevelopmentPlan/README.md @@ -0,0 +1,5 @@ +# Development Plan + +The folders and files for this folder are as follows: + +Describe ... diff --git a/docs/HazardAnalysis/HazardAnalysis.pdf b/docs/HazardAnalysis/HazardAnalysis.pdf new file mode 100644 index 0000000..5c2af53 Binary files /dev/null and b/docs/HazardAnalysis/HazardAnalysis.pdf differ diff --git a/docs/HazardAnalysis/HazardAnalysis.tex b/docs/HazardAnalysis/HazardAnalysis.tex new file mode 100644 index 0000000..026e1e6 --- /dev/null +++ b/docs/HazardAnalysis/HazardAnalysis.tex @@ -0,0 +1,39 @@ +\documentclass{article} + +\usepackage{booktabs} +\usepackage{tabularx} + +\title{Hazard Analysis\\\progname} + +\author{Team \#, Team Name + \\ Student 1 name and macid + \\ Student 2 name and macid + \\ Student 3 name and macid +} + +\date{} + +\input{../Comments} +\input{../Common} + +\begin{document} + +\begin{table}[hp] +\caption{Revision History} \label{TblRevisionHistory} +\begin{tabularx}{\textwidth}{llX} +\toprule +\textbf{Date} & \textbf{Developer(s)} & \textbf{Change}\\ +\midrule +Date1 & Name(s) & Description of changes\\ +Date2 & Name(s) & Description of changes\\ +... & ... & ...\\ +\bottomrule +\end{tabularx} +\end{table} + +\newpage + +\maketitle + + +\end{document} \ No newline at end of file diff --git a/docs/HazardAnalysis/Makefile b/docs/HazardAnalysis/Makefile new file mode 100644 index 0000000..de8103a --- /dev/null +++ b/docs/HazardAnalysis/Makefile @@ -0,0 +1,19 @@ +# Makefile +# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/ + +PROJECT=HazardAnalysis +TEX=pdflatex +BIBTEX=bibtex +BUILDTEX=$(TEX) $(PROJECT).tex + +all: + $(BUILDTEX) +# $(BIBTEX) $(PROJECT) +# $(BUILDTEX) + $(BUILDTEX) + +clean-all: + rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~ + +clean: + rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *~ \ No newline at end of file diff --git a/docs/HazardAnalysis/README.md b/docs/HazardAnalysis/README.md new file mode 100644 index 0000000..90387c6 --- /dev/null +++ b/docs/HazardAnalysis/README.md @@ -0,0 +1,5 @@ +# Hazard Analysis + +The folders and files for this folder are as follows: + +Describe ... diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..97ed65c --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,67 @@ +# Makefile +# TODO: Missing artifacts should be added to this file +.PHONY: SRS + +all: SRS MG MIS PS VnVP VnVR DevP HazA Refl UGde + +SRS: + cd SRS && make && cd .. + +MG: + cd Design/MG && make && cd ../.. + +MIS: + cd Design/MIS && make && cd ../.. + +PS: + cd ProblemStatementAndGoals && make && cd .. + +VnVP: + cd VnVPlan && make && cd ../.. + +VnVR: + cd VnVReport && make && cd ../.. + +DevP: + cd DevelopmentPlan && make && cd ../.. + +HazA: + cd HazardAnalysis && make && cd ../.. + +Refl: + cd Reflection && make && cd ../.. + +UGde: + cd UserGuide && make && cd ../.. + +clean: cleanSRS cleanMG cleanMIS cleanPS cleanVnVP cleanVnVR cleanDevP cleanHazA cleanRefl cleanUGde + +cleanPS: + cd ProblemStatementAndGoals && make clean && cd .. + +cleanSRS: + cd SRS && make clean && cd .. + +cleanMG: + cd Design/MG && make clean && cd .. + +cleanMIS: + cd Design/MIS && make clean && cd .. + +cleanVnVP: + cd VnVPlan && make clean && cd .. + +cleanVnVR: + cd VnVReport && make clean && cd .. + +cleanDevP: + cd DevelopmentPlan && make clean && cd .. + +cleanHazA: + cd HazardAnalysis && make clean && cd .. + +cleanRefl: + cd Reflection && make clean && cd .. + +cleanUGde: + cd UserGuide && make clean && cd .. diff --git a/docs/Presentations/EXPO/README.md b/docs/Presentations/EXPO/README.md new file mode 100644 index 0000000..59b56a7 --- /dev/null +++ b/docs/Presentations/EXPO/README.md @@ -0,0 +1,5 @@ +# EXPO Poster + +The folders and files for this folder are as follows: + +- \ No newline at end of file diff --git a/docs/Presentations/FinalPresentation/README.md b/docs/Presentations/FinalPresentation/README.md new file mode 100644 index 0000000..29134c9 --- /dev/null +++ b/docs/Presentations/FinalPresentation/README.md @@ -0,0 +1,5 @@ +# Final Presentation + +The folders and files for this folder are as follows: + +Describe ... diff --git a/docs/Presentations/ProofOfConceptDemo/README.md b/docs/Presentations/ProofOfConceptDemo/README.md new file mode 100644 index 0000000..0535375 --- /dev/null +++ b/docs/Presentations/ProofOfConceptDemo/README.md @@ -0,0 +1 @@ +# Proof of Concept Demonstration \ No newline at end of file diff --git a/docs/Presentations/README.md b/docs/Presentations/README.md new file mode 100644 index 0000000..d4c6299 --- /dev/null +++ b/docs/Presentations/README.md @@ -0,0 +1,5 @@ +# Presentations about your software + +The folders and files for this folder are as follows: + +- \ No newline at end of file diff --git a/docs/Presentations/Rev0Presentation/README.md b/docs/Presentations/Rev0Presentation/README.md new file mode 100644 index 0000000..2fab6e9 --- /dev/null +++ b/docs/Presentations/Rev0Presentation/README.md @@ -0,0 +1,5 @@ +# REV0 Presentation + +The folders and files for this folder are as follows: + +- \ No newline at end of file diff --git a/docs/ProblemStatementAndGoals/Makefile b/docs/ProblemStatementAndGoals/Makefile new file mode 100644 index 0000000..2e33d89 --- /dev/null +++ b/docs/ProblemStatementAndGoals/Makefile @@ -0,0 +1,19 @@ +# Makefile +# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/ + +PROJECT=ProblemStatement +TEX=pdflatex +BIBTEX=bibtex +BUILDTEX=$(TEX) $(PROJECT).tex + +all: + $(BUILDTEX) +# $(BIBTEX) $(PROJECT) +# $(BUILDTEX) + $(BUILDTEX) + +clean-all: + rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~ + +clean: + rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *~ \ No newline at end of file diff --git a/docs/ProblemStatementAndGoals/ProblemStatement.pdf b/docs/ProblemStatementAndGoals/ProblemStatement.pdf new file mode 100644 index 0000000..831ccdb Binary files /dev/null and b/docs/ProblemStatementAndGoals/ProblemStatement.pdf differ diff --git a/docs/ProblemStatementAndGoals/ProblemStatement.tex b/docs/ProblemStatementAndGoals/ProblemStatement.tex new file mode 100644 index 0000000..0b4bf12 --- /dev/null +++ b/docs/ProblemStatementAndGoals/ProblemStatement.tex @@ -0,0 +1,56 @@ +\documentclass{article} + +\usepackage{tabularx} +\usepackage{booktabs} + +\title{Problem Statement and Goals\\\progname} + +\author{\authname} + +\date{} + +\input{../Comments} +\input{../Common} + +\begin{document} + +\maketitle + +\begin{table}[hp] +\caption{Revision History} \label{TblRevisionHistory} +\begin{tabularx}{\textwidth}{llX} +\toprule +\textbf{Date} & \textbf{Developer(s)} & \textbf{Change}\\ +\midrule +Date1 & Name(s) & Description of changes\\ +Date2 & Name(s) & Description of changes\\ +... & ... & ...\\ +\bottomrule +\end{tabularx} +\end{table} + +\section{Problem Statement} + +\wss{You should check your problem statement with the +\href{https://github.com/smiths/capTemplate/blob/main/docs/Checklists/ProbState-Checklist.pdf} +{problem statement checklist}.} +\wss{You can change the section headings, as long as you include the required information.} + +\subsection{Problem} + +\subsection{Inputs and Outputs} + +\wss{Characterize the problem in terms of ``high level'' inputs and outputs. +Use abstraction so that you can avoid details.} + +\subsection{Stakeholders} + +\subsection{Environment} + +\wss{Hardware and software} + +\section{Goals} + +\section{Stretch Goals} + +\end{document} \ No newline at end of file diff --git a/docs/ProblemStatementAndGoals/README.md b/docs/ProblemStatementAndGoals/README.md new file mode 100644 index 0000000..e5c5ef4 --- /dev/null +++ b/docs/ProblemStatementAndGoals/README.md @@ -0,0 +1,5 @@ +# Problem Statement + +The folders and files for this folder are as follows: + +Describe ... diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b946aa7 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,23 @@ + + + + + + + + + + +# Documentation folders + +The folders and files for this folder are as follows: + +Describe ... \ No newline at end of file diff --git a/docs/Reflection/Makefile b/docs/Reflection/Makefile new file mode 100644 index 0000000..d9890e9 --- /dev/null +++ b/docs/Reflection/Makefile @@ -0,0 +1,19 @@ +# Makefile +# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/ + +PROJECT=Reflection +TEX=pdflatex +BIBTEX=bibtex +BUILDTEX=$(TEX) $(PROJECT).tex + +all: + $(BUILDTEX) +# $(BIBTEX) $(PROJECT) +# $(BUILDTEX) + $(BUILDTEX) + +clean-all: + rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~ + +clean: + rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *~ \ No newline at end of file diff --git a/docs/Reflection/README.md b/docs/Reflection/README.md new file mode 100644 index 0000000..b6bfa0c --- /dev/null +++ b/docs/Reflection/README.md @@ -0,0 +1,5 @@ +# Development Plan + +The folders and files for this folder are as follows: + +Describe ... diff --git a/docs/Reflection/Reflection.pdf b/docs/Reflection/Reflection.pdf new file mode 100644 index 0000000..625c7d0 Binary files /dev/null and b/docs/Reflection/Reflection.pdf differ diff --git a/docs/Reflection/Reflection.tex b/docs/Reflection/Reflection.tex new file mode 100644 index 0000000..0e40c10 --- /dev/null +++ b/docs/Reflection/Reflection.tex @@ -0,0 +1,52 @@ +\documentclass{article} + +\usepackage{tabularx} +\usepackage{booktabs} + +\title{Reflection Report on \progname} + +\author{author name} + +\date{} + +\input{../Comments} +\input{../Common} + +\begin{document} + +\begin{table}[hp] +\caption{Revision History} \label{TblRevisionHistory} +\begin{tabularx}{\textwidth}{llX} +\toprule +\textbf{Date} & \textbf{Developer(s)} & \textbf{Change}\\ +\midrule +Date1 & Name(s) & Description of changes\\ +Date2 & Name(s) & Description of changes\\ +... & ... & ...\\ +\bottomrule +\end{tabularx} +\end{table} + +\newpage + +\maketitle + +Put your introductory blurb here. + +\section{Project Overview} + +\plt{Summarize the original project goals and requirements} + +\section{Key Accomplishments} + +\plt{What went well? This can be what went well with the documentation, the + coding, the project management, etc.} + +\section{Key Problem Areas} + +\plt{What went wrong? This can be what went wrong with the documentation, the + technology, the coding, time management, etc.} + +\section{What Would you Do Differently Next Time} + +\end{document} \ No newline at end of file diff --git a/docs/SRS/CA.pdf b/docs/SRS/CA.pdf new file mode 100644 index 0000000..2abc06f Binary files /dev/null and b/docs/SRS/CA.pdf differ diff --git a/docs/SRS/CA.tex b/docs/SRS/CA.tex new file mode 100644 index 0000000..6b620a3 --- /dev/null +++ b/docs/SRS/CA.tex @@ -0,0 +1,526 @@ +\documentclass[12pt]{article} + +\usepackage{amsmath, mathtools} +\usepackage{amsfonts} +\usepackage{amssymb} +\usepackage{graphicx} +\usepackage{colortbl} +\usepackage{xr} +\usepackage{hyperref} +\usepackage{longtable} +\usepackage{xfrac} +\usepackage{tabularx} +\usepackage{float} +\usepackage{siunitx} +\usepackage{booktabs} +\usepackage{caption} +\usepackage{pdflscape} +\usepackage{afterpage} + +\usepackage[round]{natbib} + +%\usepackage{refcheck} + +\hypersetup{ + bookmarks=true, % show bookmarks bar? + colorlinks=true, % false: boxed links; true: colored links + linkcolor=red, % color of internal links (change box color with linkbordercolor) + citecolor=green, % color of links to bibliography + filecolor=magenta, % color of file links + urlcolor=cyan % color of external links +} + +\input{../Comments} + +% For easy change of table widths +\newcommand{\colZwidth}{1.0\textwidth} +\newcommand{\colAwidth}{0.13\textwidth} +\newcommand{\colBwidth}{0.82\textwidth} +\newcommand{\colCwidth}{0.1\textwidth} +\newcommand{\colDwidth}{0.05\textwidth} +\newcommand{\colEwidth}{0.8\textwidth} +\newcommand{\colFwidth}{0.17\textwidth} +\newcommand{\colGwidth}{0.5\textwidth} +\newcommand{\colHwidth}{0.28\textwidth} + +% Used so that cross-references have a meaningful prefix +\newcounter{defnum} %Definition Number +\newcommand{\dthedefnum}{GD\thedefnum} +\newcommand{\dref}[1]{GD\ref{#1}} +\newcounter{datadefnum} %Datadefinition Number +\newcommand{\ddthedatadefnum}{DD\thedatadefnum} +\newcommand{\ddref}[1]{DD\ref{#1}} +\newcounter{theorynum} %Theory Number +\newcommand{\tthetheorynum}{T\thetheorynum} +\newcommand{\tref}[1]{T\ref{#1}} +\newcounter{tablenum} %Table Number +\newcommand{\tbthetablenum}{T\thetablenum} +\newcommand{\tbref}[1]{TB\ref{#1}} +\newcounter{assumpnum} %Assumption Number +\newcommand{\atheassumpnum}{P\theassumpnum} +\newcommand{\aref}[1]{A\ref{#1}} +\newcounter{goalnum} %Goal Number +\newcommand{\gthegoalnum}{P\thegoalnum} +\newcommand{\gsref}[1]{GS\ref{#1}} +\newcounter{instnum} %Instance Number +\newcommand{\itheinstnum}{IM\theinstnum} +\newcommand{\iref}[1]{IM\ref{#1}} +\newcounter{reqnum} %Requirement Number +\newcommand{\rthereqnum}{P\thereqnum} +\newcommand{\rref}[1]{R\ref{#1}} +\newcounter{lcnum} %Likely change number +\newcommand{\lthelcnum}{LC\thelcnum} +\newcommand{\lcref}[1]{LC\ref{#1}} + +\newcommand{\famname}{FamName} % PUT YOUR PROGRAM NAME HERE + +\usepackage{fullpage} + +\begin{document} + +\title{Program Family Title \plt{\famname should appear in the title}} +\author{Author Name} +\date{\today} + +\maketitle + +~\newpage + +\pagenumbering{roman} + +\plt{The CA template is related to the SRS template. Many of the +sections are in common. The notes and advice for the SRS template are +not reproduced here. Please have a look at the SRS template for advice.} + + +\plt{This CA template is based on \citet{Smith2006}. An example for a family of + material models is given in \citet{SmithMcCutchanAndCarette2017}. This + example is for a physics based family. Often the families will be based on + generic numerical techniques, rather than physics.} + +\plt{A good mindset for thinking about the families is often to think of the + family as providing a library of services, as opposed to a single executable. + The library of services can be used to build an application that uses a subset + of the services, which is like providing the smaller library as a single + family member.} + +\section{Revision History} + +\begin{tabularx}{\textwidth}{p{3cm}p{2cm}X} +\toprule {\bf Date} & {\bf Version} & {\bf Notes}\\ +\midrule +Date 1 & 1.0 & Notes\\ +Date 2 & 1.1 & Notes\\ +\bottomrule +\end{tabularx} + +~\newpage + +\section{Reference Material} + +This section records information for easy reference. + +\subsection{Table of Units} + +Throughout this document SI (Syst\`{e}me International d'Unit\'{e}s) is employed +as the unit system. In addition to the basic units, several derived units are +used as described below. For each unit, the symbol is given followed by a +description of the unit and the SI name. +~\newline + +\renewcommand{\arraystretch}{1.2} +%\begin{table}[ht] + \noindent \begin{tabular}{l l l} + \toprule + \textbf{symbol} & \textbf{unit} & \textbf{SI}\\ + \midrule + \si{\metre} & length & metre\\ + \si{\kilogram} & mass & kilogram\\ + \si{\second} & time & second\\ + \si{\celsius} & temperature & centigrade\\ + \si{\joule} & energy & Joule\\ + \si{\watt} & power & Watt (W = \si{\joule\per\second})\\ + \bottomrule + \end{tabular} + % \caption{Provide a caption} +%\end{table} + +\plt{Only include the units that your CA actually uses. If there are no units + for your problem, like for a general purpose library, you should still include +the heading, with the content ``not applicable'' (or similar).} + +\subsection{Table of Symbols} + +The table that follows summarizes the symbols used in this document along with +their units. The choice of symbols was made to be consistent with the heat +transfer literature and with existing documentation for solar water heating +systems. The symbols are listed in alphabetical order. + +\renewcommand{\arraystretch}{1.2} +%\noindent \begin{tabularx}{1.0\textwidth}{l l X} +\noindent \begin{longtable*}{l l p{12cm}} \toprule +\textbf{symbol} & \textbf{unit} & \textbf{description}\\ +\midrule +$A_C$ & \si[per-mode=symbol] {\square\metre} & coil surface area +\\ +$A_\text{in}$ & \si[per-mode=symbol] {\square\metre} & surface area over +which heat is transferred in +\\ +\bottomrule +\end{longtable*} +\plt{Use your problems actual symbols. The si package is a good idea to use for + units.} +\plt{For the case of a generic numerical library, units will likely not be + included. For instance, a linear ODE solver will not know the units of its + coefficients.} + +\subsection{Abbreviations and Acronyms} + +\renewcommand{\arraystretch}{1.2} +\begin{tabular}{l l} + \toprule + \textbf{symbol} & \textbf{description}\\ + \midrule + A & Assumption\\ + DD & Data Definition\\ + GD & General Definition\\ + GS & Goal Statement\\ + IM & Instance Model\\ + LC & Likely Change\\ + PS & Physical System Description\\ + R & Requirement\\ + SRS & Software Requirements Specification\\ + \famname{} & \plt{put your famram name here}\\ + T & Theoretical Model\\ + \bottomrule +\end{tabular}\\ + +\plt{Add any other abbreviations or acronyms that you add.} +\plt{Only include abbreviations and acronyms that are actually used.} + +\newpage + +\tableofcontents + +~\newpage + +\pagenumbering{arabic} + +\section{Introduction} + +\plt{This CA template is based on \citet{Smith2006}. It + will get you started, but you will have to make changes. Any changes to + section headings should be approved by the instructor, since that implies a + deviation from the template. Although the bits shown below do not include + type information, you may need to add this information for your problem.} + +\plt{Feel free to change the appearance of the report by modifying the LaTeX + commands.} + +\subsection{Purpose of Document} + +\subsection{Scope of the Family} + +\subsection{Characteristics of Intended Reader} + +\subsection{Organization of Document} + +\section{General System Description} + +This section identifies the interfaces between the system and its environment, +describes the potential user characteristics and lists the potential system +constraints. + +\subsection{Potential System Contexts} + +\plt{Your system context will likely include an explicit list of user and system + responsibilities} + +\begin{itemize} +\item User Responsibilities: +\begin{itemize} +\item +\end{itemize} +\item \famname{} Responsibilities: +\begin{itemize} +\item Detect data type mismatch, such as a string of characters instead of a + floating point number +\item +\end{itemize} +\end{itemize} + +\subsection{Potential User Characteristics} \label{SecUserCharacteristics} + +The end user of \famname{} should have an understanding of undergraduate Level +1 Calculus and Physics. + +\subsection{Potential System Constraints} + +\plt{You may not have any system constraints.} + +\plt{If you need to make design decisions for your family, these decisions will + be made here as constraints. For instance, if all inputs will have to use the +same file format, this would be a constraint that would be included here.} + +\plt{You should generally limit the number of constraints, to keep the CA + abstract.} + +\section{Commonalities} + +\subsection{Background Overview} \label{Sec_Background} + +\subsection{Terminology and Definitions} + +This subsection provides a list of terms that are used in the subsequent +sections and their meaning, with the purpose of reducing ambiguity and making it +easier to correctly understand the requirements: + +\begin{itemize} + +\item + +\end{itemize} + +\subsection{Data Definitions} \label{sec_datadef} + +This section collects and defines all the data needed to build the instance +models. The dimension of each quantity is also given. \plt{Modify the examples + below for your problem, and add additional definitions as appropriate.} + +~\newline + +\noindent +\begin{minipage}{\textwidth} +\renewcommand*{\arraystretch}{1.5} +\begin{tabular}{| p{\colAwidth} | p{\colBwidth}|} +\hline +\rowcolor[gray]{0.9} +Number& DD\refstepcounter{datadefnum}\thedatadefnum \label{FluxCoil}\\ +\hline +Label& \bf Heat flux out of coil\\ +\hline +Symbol &$q_C$\\ +\hline +% Units& $Mt^{-3}$\\ +% \hline + SI Units & \si{\watt\per\square\metre}\\ + \hline + Equation&$q_C(t) = h_C (T_C - T_W(t))$, over area $A_C$\\ + \hline + Description & + $T_C$ is the temperature of the coil (\si{\celsius}). $T_W$ is the temperature of the water (\si{\celsius}). + The heat flux out of the coil, $q_C$ (\si{\watt\per\square\metre}), is found by + assuming that Newton's Law + of Cooling applies (\aref{A_Newt_coil}). This law (\dref{NL}) is used on the surface of + the coil, which has area $A_C$ (\si{\square\metre}) and heat + transfer coefficient $h_C$ + (\si{\watt\per\square\metre\per\celsius}). This equation + assumes that the temperature of the coil is constant over time (\aref{A_tcoil}) and that it does not vary along the length + of the coil (\aref{A_tlcoil}). + \\ + \hline + Sources& Citation here\\ + \hline + Ref.\ By & \iref{ewat}\\ + \hline +\end{tabular} +\end{minipage}\\ + +\subsection{Goal Statements} + +\noindent Given the \plt{inputs}, the goal statements are: + +\begin{itemize} + +\item[GS\refstepcounter{goalnum}\thegoalnum \label{G_meaningfulLabel}:] \plt{One + sentence description of the goal. There may be more than one. Each Goal + should have a meaningful label.} + +\end{itemize} + +\subsection{Theoretical Models} \label{sec_theoretical} + +This section focuses on the general equations and laws that \famname{} is based +on. \plt{Modify the examples below for your problem, and add additional models + as appropriate.} + +~\newline + +\noindent +\begin{minipage}{\textwidth} +\renewcommand*{\arraystretch}{1.5} +\begin{tabular}{| p{\colAwidth} | p{\colBwidth}|} + \hline + \rowcolor[gray]{0.9} + Number& T\refstepcounter{theorynum}\thetheorynum \label{T_COE}\\ + \hline + Label&\bf Conservation of thermal energy\\ + \hline + Equation& $-{\bf \nabla \cdot q} + g$ = $\rho C \frac{\partial T}{\partial t}$\\ + \hline + Description & + The above equation gives the conservation of energy for transient heat transfer in a material + of specific heat capacity $C$ (\si{\joule\per\kilogram\per\celsius}) and density $\rho$ + (\si{\kilogram\per\cubic\metre}), where $\bf q$ is the thermal flux vector (\si{\watt\per\square\metre}), + $g$ is the volumetric heat generation + (\si{\watt\per\cubic\metre}), $T$ is the temperature + (\si{\celsius}), $t$ is time (\si{\second}), and $\nabla$ is + the gradient operator. For this equation to apply, other forms + of energy, such as mechanical energy, are assumed to be negligible in the + system (\aref{A_OnlyThermalEnergy}). In general, the material properties ($\rho$ and $C$) depend on temperature.\\ + \hline + Source & + \url{http://www.efunda.com/formulae/heat_transfer/conduction/overview_cond.cfm}\\ + % The above web link should be replaced with a proper citation to a publication + \hline + Ref.\ By & \dref{ROCT}\\ + \hline +\end{tabular} +\end{minipage}\\ + +~\newline + +\plt{In a CA, the TMs often do not need to be refined. However, this is not a + rule. In some cases, it may make sense to introduce an IM, or possibly even a + GD in between the TM and the IM.} + +\section{Variabilities} + +\plt{The variabilities are summarized in the following subsections. They may + each be summarized separately, like in \citet{SmithMcCutchanAndCarette2017}, or + in a table, as in \citet{Smith2006}.} + +\plt{For each variability, a description should be given, along with the + parameters of variation and the binding time. The parameters of variation + give the type that defines possible values. The binding time is when the + variability is set. The possible values are specification time (scope time), + build time and run time.} + +\subsection{Assumptions} + +\begin{itemize} + +\item[A\refstepcounter{assumpnum}\theassumpnum \label{A_meaningfulLabel}:] + \plt{Short description of each assumption. Each assumption + should have a meaningful label. Use cross-references to identify the + appropriate traceability to T, GD, DD etc., using commands like dref, ddref etc.} + +\end{itemize} + +\plt{Input assumptions will be appropriate for many problems. Some input will + have simplifying constraints, and other inputs will not.} + +\subsection{Calculation} \label{sec_Calculation} + +\plt{The calculation variabilities should be as abstract as possible. If there + are variabilities that are related to imposed design decisions, the system + constraints section should be referenced for the relevant constraint. Design + constraint related variabilities should be listed separately.} + +\plt{Variabilities related to data structure choices would go in this section. + However, these variabilities are related to design, so they should be + separated from the more abstract variabilities.} + +\plt{Algorithmic variations would go here as well, but as for data structures, + they should be separated from the more abstract variabilities.} + +\subsection{Output} \label{sec_Output} + +\section{Requirements} + +This section provides the functional requirements, the business tasks that the +software is expected to complete, and the nonfunctional requirements, the +qualities that the software is expected to exhibit. + +\subsection{Family of Functional Requirements} + +\plt{Since the CA will often be applied to a library, the functionality will not + be a single use case. Therefore, this section should summarize the family of + potential requirements. A good way to provide an overview of the functional + requirements would be to provide multiple use cases on how the library will be + employed.} + +\noindent \begin{itemize} + +\item[R\refstepcounter{reqnum}\thereqnum \label{R_Inputs}:] \plt{Requirements + for the inputs that are supplied by the user. This information has to be + explicit.} + +\item[R\refstepcounter{reqnum}\thereqnum \label{R_OutputInputs}:] \plt{It isn't + always required, but often echoing the inputs as part of the output is a + good idea.} + +\item[R\refstepcounter{reqnum}\thereqnum \label{R_Calculate}:] \plt{Calculation + related requirements.} + +\item[R\refstepcounter{reqnum}\thereqnum \label{R_VerifyOutput}:] + \plt{Verification related requirements.} + +\item[R\refstepcounter{reqnum}\thereqnum \label{R_Output}:] \plt{Output related + requirements.} + +\end{itemize} + +\subsection{Nonfunctional Requirements} + +\plt{To allow the Non-Functional Requirements (NFRs) to vary between family + members, try to parameterize them. The value of the parameter is than a variability.} + +\plt{An important variability between family members it the relative importance + of the NFRs. \citet{Smith2006} shows how pairwise comparisons can be used to + rank the importance of NFRs.} + +\plt{List your nonfunctional requirements. You may consider using a fit + criterion to make them verifiable.} + +\section{Likely Changes} + +\noindent \begin{itemize} + +\item[LC\refstepcounter{lcnum}\thelcnum\label{LC_meaningfulLabel}:] \plt{If + there is a ranking of variabilities, or combinations of variabilities, that + are more likely, this information can be included here.} + +\end{itemize} + +\section{Traceability Matrices and Graphs} + +\plt{You will have to add tables.} + +\newpage + +\bibliographystyle {plainnat} +\bibliography {../../refs/References} + +\newpage + +\section{Appendix} + +\plt{Your report may require an appendix. For instance, this is a good point to +show the values of the symbolic parameters introduced in the report.} + +\subsection{Symbolic Parameters} + +\plt{The definition of the requirements will likely call for SYMBOLIC\_CONSTANTS. +Their values are defined in this section for easy maintenance.} + +\noindent \plt{Advice on using the template: +\begin{itemize} +\item Assumptions have to be invoked somewhere +\item ``Referenced by'' implies that there is an explicit reference +\item Think of traceability matrix, list of assumption invocations and list of + reference by fields as automatically generatable +\item If you say the format of the output (plot, table etc), then your + requirement could be more abstract +\item For families the notion of binding time should be introduced +\item Think of families as a library, not as a single program +\end{itemize} +} + +\subsection{First Stage of Implementation} + +\plt{In this section specify the family member, or sub-family, that you will be + implementing. You should specify the value for all of your + variabilities, along with the binding time. A tabular representation will + probably be the easiest way to convey this information.} +\end{document} \ No newline at end of file diff --git a/docs/SRS/Makefile b/docs/SRS/Makefile new file mode 100644 index 0000000..2966945 --- /dev/null +++ b/docs/SRS/Makefile @@ -0,0 +1,19 @@ +# Makefile +# From https://danielkaes.wordpress.com/2009/03/14/compiling-latex-documents-using-makefiles/ + +PROJECT=SRS #SRS or CA +TEX=pdflatex +BIBTEX=bibtex +BUILDTEX=$(TEX) $(PROJECT).tex + +all: + $(BUILDTEX) + $(BIBTEX) $(PROJECT) + $(BUILDTEX) + $(BUILDTEX) + +clean-all: + rm -f *.dvi *.log *.bak *.aux *.bbl *.blg *.idx *.ps *.eps *.pdf *.toc *.out *~ + +clean: + rm -f *.log *.bak *.aux *.bbl *.blg *.idx *.toc *.out *.synctex.gz *~ \ No newline at end of file diff --git a/docs/SRS/README.md b/docs/SRS/README.md new file mode 100644 index 0000000..596a98d --- /dev/null +++ b/docs/SRS/README.md @@ -0,0 +1,10 @@ +# Software Requirements Specification (SRS) and Commonality Analysis (CA) + + + +The folders and files for this folder are as follows: + +Describe ... + +Only one of the CA or SRS document should be completed diff --git a/docs/SRS/RelationsBetweenTM_GD_IM_DD_A.pdf b/docs/SRS/RelationsBetweenTM_GD_IM_DD_A.pdf new file mode 100644 index 0000000..7a18d19 Binary files /dev/null and b/docs/SRS/RelationsBetweenTM_GD_IM_DD_A.pdf differ diff --git a/docs/SRS/SRS-FAQ.pdf b/docs/SRS/SRS-FAQ.pdf new file mode 100644 index 0000000..6f0517d Binary files /dev/null and b/docs/SRS/SRS-FAQ.pdf differ diff --git a/docs/SRS/SRS-FAQ.tex b/docs/SRS/SRS-FAQ.tex new file mode 100644 index 0000000..e00c965 --- /dev/null +++ b/docs/SRS/SRS-FAQ.tex @@ -0,0 +1,122 @@ +\documentclass[12pt]{article} + +\usepackage{hyperref} +\hypersetup{colorlinks=true, + linkcolor=blue, + citecolor=blue, + filecolor=blue, + urlcolor=blue, + unicode=false} +\urlstyle{same} + +\begin{document} + +\title{SRS Frequently Asked Questions} +\author{Spencer Smith} +\date{\today} + +\maketitle + +A list of Frequently Asked Questions are given below. The answer to the +question is shown below the question, in italic font. + +\begin{enumerate} + +\item If we are solving an ``intermediate problem,'' should we state the + output(s) of that step or we should only talk about the raw inputs of the + software and ultimate outputs?" \medskip + + \emph{Without any other qualifying information, I would say that the + intermediate steps are not relevant in the SRS. The SRS should be abstract. + It should say what we want, not how to calculate it. However, the world of + requirements specification doesn't always lend itself to an absolute answer. + :-) There are definitely cases where the best course of action is to + describe how to get from $a$ to $c$ by first passing through $b$. The cases where + specifying the intermediate steps makes sense are as follows: + \begin{enumerate} + \item If the intermediate steps have value on their own, then they should be + included as a goal. For instance, in the Solar Water Heating System + example the energy in the water and the PCM depends on the temperatures. + If the ultimate goal was to know the energies, it still would make sense + to output the temperatures, since they have value on their own. + \item If the intermediate steps make the specification clearer, or easier to + understand, they should be included. Although a specification should say + what is desired, there are cases where the appropriate way to specify + ``what'' is to say ``how.'' This is called an operational specification. An + operational specification gives the steps for the intended behaviour. All + other things being equal, our preference is still a descriptive specification. + A descriptive specification says what is required in terms of the desired + properties, without reference to how it will be done. As an example, a + descriptive specification for finding the minimum of a list would describe + what is meant by minimum. A descriptive specification would say that the + output is the element of the list that is equal to or less than all other + elements. The corresponding operational specification would give the + algorithm for finding the minimum. The topic of operational versus + descriptive specification is covered further in these + \href{https://gitlab.cas.mcmaster.ca/smiths/se2aa4_cs2me3/-/blob/master/Lectures/L25_IntroToSpecContinued/IntroToSpecContinued.pdf} + {slides} (starting around slide 22). One of the points on operational + specifications that sometimes confuses students is that the operational + specification is phrased in terms of ``how,'' but the intention is still to + say ``what.'' That is, the implementation is not required to use the steps + given for how, as long as the results match the what. In the above + example, the operational specification for the minimum of a list gives an + algorithm, but the implementation is free to use any algorithm, as long as + the output returned matches the output that would be returned by following + the operational specification. + \end{enumerate} + In the SRS intermediate calculations can come through supporting theoretical + models, general definitions, instance models and/or data definitions. The + short answer to the original question is that sometimes it makes sense to + include an intermediate problem in the specification, and sometimes it + doesn't. A generalization isn't really possible. The answer depends on the + specific problem at hand. \smallskip} + +\item If your work depends on other applications or libraries, how does this + show up in the SRS? \medskip + + \emph{The first thought may be that you should assume that the libraries are + available; that is, that you should capture this information through + assumptions. I can see why assuming that a library exists might be called + an assumption, but this isn't the best location for this information. + Assumptions are used to refine the scope; they take a very general problem + and turn it into something that we have a hope of solving. For instance, + assuming that a function is differentiable is needed for many theoretical + proofs. This assumptions is saying that the software won't work for all + functions; the class of functions that will work has been restricted. + Assumptions refine ``what'' you are solving; they don't refine ``how'' you + are going to solve the problem. Building on the work of others is relevant + to make the problem feasible, but it isn't technically needed to make the + problem solvable.} + + \emph{There are two spot in the SRS to show that you are building on the work + of others: System Context and System Constraints. The System Context shows + the boundary between your software and the environment in which it works. + If the software will depend on services from other libraries, the + availability of these services should be mentioned. In the system context + diagram there would be other boxes that your program would point to. You + are then explicitly saying that your program will depend on these services. + Ideally, the services will be given generic names. That is, unless you have + no choice, you should leave it open as to which library will actually + provide the services. In this way you keep your document abstract. + However, there are cases where the design decision is imposed on you. In + these cases you would include the names of the specific library, or + libraries, as System Constraints (and list them in the corresponding section + of the SRS).} + +\item As I work on my Verification and Validation plan I find part of the SRS + should be changed. What should I do? \medskip + + \emph{This is completely natural and expected. Students in the class make + this observation every year. We cannot really have perfect knowledge when + we are writing the first draft of our SRS. We learn by jumping in and + starting the documentation. As we get further in the project our + understanding improves.} + + \emph{This is why we have two ``official'' iterations of the SRS in the + course. You should also have many sub-iterations as the term goes along. Our + aim is to have documentation at the end of the course that fakes a rational + design process.} + +\end{enumerate} + +\end{document} diff --git a/docs/SRS/SRS.pdf b/docs/SRS/SRS.pdf new file mode 100644 index 0000000..fdd81d9 Binary files /dev/null and b/docs/SRS/SRS.pdf differ diff --git a/docs/SRS/SRS.tex b/docs/SRS/SRS.tex new file mode 100644 index 0000000..fcac193 --- /dev/null +++ b/docs/SRS/SRS.tex @@ -0,0 +1,1316 @@ +\documentclass[12pt]{article} + +\usepackage{amsmath, mathtools} +\usepackage{amsfonts} +\usepackage{amssymb} +\usepackage{graphicx} +\usepackage{colortbl} +\usepackage{xr} +\usepackage{hyperref} +\usepackage{longtable} +\usepackage{xfrac} +\usepackage{tabularx} +\usepackage{float} +\usepackage{siunitx} +\usepackage{booktabs} +\usepackage{caption} +\usepackage{pdflscape} +\usepackage{afterpage} + +\usepackage[round]{natbib} + +%\usepackage{refcheck} + +\hypersetup{ + bookmarks=true, % show bookmarks bar? + colorlinks=true, % false: boxed links; true: colored links + linkcolor=red, % color of internal links (change box color with linkbordercolor) + citecolor=green, % color of links to bibliography + filecolor=magenta, % color of file links + urlcolor=cyan % color of external links +} + +\input{../Comments} +\input{../Common} + +% For easy change of table widths +\newcommand{\colZwidth}{1.0\textwidth} +\newcommand{\colAwidth}{0.13\textwidth} +\newcommand{\colBwidth}{0.82\textwidth} +\newcommand{\colCwidth}{0.1\textwidth} +\newcommand{\colDwidth}{0.05\textwidth} +\newcommand{\colEwidth}{0.8\textwidth} +\newcommand{\colFwidth}{0.17\textwidth} +\newcommand{\colGwidth}{0.5\textwidth} +\newcommand{\colHwidth}{0.28\textwidth} + +% Used so that cross-references have a meaningful prefix +\newcounter{defnum} %Definition Number +\newcommand{\dthedefnum}{GD\thedefnum} +\newcommand{\dref}[1]{GD\ref{#1}} +\newcounter{datadefnum} %Datadefinition Number +\newcommand{\ddthedatadefnum}{DD\thedatadefnum} +\newcommand{\ddref}[1]{DD\ref{#1}} +\newcounter{theorynum} %Theory Number +\newcommand{\tthetheorynum}{T\thetheorynum} +\newcommand{\tref}[1]{T\ref{#1}} +\newcounter{tablenum} %Table Number +\newcommand{\tbthetablenum}{T\thetablenum} +\newcommand{\tbref}[1]{TB\ref{#1}} +\newcounter{assumpnum} %Assumption Number +\newcommand{\atheassumpnum}{P\theassumpnum} +\newcommand{\aref}[1]{A\ref{#1}} +\newcounter{goalnum} %Goal Number +\newcommand{\gthegoalnum}{P\thegoalnum} +\newcommand{\gsref}[1]{GS\ref{#1}} +\newcounter{instnum} %Instance Number +\newcommand{\itheinstnum}{IM\theinstnum} +\newcommand{\iref}[1]{IM\ref{#1}} +\newcounter{reqnum} %Requirement Number +\newcommand{\rthereqnum}{P\thereqnum} +\newcommand{\rref}[1]{R\ref{#1}} +\newcounter{nfrnum} %NFR Number +\newcommand{\rthenfrnum}{NFR\thenfrnum} +\newcommand{\nfrref}[1]{NFR\ref{#1}} +\newcounter{lcnum} %Likely change number +\newcommand{\lthelcnum}{LC\thelcnum} +\newcommand{\lcref}[1]{LC\ref{#1}} + +\usepackage{fullpage} + +\newcommand{\deftheory}[9][Not Applicable] +{ +\newpage +\noindent \rule{\textwidth}{0.5mm} + +\paragraph{RefName: } \textbf{#2} \phantomsection +\label{#2} + +\paragraph{Label:} #3 + +\noindent \rule{\textwidth}{0.5mm} + +\paragraph{Equation:} + +#4 + +\paragraph{Description:} + +#5 + +\paragraph{Notes:} + +#6 + +\paragraph{Source:} + +#7 + +\paragraph{Ref.\ By:} + +#8 + +\paragraph{Preconditions for \hyperref[#2]{#2}:} +\label{#2_precond} + +#9 + +\paragraph{Derivation for \hyperref[#2]{#2}:} +\label{#2_deriv} + +#1 + +\noindent \rule{\textwidth}{0.5mm} + +} + +\begin{document} + +\title{Software Requirements Specification for \progname: subtitle describing software} +\author{Author Name(s)} +\date{\today} + +\maketitle + +~\newpage + +\pagenumbering{roman} + +\tableofcontents + +~\newpage + +\section*{Revision History} + +\begin{tabularx}{\textwidth}{p{3cm}p{2cm}X} +\toprule {\bf Date} & {\bf Version} & {\bf Notes}\\ +\midrule +Date 1 & 1.0 & Notes\\ +Date 2 & 1.1 & Notes\\ +\bottomrule +\end{tabularx} + +~\newpage + +\section{Reference Material} + +This section records information for easy reference. + +\subsection{Table of Units} + +Throughout this document SI (Syst\`{e}me International d'Unit\'{e}s) is employed +as the unit system. In addition to the basic units, several derived units are +used as described below. For each unit, the symbol is given followed by a +description of the unit and the SI name. +~\newline + +\renewcommand{\arraystretch}{1.2} +%\begin{table}[ht] + \noindent \begin{tabular}{l l l} + \toprule + \textbf{symbol} & \textbf{unit} & \textbf{SI}\\ + \midrule + \si{\metre} & length & metre\\ + \si{\kilogram} & mass & kilogram\\ + \si{\second} & time & second\\ + \si{\celsius} & temperature & centigrade\\ + \si{\joule} & energy & joule\\ + \si{\watt} & power & watt (W = \si{\joule\per\second})\\ + \bottomrule + \end{tabular} + % \caption{Provide a caption} +%\end{table} + +\plt{Only include the units that your SRS actually uses.} + +\plt{Derived units, like newtons, pascal, etc, should show their derivation + (the units they are derived from) if their constituent units are in the + table of units (that is, if the units they are derived from are used in the + document). For instance, the derivation of pascals as + $\si{\pascal}=\si{\newton\per\square\meter}$ is shown if newtons and m are + both in the table. The derivations of newtons would not be shown if kg and + s are not both in the table.} + +\plt{The symbol for units named after people use capital letters, but the name + of the unit itself uses lower case. For instance, pascals use the symbol Pa, + watts use the symbol W, teslas use the symbol T, newtons use the symbol N, + etc. The one exception to this is degree Celsius. Details on writing metric + units can be found on the + \href{https://www.nist.gov/pml/weights-and-measures/writing-metric-units} + {NIST} web-page.} + +\subsection{Table of Symbols} + +The table that follows summarizes the symbols used in this document along with +their units. The choice of symbols was made to be consistent with the heat +transfer literature and with existing documentation for solar water heating +systems. The symbols are listed in alphabetical order. + +\renewcommand{\arraystretch}{1.2} +%\noindent \begin{tabularx}{1.0\textwidth}{l l X} +\noindent \begin{longtable*}{l l p{12cm}} \toprule +\textbf{symbol} & \textbf{unit} & \textbf{description}\\ +\midrule +$A_C$ & \si[per-mode=symbol] {\square\metre} & coil surface area +\\ +$A_\text{in}$ & \si[per-mode=symbol] {\square\metre} & surface area over +which heat is transferred in +\\ +\bottomrule +\end{longtable*} +\plt{Use your problems actual symbols. The si package is a good idea to use for + units.} + +\subsection{Abbreviations and Acronyms} + +\renewcommand{\arraystretch}{1.2} +\begin{tabular}{l l} + \toprule + \textbf{symbol} & \textbf{description}\\ + \midrule + A & Assumption\\ + DD & Data Definition\\ + GD & General Definition\\ + GS & Goal Statement\\ + IM & Instance Model\\ + LC & Likely Change\\ + PS & Physical System Description\\ + R & Requirement\\ + SRS & Software Requirements Specification\\ + \progname{} & \plt{put an expanded version of your program name here (as appropriate)}\\ + T & Theoretical Model\\ + \bottomrule +\end{tabular}\\ + +\plt{Add any other abbreviations or acronyms that you add} + +\subsection{Mathematical Notation} + +\plt{This section is optional, but should be included for projects that make use + of notation to convey mathematical information. For instance, if typographic + conventions (like bold face font) are used to distinguish matrices, this + should be stated here. If symbols are used to show mathematical operations, + these should be summarized here. In some cases the easiest way to summarize + the notation is to point to a text or other source that explains the + notation.} + +\plt{This section was added to the template because some students use very + domain specific notation. This notation will not be readily understandable to + people outside of your domain. It should be explained.} + +\newpage + +\pagenumbering{arabic} + +\plt{This SRS template is based on \citet{SmithAndLai2005, SmithEtAl2007}. It + will get you started. You should not modify the section headings, without + first discussing the change with the course instructor. Modification means + you are not following the template, which loses some of the advantage of a + template, especially standardization. Although the bits shown below do not + include type information, you may need to add this information for your + problem. If you are unsure, please can ask the instructor.} + +\plt{Feel free to change the appearance of the report by modifying the LaTeX + commands.} + +\plt{This template document assumes that a single program is being documented. + If you are documenting a family of models, you should start with a commonality + analysis. A separate template is provided for this. For program + families you should look at \cite{Smith2006, SmithMcCutchanAndCarette2017}. + Single family member programs are often programs based on a single physical + model. General purpose tools are usually documented as a family. Families of + physical models also come up.} + +\plt{The SRS is not generally written, or read, sequentially. The SRS is a + reference document. It is generally read in an ad hoc order, as the need + arises. For writing an SRS, and for reading one for the first time, the + suggested order of sections is: +\begin{itemize} +\item Goal Statement +\item Instance Models +\item Requirements +\item Introduction +\item Specific System Description +\end{itemize} +} + +\plt{Guiding principles for the SRS document: +\begin{itemize} +\item Do not repeat the same information at the same abstraction level. If + information is repeated, the repetition should be at a different abstraction + level. For instance, there will be overlap between the scope section and the + assumptions, but the scope section will not go into as much detail as the + assumptions section. +\end{itemize} +} + +\plt{The template description comments should be disabled before submitting this + document for grading.} + +\plt{You can borrow any wording from the text given in the template. It is part + of the template, and not considered an instance of academic integrity. Of + course, you need to cite the source of the template.} + +\plt{When the documentation is done, it should be possible to trace back to the + source of every piece of information. Some information will come from + external sources, like terminology. Other information will be derived, like + General Definitions.} + +\plt{An SRS document should have the following qualities: unambiguous, + consistent, complete, validatable, abstract and traceable.} + +\plt{The overall goal of the SRS is that someone that meets the Characteristics + of the Intended Reader (Section~\ref{sec_IntendedReader}) can learn, + understand and verify the captured domain knowledge. They should not have to + trust the authors of the SRS on any statements. They should be able to + independently verify/derive every statement made.} + +\section{Introduction} + +\plt{The introduction section is written to introduce the problem. It starts + general and focuses on the problem domain. The general advice is to start with +a paragraph or two that describes the problem, followed by a ``roadmap'' +paragraph. A roadmap orients the reader by telling them what sub-sections to +expect in the Introduction section.} + +\subsection{Purpose of Document} + +\plt{This section summarizes the purpose of the SRS document. It does not focus + on the problem itself. The problem is described in the ``Problem + Description'' section (Section~\ref{Sec_pd}). The purpose is for the document + in the context of the project itself, not in the context of this course. + Although the ``purpose'' of the document is to get a grade, you should not + mention this. Instead, ``fake it'' as if this is a real project. The purpose + section will be similar between projects. The purpose of the document is the + purpose of the SRS, including communication, planning for the design stage, + etc.} + +\subsection{Scope of Requirements} + +\plt{Modelling the real world requires simplification. The full complexity of + the actual physics, chemistry, biology is too much for existing models, and + for existing computational solution techniques. Rather than say what is in + the scope, it is usually easier to say what is not. You can think of it as + the scope is initially everything, and then it is constrained to create the + actual scope. For instance, the problem can be restricted to 2 dimensions, or + it can ignore the effect of temperature (or pressure) on the material + properties, etc.} + +\plt{The scope section is related to the assumptions section + (Section~\ref{sec_assumpt}). However, the scope and the assumptions are not + at the same level of abstraction. The scope is at a high level. The focus is + on the ``big picture'' assumptions. The assumptions section lists, and + describes, all of the assumptions.} + +\subsection{Characteristics of Intended Reader} \label{sec_IntendedReader} + +\plt{This section summarizes the skills and knowledge of the readers of the + SRS. It does NOT have the same purpose as the ``User Characteristics'' + section (Section~\ref{SecUserCharacteristics}). The intended readers are the + people that will read, review and maintain the SRS. They are the people that + will conceivably design the software that is intended to meet the + requirements. The user, on the other hand, is the person that uses the + software that is built. They may never read this SRS document. Of course, + the same person could be a ``user'' and an ``intended reader.''} + +\plt{The intended reader characteristics should be written as unambiguously and + as specifically as possible. Rather than say, the user should have an + understanding of physics, say what kind of physics and at what level. For + instance, is high school physics adequate, or should the reader have had a + graduate course on advanced quantum mechanics?} + +\subsection{Organization of Document} + +\plt{This section provides a roadmap of the SRS document. It will help the + reader orient themselves. It will provide direction that will help them + select which sections they want to read, and in what order. This section will + be similar between project.} + +\section{General System Description} + +This section provides general information about the system. It identifies the +interfaces between the system and its environment, describes the user +characteristics and lists the system constraints. \plt{This text can likely be + borrowed verbatim.} + +\plt{The purpose of this section is to provide general information about the + system so the specific requirements in the next section will be easier to + understand. The general system description section is designed to be + changeable independent of changes to the functional requirements documented in + the specific system description. The general system description provides a + context for a family of related models. The general description can stay the + same, while specific details are changed between family members.} + +\subsection{System Context} + +\plt{Your system context will include a figure that shows the abstract view of + the software. Often in a scientific context, the program can be viewed + abstractly following the design pattern of Inputs $\rightarrow$ Calculations + $\rightarrow$ Outputs. The system context will therefore often follow this + pattern. The user provides inputs, the system does the calculations, and then + provides the outputs to the user. The figure should not show all of the + inputs, just an abstract view of the main categories of inputs (like material + properties, geometry, etc.). Likewise, the outputs should be presented from + an abstract point of view. In some cases the diagram will show other external + entities, besides the user. For instance, when the software product is a + library, the user will be another software program, not an actual end user. + If there are system constraints that the software must work with external + libraries, these libraries can also be shown on the System Context diagram. + They should only be named with a specific library name if this is required by + the system constraint.} + +\begin{figure}[h!] +\begin{center} + \includegraphics[width=0.6\textwidth]{SystemContextFigure} +\caption{System Context} +\label{Fig_SystemContext} +\end{center} +\end{figure} + +\plt{For each of the entities in the system context diagram its responsibilities + should be listed. Whenever possible the system should check for data quality, + but for some cases the user will need to assume that responsibility. The list + of responsibilites should be about the inputs and outputs only, and they + should be abstract. Details should not be presented here. However, the + information should not be so abstract as to just say ``inputs'' and + ``outputs''. A summarizing phrase can be used to characterize the inputs. + For instance, saying ``material properties'' provides some information, but it + stays away from the detail of listing every required properties.} + +\begin{itemize} +\item User Responsibilities: +\begin{itemize} +\item +\end{itemize} +\item \progname{} Responsibilities: +\begin{itemize} +\item Detect data type mismatch, such as a string of characters instead of a + floating point number +\item +\end{itemize} +\end{itemize} + +\subsection{User Characteristics} \label{SecUserCharacteristics} + +\plt{This section summarizes the knowledge/skills expected of the user. + Measuring usability, which is often a required non-function requirement, + requires knowledge of a typical user. As mentioned above, the user is a + different role from the ``intended reader,'' as given in + Section~\ref{sec_IntendedReader}. As in Section~\ref{sec_IntendedReader}, the + user characteristics should be specific an unambiguous. For instance, ``The + end user of \progname{} should have an understanding of undergraduate Level 1 + Calculus and Physics.''} + +\subsection{System Constraints} + +\plt{System constraints differ from other type of requirements because they + limit the developers' options in the system design and they identify how the + eventual system must fit into the world. This is the only place in the SRS + where design decisions can be specified. That is, the quality requirement for + abstraction is relaxed here. However, system constraints should only be + included if they are truly required.} + +\section{Specific System Description} + +This section first presents the problem description, which gives a high-level +view of the problem to be solved. This is followed by the solution characteristics +specification, which presents the assumptions, theories, definitions and finally +the instance models. \plt{Add any project specific details that are relevant + for the section overview.} + +\subsection{Problem Description} \label{Sec_pd} + +\progname{} is intended to solve ... \plt{What problem does your program solve? +The description here should be in the problem space, not the solution space.} + +\subsubsection{Terminology and Definitions} + +\plt{This section is expressed in words, not with equations. It provide the + meaning of the different words and phrases used in the domain of the problem. +The terminology is used to introduce concepts from the world outside of the +mathematical model The terminology provides a real world connection to give the +mathematical model meaning.} + +This subsection provides a list of terms that are used in the subsequent +sections and their meaning, with the purpose of reducing ambiguity and making it +easier to correctly understand the requirements: + +\begin{itemize} + +\item + +\end{itemize} + +\subsubsection{Physical System Description} \label{sec_phySystDescrip} + +\plt{The purpose of this section is to clearly and unambiguously state the + physical system that is to be modelled. Effective problem solving requires a + logical and organized approach. The statements on the physical system to be + studied should cover enough information to solve the problem. The physical + description involves element identification, where elements are defined as + independent and separable items of the physical system. Some example elements + include acceleration due to gravity, the mass of an object, and the size and + shape of an object. Each element should be identified and labelled, with their + interesting properties specified clearly. The physical description can also + include interactions of the elements, such as the following: i) the + interactions between the elements and their physical environment; ii) the + interactions between elements; and, iii) the initial or boundary conditions.} + +The physical system of \progname{}, as shown in Figure~?, +includes the following elements: + +\begin{itemize} + +\item[PS1:] + +\item[PS2:] ... + +\end{itemize} + +\plt{A figure here makes sense for most SRS documents} + +% \begin{figure}[h!] +% \begin{center} +% %\rotatebox{-90} +% { +% \includegraphics[width=0.5\textwidth]{} +% } +% \caption{\label{