Help on writing sofware: general guidelines, in particular separation of computation and visualization

Question

Although I already did some work in the intersection of theory and simulation I'm still very new to this field and I need some guidance. If anybody can give some recommendations for introductory literature about computational science and how to plan scientific software I appreciate it. Below are some more concrete questions.

During the work for my thesis I did and still do numerical simulations of a quantum-mechanical system and I encountered the following problem. Basically, the three important steps of these simulations are: solving a system of ODEs, computation of physical observables using this solution, and plotting of the observables. My first question is, when it comes to writing the software what is the best practice for the separation of these steps? Should a program do all of these steps or is it better to divide the steps between different scripts and save the data in between?

My concern is that my current approach is chaotic and not efficient. My first scripts did all the steps in one go. When the ODE solver took a lot of time for the solution, I changed the script to save the raw solution for later purposes. My current approach is to calculate the solution and the quantities of interest in one go, and save the data to text files. The plotting is done by separate scripts. Currently it takes me about 0.5-3h to revise a figure and imho this is very slow.

Since there are a lot of parameters, there is a lot of room for choosing which variables are fixed, which are varied, what the x-axis is, and so forth. This led me to write a lot of small scripts each tailored to a specific region of the parameter space and a specific choice of observables which subsequently led to a complicated and fragmented folder and file structure. Is this a good style or should one choose to write programs that cover all possible cases and observables?

Answer 1

My first question is, when it comes to writing the software what is the best practice for the separation of these steps? Should a program do all of these steps or is it better to divide the steps between different scripts and save the data in between?

How you separate the steps depends on many things, like how long it takes to solve the ODEs, what software environment you are using, etc.

In general, keep things as simple as they can possibly be while still being productive. If you're writing your ODE solver code in MATLAB or Python, it's fairly easy to keep the visualization step in the same script, as long as the ODE solve isn't unacceptably slow. In a compiled language, it's usually easier write to output and then use a third-party plotting tool.

My concern is that my current approach is chaotic and not efficient. My first scripts did all the steps in one go. When the ODE solver took a lot of time for the solution, I changed the script to save the raw solution for later purposes. My current approach is to calculate the solution and the quantities of interest in one go, and save the data to text files. The plotting is done by separate scripts. Currently it takes me about 0.5-3h to revise a figure and imho this is very slow.

This iterative approach is exactly what you should be doing. As a first hack, doing all the steps in one go makes sense. It's like a first draft of a document; putting everything down in code helps you see what needs to be done, and what can be improved. Sometimes, some design work can be done in advance, but in general, whatever is written will need to be revised.

Since there are a lot of parameters, there is a lot of room for choosing which variables are fixed, which are varied, what the x-axis is, and so forth. This led me to write a lot of small scripts each tailored to a specific region of the parameter space and a specific choice of observables which subsequently led to a complicated and fragmented folder and file structure. Is this a good style or should one choose to write programs that cover all possible cases and observables?

I'd say, in general, pick tools that work for you. If you find that a lot of the scripts you're writing are cut-and-paste, that's probably a sign you can make your scripts more general.

Do you know some literature about scicomp or designing scientific software?

Software Carpentry maintains a list of suggested materials. I've read some of the suggested works (for instance, Code Complete) and found them to be helpful. Some sources have more of a general software engineering focus, and are useful because they impart the decades of experience software engineers have in best practices. A more narrowly focused book that might be of use is Writing Scientific Software: A Guide to Good Style.

(Disclaimer: I have taught two Software Carpentry workshops.)

Answer 2

Should a program do all of these steps or is it better to divide the steps between different scripts and save the data in between?

Keep them separate.

The reason to consider integrating a simulation (solving ODEs) and analysis is to avoid writing data to disk and then reloading it for the analyses. If your ODE is hard to solve (more than O(N)) and you change your analysis with any regularity, then loading an old result from disk will be a lot faster than regenerating a new one.

Is this a good style or should one choose to write programs that cover all possible cases and observables?

How broad or narrow your tools should be is very situation specific. In particular, it depends on:

• What you're trying to do
• What 3rd party programs/libraries you are using (gnuplot, matplotlib, etc)
• How good of a programmer you are

You should try to strike a balance between investing time in building tools that make your science easier and doing the actual science. If you're more comfortable writing a relatively large number of specialized tools, there's nothing wrong with that. On the other hand, if you can spend 5 minutes to generalize a plotting script in a way that eliminates 10 others and saves you time, you should do that.