diff options
Diffstat (limited to 'software')
| -rw-r--r-- | software/chapter.tex | 233 |
1 files changed, 158 insertions, 75 deletions
diff --git a/software/chapter.tex b/software/chapter.tex index 0b880e4..d4a1517 100644 --- a/software/chapter.tex +++ b/software/chapter.tex @@ -101,9 +101,10 @@ enabling infrastructure for science and engineering research'' [CITE https://www \section{Challenges in scientific software development} % ========================================
Software development ``by-and-for'' scientists poses unique challenges. %
+In this section, I attempt to summarize the literature about these challenges, with a focus on
+those challenges that I have found most relevant. %
-\subsection{Extensibility} % ---------------------------------------------------------------------
-
+\textbf{Extensibility.} % TODO: cite
Many traditional software development paradigms demand an upfront articulation of goals and
requirements. %
This allows the developers to carefully design their software, even before a single line of code is
@@ -120,23 +121,13 @@ of researchers and a contracted team of software engineers. % \end{dquote}
-\subsection{Testing} % ---------------------------------------------------------------------------
-
PrabhuPrakash2011a---lots of good stuff under ``Scientists do not rigorously test their programs''
-\subsection{Lifetime} % --------------------------------------------------------------------------
-
+\textbf{Lifetime.}
PrabhuPrakash2011a--- subsection ``long history of software development''
-
Challenges with portability, and updating to ``modern standards''.
-\subsection{Optimization} % ----------------------------------------------------------------------
-
-PrabhuPrakash2011a: ``scientists do not optimize for the common case'', ``scientists are unaware of
-parallelization paradigms''
-
-\subsection{Maintenance} % -----------------------------------------------------------------------
-
+\textbf{Maintenance}
Scientific software, especially software maintained by graduate students, tends to be very hard to
maintain. %
This problem is compounded by the long lifetime of such software, and the poorly defined
@@ -146,50 +137,115 @@ written by generation upon generation of student. % Worse, software is sometimes abandoned or left untouched to become a crucial but arcane component
of a scientific research project. %
+\textbf{Optimization}
+PrabhuPrakash2011a: ``scientists do not optimize for the common case'', ``scientists are unaware of
+parallelization paradigms''
+
\section{Good-enough practices} % ================================================================
In their [...] perspective, ``Good enough practices in scientific computing'', (from which this
section gets its name) [WILSON ET AL] describe a set of techniques that, in their words, ``every
researcher can and should consider adopting''. %
-
-\subsection{Write clearly and document often} % --------------------------------------------------
-
-Let the computer do the work...
-
-Write programs for people, not computers. %
-
-\subsection{Do not reinvent} % -------------------------------------------------------------------
-
-Don't repeat yourself, or others (we built on top of scipy, hdf5).
-
-\subsection{Avoid premature optimization} % ------------------------------------------------------
-
-Write first, optimize later.
-
-\subsection{Data formats} % ----------------------------------------------------------------------
-
-% HDF5
-
-% SELF-DESCRIBING DATA
-
-% OBJECT ORIENTED PROGRAMMING
-
-\subsection{Collaboration and version control} % -------------------------------------------------
-
-Plan for mistakes / use testing.
-
-Document document docuement.
-
-Collaborate.
-Code review...
-Issues...
-Make incremental changes...
-
-% SOURCE CONTROL AND VERSIONING
-
-\subsection{Licensing and distribution} % --------------------------------------------------------
-
-% LICENSING AND DISTRIBUTION
+In this section, I attempt to very quickly summarize my personal perspective on what makes good
+software development good---with citations to literature that supports each idea. %
+These practices are not, generally, ``extra work''. %
+In fact, many of them save massive amounts of time and effort in the long \emph{and} short run,
+when properly applied. %
+
+\textbf{Do not reinvent.} \cite{WilsonGreg2017a} %
+Before you sit down and implement a piece of software, stop! %
+First you should try hard to find a library that already has what you need. %
+You'll often surprise yourself with what you can find. %
+Search the package repository for your language, such as PyPI [CITE], MATLAB File Exchange [CITE]
+or CRAN [CITE]. %
+Even if there is not a full solution to your problem out there, there is almost certainly a
+solution to some part of it. %
+Much better to have a dependency than a custom implementation. %
+Make your dependencies explicit, in machine readable ways where possible. %
+
+\textbf{Do not duplicate.} \cite{WilsonGreg2017a} %
+If you do need to write some software, make sure that you do not duplicate code within your own
+work. %
+Instead of writing the same 10 lines of code again and again with small tweaks, write a function
+that accepts a set of arguments. %
+If your software package grows to contain multiple files, make those files modular. %
+As a general rule, once you have two classes you need multiple files. %
+
+\textbf{Choose good data formats.} \cite{WilsonGreg2017a} %
+Choose a non-proprietary format if at all possible---remember: you yourself might not have access
+to the proprietary software in 10 years. %
+Choose plain text if you can. %
+Consider conforming to specifications, such as Tidy Data. [CITE] %
+If you must, use open binary formats such as HDF5. %
+Put as much metadata as you can into the file. %
+Any piece of metadata that can automatically be added by the computer is essentially free---you
+might as well do it. %
+Make sure that it is clear what each piece of data means. %
+For tabular data, use headers. %
+Don't forget units. %
+
+\textbf{Use version control.} %
+Version control systems allow programmers to save a software package such that they can always
+return to that save point. %
+All of the files in the package are saved together. %
+Modern version control systems allow programmers to see exactly what has changed between each save
+point, and since the last save point. %
+This is indispensable when trying to diagnose software problems. %
+In order to use version control as effectively as possible, try to save the package after every
+change (feature addition, bugfix, etc). %
+Typically version control is coupled with uploading to a remote server, for example using git with
+GitHub [CITE] or git.chem.wisc.edu [CITE], but version control need not be synonymous with
+uploading and distribution. %
+Tools like git have a lot of fantastic features beyond simply saving [CITE], but those are beyond the
+scope of these ``good enough'' recommendations. %
+Also consider defining a version for the software package as a whole. %
+Use semantic versioning [CITE], unless there is a strong reason not to. %
+If the language you are using has a convention for representing the version programmatically, such
+as a \python{__version__} attribute in Python, comply with that convention. %
+
+\textbf{Test.} \cite{WilsonGreg2017a} %
+As the old saying goes, ``if it's not tested, it's broken''. %
+If you rely on a piece of functionality in your software, consider writing a test that defines that
+functionality. %
+In this way, as you make changes you can run your tests to ensure that those changes do not
+accidentally break important functionality. %
+Testing sounds difficult, but it's really just about writing simple functions that use your
+software to do something, and then raise an exception if the result is not correct. %
+If you add tests when you add features or fix bugs, you'll quickly find that you have a lot of
+tests that do a good job of defining the expected behavior of your software. %
+Software engineers tend to be dogmatic about testing, but don't worry too much about test coverage
+unless your project becomes very important. %
+Distribute test datasets, when appropriate. %
+Remember, your tests can serve double duty as simple minimal examples. %
+
+\textbf{Collaborate and share.} \cite{WilsonGreg2017a} %
+If you are part of a team, consider sharing software and collaborating to create it. %
+Try using practices like code review and issue tracking, but don't feel obligated to use them if it
+doesn't make sense for your project. %
+When working as part of a team, making incremental changes and using version control become even
+more important. %
+Earlier we mentioned ``do not reinvent''. %
+The other side of that coin is ``if you make something, consider sharing it''. %
+Put your software on an open platform, like GitHub, and mint a DOI. %
+Cite your software, and ask other people who are using your software to do the same. %
+Choose a license early, and choose permissive and commercially compatible unless you 1. know what
+you are doing and 2. plan to enforce. %
+% TODO: cite 'publish your code it is good enough'
+
+\textbf{Write human readable code, and document it well.} \cite{WilsonGreg2017a} %
+Let the computer do the work, but write the program to be read by a human. %
+Give classes, functions, attributes and variables meaningful names. %
+Don't be afraid to be verbose, most programming environments have tab completion so long names are
+not all that hard to type. %
+Try to follow the recommended style for your language, but don't obsess about it. %
+
+\textbf{Avoid premature optimization.} \cite{WilsonGreg2017a}
+Don't get pulled into the trap of trying to make things perfect the first time. %
+Software design is typically a very iterative process, and for good reason. %
+Write first, and if it works, consider optimization. %
+If you do need to make your software faster, use profiling tools like cProfile [CITE] and SnakeVis
+[CITE] to empirically determine what operations are taking the longest, rather than trying to guess
+or use intuition. %
\section{Object oriented programming} % ----------------------------------------------------------
@@ -223,9 +279,9 @@ class Person(): if food == self.favorite_food:
return 'yum! my favorite'
elif food == self.hated_food:
- return 'gross---no thank you'
+ return 'gross---no thank you'''''''''
else:
- return 'meh'
+ return 'meh''
\end{codefragment}
Now I can make some instances of that class, and access their attributes and methods. %
\begin{codefragment}{python}
@@ -266,8 +322,8 @@ I recommend The Quarks of Object-Oriented Development, by \textcite{ArmstrongDeb \section{Hierarchical data format} % -------------------------------------------------------------
-One of the particularly important challenges in MR-CMDS is data storage. %
-MR-CMDS datasets are multi-dimensional, and the particular dimensions are different from experiment
+One of the particularly important challenges in CMDS is data storage. %
+CMDS datasets are multi-dimensional, and the particular dimensions are different from experiment
to experiment. %
Historically, the Wright Group has stored data as ``flattened'' arrays in plain text, where each
column corresponds to one of the scannable hardwares or one of the sensors in the experiment. %
@@ -278,27 +334,54 @@ increasingly large and higher-dimensional data. % Heirarchial data files are an alternative strategy that scales much better with large and
high-dimensional data. %
-
-Originally, CDF \cite{TreinshLloydA1987a}. %
-Support ``random access to data, so that efficient access of small portions or large data files
-would be possible''. %
-
-Then, NetCDF \cite{RewRuss1990a}.
-More portability. %
-Named dimensions. %
-Metadata. %
-``Hyperslab''
-
-FITS used by astronomy community, with a focus on backwards compatibility. %
-\cite{WellsDC1981a}
+These are binary files that store the array directly, not in a flattened way. %
+They can contain multiple arrays, with different data types, in the same file under a well-defined
+organizational system. %
+They support arbitrary metadata, integrated into the same hierarchy as the arrays, so making them
+self-describing is trivial. %
+While in general plain text is prefered for its simplicity, these file-types are simply superior
+for storing CMDS data. %
+
+To this author's best knowledge, the Common Data Format (CDF) was the first general purpose
+self-describing multidimensional array data format. \cite{TreinshLloydA1987a} %
+The engineers at the National Space Science Data Center (a division of NASA) created the CDF. %
+Using this construct, ``scientific softwares at NSSDC ... do not need specific knowledge of the
+data whith which they are working. This permits users of such systems to apply the same functions
+to different sets of data.''
+These are exactly the capabilities that CMDS requires. %
+
+A second-order challenge in CMDS data storage is the size of the arrays. %
+While by no-means ``big data'', CMDS data is often awkwardly large: large enough to fill up the
+memory of an average modern laptop or desktop computer. %
+CDF also has a unique solution to this problem: use a block structure to allow access to parts of
+the array without reading the entire data into memory. %
+
+Slightly later, NetCDF was introduced \cite{RewRuss1990a}. %
+Very similar to CDF, NetCDF focused on enhancments to portability. %
+Certain metadata conventions were also introduced, including named dimensions. %
+NetCDF remains popular in the aerospace and
+
+The Flexable Image Transform System (FITS) is a similar format with a focus on visualization and
+backwards compatibility. \cite{WellsDC1981a} %
% CITE https://fits.gsfc.nasa.gov/
% CONSIDER CITING https://fits.gsfc.nasa.gov/rfc4047.txt
+Fits is still popular in the astronomy community. %
-I have chosen to build off of HDF5. %
+Today, these hierarchical data formats have gathered under the umbrella of the HDF5 format, built
+and maintained by the HDF Group. [CITE] %
+This format has all of the advantages of FITS, CDF, and NetCDF. %
+It can support arbitrary datatypes and is optimized to quickly process large and complex
+datasets. %
+In Python, HDF5 is supported primarily through the h5py package. [CITE] %
\section{Scientific Python} % --------------------------------------------------------------------
-Numpy, SciPy
-
-% TODO: add MillmanKJarrod2011a (Python for Scientists and Engineers)
-% TODO: add vanderWaltStefan2011a (The NumPy Array: A Structure for Efficient Numerical Computation)
\ No newline at end of file +SciPy is a collection of ``open-source software for mathematics, science, and egnineering.''
+\cite{MillmanKHarrod2011a} %
+SciPy was an absolute essential component of this dissertation and the work it describes. %
+There are packages under the SciPy umbrella. %
+NumPy is a very powerful and fast package for working with multidimensional arrays.
+\cite{vanderWaltStefan2011a} %
+The SciPy library contains a vast number of scientific computing tools, including many mathematical
+operations that this work depends on. [CITE] %
+Matplotlib is a beautiful visualization package for 1, 2, and 3D plotting. [CITE] %
|