Skip to content

Commit cb5fa57

Browse files
cosdencosden
authored
Merge pull request #1 from adubey64/main
Content for software design lesson.
2 parents d2a842d + b3882ea commit cb5fa57

32 files changed

Lines changed: 714 additions & 9 deletions

‎AUTHORS‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
FIXME: list authors' names and email addresses.
1+
Anshu Dubey: adubey@anl.gov
2+
Abhishek Biswas

‎_episodes/01-introduction.md‎

Lines changed: 64 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,72 @@ title: "Introduction"
33
teaching: 0
44
exercises: 0
55
questions:
6-
- "Key question (FIXME)"
6+
- "How to design research software"
77
objectives:
8-
- "First learning objective. (FIXME)"
8+
- "To understand design principles and to be able to apply them to
9+
research software"
910
keypoints:
10-
- "First key point. Brief Answer to questions. (FIXME)"
11+
- "Investing in design is critical for reliable, maintainable and extensible software"
1112
---
12-
FIXME
1313

14-
{% include links.md %}
14+
# Why Design
15+
16+
* Investing some thought in design of software makes it possible to maintain\, reuse and extend it
17+
* Even if some research software (RS) begins its life as a one\-off use case\, it often gets reused
18+
* Without proper design it is likely to accrete features haphazardly and become a monstrosity
19+
* Acquires a lot of technical debt in the process
20+
21+
![](img/techdebt.png)
22+
23+
definition from
24+
https://enterprisersproject\.com/article/2020/6/technical\-debt\-explained\-plain\-english
25+
26+
In many ways technical debt works like monetary debt. If you don't pay
27+
it off it compounds. The more technical debt you accrue, the more
28+
unmaintainable your software becomes.
29+
30+
Many projects have had this happen to them, and most of them end up
31+
with a hard reset and having to start over again
32+
33+
# In this module we will cover general design principles and those that are tailored for scientific software
34+
35+
Several books are available on the topic of software design
36+
37+
![](img/books.png)
38+
39+
…\. and many more
40+
41+
So why do we have this module in the bootcamp ?
42+
43+
# Motivation and Objectives
44+
45+
The first and foremost reason is the same as for taking any course
46+
that has good textbooks.
47+
48+
A practitioner with experience can make the ideas more
49+
accessible. Instructor can perceive when attendees are not following
50+
and therefore can try to present the same idea with a different
51+
approach and/or perspective. Practitioners also bring their own
52+
intuition and experience to the discussion which tend to enrich the
53+
information being imparted in a classroom setting.
54+
55+
There are other reasons why software design needs to be included in a
56+
research software engineering training. Most of software engineering
57+
research and literature targets enterprise software that is in
58+
production. Literature is sparse even for exploratory enterprise
59+
software. One reason is that understanding the requirements and
60+
devising strategies for design of exploratory software is
61+
difficult. For industry it may not even be a worthwhile expenditure
62+
because before being released and utilized for production all software
63+
likely goes through rigorous quality control.
64+
65+
Research software in academic setting is different because it is also
66+
the production software. Often exploration and production go hand in
67+
hand, which means that quality control is an ongoing
68+
process. Therefore it is important to understand methodologies for
69+
designing research software that meets research goals while
70+
maintaining its reliability without becoming an excessive burden on
71+
the developers and the users.
72+
73+
![](img/emph.png)
1574

