1 - Introduction to Design Documents
It can feel rather disconnected and pointless to talk about coding concepts in the abstract. So, to start us off we'll be using a simulation of an Ising model as an example. I've chosen this model for a few reasons: It is relativity simple, well studied, has rich and interesting behavior, and there are some very nice extensions that can be made to the base model (History of the Lenz-Ising Model: https://doi.org/10.1103/RevModPhys.39.883).
That the Ising Model has simple yet powerful extensions makes it an ideal model to showcase Code Reuse, a topic we’ll cover in a few weeks. Often in research there is a pattern where you start with a basic computational model, run some experiments with it, and then make a couple changes — to the parameters, the initial conditions, the measurements or model itself — and run a new experiment. If you’re in the habit of editing a single long script to manage your computational model, you already know this can quickly become quite cumbersome and it can be hard to switch between different experiments. I aim to show that with a little planning and the implementation of object-oriented code, your code base can become much more manageable. Planning things out with a Design Document makes this process much easier.
Over the coming weeks we will plan out, code, and test a simulation with this Ising Model case study. We will also be adding some extensions to the base model that have been planned for which helps show the payoff for the planning we put in and the class structure we set up. Then we will add some extensions we didn't plan for to show how to adapt the code base to changing needs.
Now that we've got a model to investigate, it’s time to do the planning stage of this project. We'll do that by filling out a Design Document. A design document serves two purposes, it is a tool to help us plan that creates a road map for the code that tells other people (or reminds us 2 weeks later) what we set out to do. A good design document for a physics simulation should capture:
The physical phenomenon we want to study
How we plan to model it mathematically
How we plan to solve the model on the computer
What initial conditions we want to start the system in
What quantities we want to measure
How those quantities will be measured on the computer
What experiments we want to run and how we will run them
How the code will be structured to achieve this
How we plan to test the code
It may be hard to convince yourself to take the time to fill out a form and plan everything out when you just want to dive into coding. Consider that the planning and decisions you make while writing a Design Document are choices that we will have to make at some point in the project. Thinking about them ahead of time lets us prepare for them and consider them as a whole, thus saving time down the road. This is the big picture that will help guide us as we code. Writing all the discretized math as it will be carried out in the code saves us from having to program and do math at the same time — something which, in my experience, leads to mistakes in both. This is our first step in project management: we've created a list of everything that needs to go into V1.0 of the code, and now we have an end point (or at least a check point). Finally, having this document saves time when this code needs to be read — and code is read more often than it is written.
As Eisenhower said, "plans are useless but planning is indispensable." The Design Document should be a living document. As you actually write the simulation you may realize you were wrong about how you wanted to do things. You may want to add in more features (experiments) later. You should continually update the design document to reflect this. Even if it doesn’t happen at the beginning, this is valuable planning time that will ensure that the document still functions as a roadmap to the code. This means that when you first write the Design Document you should just focus on getting your thoughts on paper. It is easy to iterate but you have to have something to start with.
I’ve attached a design document I have developed for physics simulations. If you feel like your project should have another section, add it. If a section is irrelevant for you, remove it. The purpose of this is to make a roadmap of a problem from concept to code, but each problem is different and the problem itself will inform structure of the document.
Next week we’ll go through the first 6 Sections of this document in depth, continuing with the Ising model case study. Then we’ll talk about different options for interfaces before getting into the larger topics of how to design a class structure and a test plan.
Link to Tex File: Design Document Template