‎_episodes/02-design-principles-general.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: "General Design Principles"
3+
teaching: 0
4+
exercises: 0
5+
questions:
6+
- "What are most commonly used design principles?"
7+
objectives:
8+
- "To introduce common design principles"
9+
keypoints:
10+
- " "
11+
---
12+
13+
# General Design Principles
14+
15+
## Found on the web
16+
17+
* Encapsulate what varies
18+
* Favor composition over inheritance
19+
* Program to interfaces not implementations
20+
* Loose coupling – interacting components should have minimal knowledge about each other
21+
* SOLID
22+
* Single responsibility
23+
* Class/method/function should do only one thing
24+
* Open/closed
25+
* Open for extension\, close for modification
26+
* Liskov substitution
27+
* Implementations of an interface should give same result
28+
* Interface segregation
29+
* Client should not have to use methods it does not need
30+
* Dependency inversion
31+
* High level modules should not depend on low level modules\, only
32+
on abstractions
33+
34+
These are just some of the links that have more details on these
35+
design principles.
36+
37+
https://www.freecodecamp.org/news/solid-design-principles-in-software-development/
38+
https://www.bmc.com/blogs/solid-design-principles/
39+
https://bootcamp.uxdesign.cc/software-design-principles-every-developers-should-know-23d24735518e
40+
41+
42+
# Designing Software – High Level Phases
43+
44+
![](img/elements.png)
45+
46+
As shown in the figure above, software design has three phases:
47+
requirements gathering, decomposition, and understanding connectivity
48+
with that decomposition. These phases come one after another, though
49+
one can iterate over them as needed.
50+
51+
# Requirements Gathering
52+
53+
In the requirement gathering phase the developers gather information
54+
about what is needed from the software. As an extremely simple example
55+
is writing an integer sorter. At first glance it appears that only
56+
requirement is to read in a bunch of integers, sort them in specified
57+
order, and output the sorted numbers. However a few other requirements
58+
may dictate actual implementation. For example:
59+
60+
* How large is the dataset -- will simplest O(N<sup>2</sup>) method
61+
suffice or does one need O(NlogN) method
62+
* Is the dataset large enough that a parallel sorting algorithm needed
63+
* Is it a stand-alone code or is it going to be used in another code
64+
(in other words does it handle I/O or needs to have arguments)
65+
* If it needs I/O then what is format of input and output files
66+
* If it has arguments what should the interface look like
67+
68+
It may seem like an obvious approach to take, but if you think a
69+
little about what is involved you will realize that failing to get
70+
these specifications will likely accrue some technical debt which will
71+
have to be paid later through modifications in the code.
72+
73+
# Decomposition
74+
75+
Once requirements are known one can proceed to design components of
76+
the software. In the sorting example the simplest case of small
77+
dataset to sorted through a function call will have just one
78+
components. If it is a stand-alone piece of software then it may be
79+
divided into three components, one for I/O, one for sorting, and the
80+
driver that invokes the other two components. If it is
81+
a stand-alone parallel sorter then it may either incorporate
82+
parallelization in the driver, or may add another component to handle
83+
the parallelization.
84+
85+
# Connectivity
86+
87+
This phase of design is devoted to understanding the interdependencies
88+
between components. In the stand-alone parallel sorting example with a
89+
separate parallelization component we infer the following
90+
connectivity:
91+
92+
* Driver knows all other components and invokes them as needed
93+
* I/O is called by the Driver and no other component. If parallel I/O
94+
is being used then it needs to have an interface with the
95+
parallelization component
96+
* Sorter is called by the driver, but it also needs access to the
97+
parallelization component
98+
* Parallelization component is called by the driver and the sorter. It
99+
may also be called by I/O if we are using parallel I/O
100+
101+
One immediate concern that you may have is that this approach is not
102+
compatible with agile methodology. It is not because complete design of a
103+
complex software may need several iterations over the three phases. It
104+
need not all happen before development begins. It can happen anytime
105+
during the development cycle, and in all probability some or all of
106+
the phases may need to be reconsidered as understanding grows.
107+
108+
In the next section we will work through a real life application design.
109+
110+

‎_episodes/03-apply-general-principles.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: "Design Principles Application"
3+
teaching: 0
4+
exercises: 0
5+
questions:
6+
- "What are some ways of using these principles"
7+
objectives:
8+
- "Work through a simple example"
9+
keypoints:
10+
- "Understanding process of software design with a simple application"
11+
---
12+
13+
# Example 1 – Problem Description
14+
15+
We have a house with exterior walls made of single material of
16+
thickness Lx\. The wall has some water pipes shown in the picture\.
17+
The inside temperature is kept at 70 degrees\. But outside temperature is expected to be \-40 degrees for 15\.5 hours\.
18+
19+
The question we are trying to answer is -- will the pipes freeze before the storm is over
20+
21+
![](img/example1.png)
22+
23+
24+
25+
In general, heat [conduction](https://en.wikipedia.org/wiki/Thermal_conduction) is governed
26+
by the partial differential (PDE)...
27+
28+
| | |
29+
|:---:|:---:|
30+
|![](http://latex.codecogs.com/gif.latex?%5Cfrac%7B%5Cpartial%20u%7D%7B%5Cpartial%20t%7D%20-%20%5Cnabla%20%5Ccdot%20%5Calpha%20%5Cnabla%20u%20%3D%200)|(1)|
31+
32+
where _u_ is the temperature at spatial positions, _x_, and times, _t_,
33+
![](http://latex.codecogs.com/gif.latex?%5Calpha) is the _thermal diffusivity_
34+
of the homogeneous material through which heat is flowing. This partial differential equation (PDE)
35+
is known as the _Diffusion Equation_ and also the [_Heat Equation_](https://en.wikipedia.org/wiki/Heat_equation).
36+
37+
# Simplifying Assumptions
38+
39+
To make the problem tractable for this lesson, we make some simplifying assumptions...
40+
41+
1. The thermal diffusivity, ![](http://latex.codecogs.com/gif.latex?%5Calpha),
42+
is constant for all _space_ and _time_.
43+
1. The only heat _source_ is from the initial and/or boundary conditions.
44+
1. We will deal only with the _one dimensional_ problem in _Cartesian
45+
coordinates_.
46+
47+
In this case, the PDE our application needs to solve simplifies to...
48+
49+
| | |
50+
|:---:|:---:|
51+
|![](http://latex.codecogs.com/gif.latex?%5Cfrac%7B%5Cpartial%20u%7D%7B%5Cpartial%20t%7D%20%3D%20%5Calpha%20%5Cfrac%7B%5Cpartial%5E2%20u%7D%7B%5Cpartial%20x%5E2%7D)|(2)|
52+
53+
The code in the repository has three different numerical algorithms
54+
55+
* [Foward Time Centered Space (FTCS)](https://en.wikipedia.org/wiki/FTCS_scheme), an
56+
[explicit](https://en.wikipedia.org/wiki/Explicit_and_implicit_methods) method
57+
* [Crank-Nicholson](https://en.wikipedia.org/wiki/Crank–Nicolson_method),
58+
an [implicit](https://en.wikipedia.org/wiki/Explicit_and_implicit_methods) method
59+
* [Upwind-15](https://en.wikipedia.org/wiki/Upwind_scheme), another
60+
[explicit](https://en.wikipedia.org/wiki/Explicit_and_implicit_methods) method
61+
with higher spatial order than FTCS.
62+
63+
We will work through one of them -- FTCS
64+
65+
66+
# Requirement gathering
67+
68+
* To solve heat equation we need:
69+
* a discretization scheme
70+
* a driver for running and book\-keeping
71+
* an integration method to evolve solution
72+
* Initial conditions
73+
* Boundary conditions
74+
* To make sure that we are doing it correctly we need:
75+
* Ways to inspect the results
76+
* Ways of verification
77+
78+
79+
# Decomposition
80+
81+
* This is a small design space
82+
* Several requirements can directly map to components – in this instance functions
83+
* Driver
84+
* Initialization – data containers
85+
* Mesh initialization – applying initial conditions
86+
* Integrator
87+
* I/O
88+
* Boundary conditions
89+
* Comparison utility
90+
91+
* Binning components
92+
* Components that will work for any application of heat equation
93+
* Driver
94+
* Initialization – data containers
95+
* I/O
96+
* Comparison utility
97+
* Components that are application specific
98+
* Mesh initialization – applying initial conditions
99+
* Integrator
100+
* Boundary conditions
101+
102+
# Connectivity
103+
104+
![](img/conn1.png)
105+
106+
# Connectivity – Alternative Possibility
107+
108+
![](img/conn2.png)
109+
110+

0 commit comments

Comments
 (0)