This book is about software design. We use “design” here in the sense that it applies to machines, electrical circuits, chemical plants, and buildings. At least two differences between designing scientific software and designing these other systems seem apparent:

1. The extent to which one communicates a system's structure by representing schematically its component parts and their interrelationships,

2. The extent to which such schematics can be analyzed to evaluate suitability and prevent failures.

Schematic representations greatly simplify communications between developers. Analyses of these schematics can potentially settle long-standing debates about which systems will wear well over time as user requirements evolve and usage varies.

This book does not chiefly concern high-performance computing. While most current discussions of scientific programming focus on scalable performance, we unabashedly set out along the nearly orthogonal axis of scalable design. We analyze how the structure of a package determines its developmental complexity according to such measures as bug search times and documentation information content. We also present arguments for why these issues impact solution cost and time more than does scalable performance.

We firmly believe that science is not a horse race. The greatest scientific impact does not necessarily go to the swiftest code. Groundbreaking results often occur at the intersection of multiple disciplines, where the basic science is so poorly understood that important insights can be gleaned from creative simulations of modest size.

Abstract Data Type Calculus

A desire for code reuse motivated most of Chapter 2. Using encapsulation and information hiding, we wrapped legacy, structured programs in an object-oriented superstructure without exposing the legacy interfaces. We used aggregation and composition to incorporate the resulting classes into components inside new classes. We also employed inheritance to erect class hierarchies. Finally, we employed dynamic polymorphism to enable child instances to respond to the type-bound procedure invocations written for their parents.

Much of the code in Chapters 1–2 proved amenable to reuse in modeling heat conduction, but few of the object-oriented abstractions presented would find any use for nonthermal calculations. Even to the extent the heat equation models other phenomena, such as Fickian diffusion, calling a procedure named heat_for() to solve the diffusion equation would obfuscate its purpose. This problem could be addressed with window dressing – creating a diffusion-oriented interface that delegates all procedure invocations to the conductor class. Nonetheless, neither the original conductor class nor its diffusion counterpart would likely prove useful in any simulation that solves a governing equation that is not formally equivalent to the heat equation. This begs the question: “When reusing codes, what classes might we best construct from them?”

Most developers would agree with the benefits of breaking a large problem into smaller problems, but choosing those smaller problems poses a quandary without a unique solution.

Nomenclature

Chapter 1 introduced the main pillars of object-orientation: encapsulation, information hiding, polymorphism, and inheritance. The current chapter provides more detailed definitions and demonstrations of these concepts in Fortran 2003 along with a complexity analysis. As noted in the preface, we primarily target three audiences: Fortran 95 programmers unfamiliar with OOP, Fortran 95 programmers who emulate OOP, and C++ programmers familiar with OOP. In reading this chapter, the first audience will learn the basic OOP concepts in a familiar syntax. The second audience will find that many of the emulation techniques that have been suggested in the literature can be converted quite easily to employ the intrinsic OOP constructs of Fortran 2003. The third audience will benefit from the exposure to OOP in a language other than their native tongue. All will hopefully benefit from the complexity analysis at the end of the chapter.

We hope that using the newest features of Fortran gives this book lasting value. Operating at the bleeding edge, however, presents some short-term limitations. As of January 2011, only two compilers implemented the full Fortran 2003 standard:

• The IBM XL Fortran compiler,

• The Cray Compiler Environment.

However, it appears that the Numerical Algorithms Group (NAG), Gnu Fortran (gfortran), and Intel compilers are advancing rapidly enough that they are likely to have the features required to compile the code in this book by the time of publication (Chivers and Sleightholme 2010).

The Problem

This chapter introduces the GoF strategy pattern along with a Fortran-specific, enabling pattern: surrogate. In scientific programming, one finds context for a strategy when the choice of numerical algorithms must evolve dynamically. Multiphysics modeling, for example, typically implies multi-numerics modeling. As the physics changes, so must the numerical methods.

A problem arises when the software does not separate its expression of the physics from its expression of the discrete algorithms. In the Lorenz system, for example, equation (4.5) expresses the physics, whereas equation (4.6) expresses the discretization. Consider a concrete ADT that solves the same equations as the abstractions presented in Section 6.2 and extends the integrand ADT but requires a new time integration algorithm. The extended type must overload the integrate name. This would be a simple task when changing one algorithm in one particular ADT. However, when numerous algorithms exist, one faces the dilemma of either putting all possible algorithms in the parent type or leaving to extended types the task of each implementing their own algorithms. Section 7.3 explains the adverse impact the first option has on code maintainability. The second option could lead to redundant (and possibly inconsistent) implementations.

The Lorenz equation solver described in Chapter 6 uses explicit Euler time advancement. That solver updates the solution vector at each time step without explicitly storing a corresponding time coordinate.

The Problem

The patterns discussed in Chapters 6–7 adhere closely to the GoF philosophy of designing to an interface rather than an implementation. That maxim inspired the use of abstract classes in defining an abstract calculus, a strategy, and a surrogate. The puppeteer definition in Chapter 8 represented the one setting in which client code manipulated concrete implementations directly – although an exercise at the end of that chapter describes a way to liberate the puppeteer from the tyranny of implementations also.

Independent of whether the classes comprising the pattern demonstrations are abstract, the client codes (main programs in the cases considered) exploit knowledge of the concrete type of each object constructed in Chapters 6–8. Although we were able to write polymorphic procedures such as integrate in Figures 6.2(b) and 6.3(b)–(c), in each case, the actual arguments passed to these procedures were references to concrete objects the client constructed. One can write even more flexible code by freeing clients of even this minimal knowledge of concrete types. This poses the dilemma of where object construction happens. Put simply, how does one construct an object without directly invoking its constructor? Or from another angle, how does an object come to be if the client knows only the interface defined by its abstract parent, but that parent's abstract nature precludes definition of a constructor? By definition, no instance of an abstract type can be instantiated.

Why Be Formal?

Whereas Parts I and II focused on canonical examples, Part III marches toward complete applications, resplendent with runtime considerations. The current chapter addresses code and compiler correctness. Chapter 11 discusses language interoperability. Chapter 12 addresses scalability and weaves elements of the entire book into a vision for multiphysics framework design.

Formal methods form an important branch of software engineering that has apparently been applied to the design of only a small percentage of scientific simulation programs (Bientinesi and van de Geijn 2005; van Engelen and Cats 1997). Two pillars of formalization are specification and verification – that is, specifying mathematically what a program must do and verifying the correctness of an algorithm with respect to the specification. The numerical aspects of scientific programming are already formal. The mathematical equations one wishes to solve in a given scientific simulation provide a formal specification, whereas a proof of numerical convergence provides a formal verification. Hence, formal methods developers often cite a motivation of seeking correctness standards for non-scientific codes as rigorous as those for scientific codes (Oliveria 1997). This ignores, however, the nonnumerical aspects of scientific programs that could benefit from greater rigor. One such aspect is memory management. The current chapter specifies formal constraints on memory allocations in the Fortran implementation of the Burgers equation solver from Chapter 9.

Introduction

The past several decades have witnessed impressive successes in the ability of scientists and engineers to accurately simulate physical phenomena on computers. In engineering, it would now be unimaginable to design complex devices such as aircraft engines or skyscrapers without detailed numerical modeling playing an integral role. In science, computation is now recognized as a third mode of inquiry, complementing theory and experiment. As the steady march of progress in individual spheres of interest continues, the focus naturally turns toward leveraging efforts in previously separate domains to advance one's own domain or in combining old disciplines into new ones. Such work falls under the umbrella of multiphysics modeling.

Overcoming the physical, mathematical, and computational challenges of multiphysics modeling comprises one of the central challenges of 21st-century science and engineering. In one of its three major findings, the National Science Foundation Blue Ribbon Panel on Simulation-Based Engineering Science (SBES) cited “open problems associated with multiscale and multi-physics modeling” among a group of “formidable challenges [that] stand in the way of progress in SBES research.” As the juxtaposition of “multiphysics” and “multiscale” in the panel's report implies, multi-physics problems often involve dynamics across a broad range of lengths and times.

At the level of the physics and mathematics, integrating the disparate dynamics of multiple fields poses significant challenges in simulation accuracy, consistency, and stability.

The purpose of a software naming convention is to help the people who read and write the code understand the program. Understanding the code makes it easier to use, write, or modify correctly. The goal in naming is to use names that are easy to recognize and associate with their meaning and role.

The basic content idea is to use words and character sequences that help connect a name with the entity that it represents. It is a great idea to use names that are intuitive, but developers have surprisingly divergent ideas on which names are intuitive. A more realistic objective is to use names that help the reader understand the code.

The basic visual style idea is to use different visual styles for different identifier types. This makes it easier to recognize the various elements of the language. Clearly, some consistency and differentiation is important. There is a balance in differentiation because having a large number of styles makes for too much to remember. In any case, only a few variations of naming style are available in MATLAB, so the language elements have to be grouped into a smaller number of styles. There is controversy is over how best to do it.

Establishing a naming convention for a group of developers is important, but the process can become ridiculously contentious. There is no naming convention that will please everyone.

The organization of code and data files in directories can have a significant impact on ease of use. Separate project-specific and general-purpose m-files to make them easier to use and to integrate with the MATLAB product.

Toolboxes

Organize General-Purpose m-Files in Toolboxes

Develop general-purpose program libraries or toolboxes to increase productivity. A library is particularly helpful for related functions, such as statistics or time series analysis, that are useful in more than one application domain.

Write your toolboxes for sharing. Standards are higher for public toolboxes that you share with others than for personal toolboxes for your own use. Improve the quality of your code by having others use and criticize it. A public toolbox should be usable by nonexperts and customizable and extensible by experts.

Put Test Files in a Separate Directory

In general, do not release test files in a production code toolbox directory. Putting the test files in their own directory makes the release separation easier. Using separate directories helps avoid any dependence of the production code on the test code.

Consider Writing Demo Files

Demo files provide the user with quick examples of the capabilities and uses of the functions in a toolbox. Demos often use graphical user interfaces (GUIs) or are graphics based, and they allow the user to see results without extensive programming.

The syntax of a programming language tells you what code it is possible to write – what machines will understand. Style tells you what you ought to write – what humans reading the code will understand. Code written with a consistent, readable style is robust, maintainable, and contains fewer bugs. Code written with no regard to style contains more bugs, and it may simply be thrown away and replaced rather than supported and extended.

Attending to style is particularly important when developing software as a team. Consistent style facilitates communication because it enables team members to read and understand each other's work more easily. The value of consistent programming style increases dramatically with the number of people working with the code and with the amount of code in the project.

Two style guides are classics: Strunk and White's The Elements of Style and Kernighan and Plauger's The Elements of Programming Style. These small books work because they are simple: a list of rules, each containing an explanation and examples of correct, and sometimes incorrect, use. This book follows the same pattern.

Some of the advice in this book may seem obvious to you, particularly if you have been writing and reading code for a long time. You may disagree with some of the specific suggestions about formatting, naming, or usage.

MATLAB now has the capability for serious projects, not just casual prototyping. As projects get bigger and team size grows, explicit and consistent development practices become more important. MATLAB is used with a range of recognized development practices from traditional to more recent agile approaches. This chapter presents techniques and strategies that are generally applicable to most of these practices. It also includes some items that are agile-specific.

Traditional approaches tend to have formal documented specifications and detailed design up front, with code documentation and testing near the end of the process. Agile approaches promote writing code and tests early, refactoring often to produce design, and placing less emphasis on formal documentation.

The goal of any development is software that works, usually including properties such as stability, correctness, extensibility, and maintainability. All serious development approaches include elements such as design, documentation, and test. The project deliverables are code (main and test) and documentation (of software, process, and evaluation).

Most software projects are constrained by developer time. Use practices that make the best use of your limited time and are effective in your work environment. Despite schedule pressures, make time to learn about important elements of the language, features of the development environment, and best practices.

In 2002, I wrote a brief set of observations and thoughts on MATLAB® style for my coworkers. Other programmers found it useful, so I posted the “MATLAB Programming Style Guidelines” document on my website datatool.com. It has since been downloaded more than 40,000 times.

This book responds to that encouraging interest and incorporates what I have learned in the meantime. It joins a well-received series of style books on other languages, including The Elements of Java Style, The Elements of C++ Style, and The Elements of C# Style.

Much of the advice in this book may be familiar. This is deliberate because many of the programming principles described are valid across programming languages. However, the content has been extensively reworked and expanded here to address the unique characteristics of the MATLAB language and development environment environment, as well as the priorities and practices of MATLAB programmers.

Audience

This is a practical manual for the serious user who wants to become more productive. It provides guidance on clear and effective programming, particularly for those who develop with or for others.

This book is written for new MATLAB programmers who want to develop good habits, as well as for experienced MATLAB programmers who want to get better and to understand why others use different style conventions.

This book is not intended to teach you the MATLAB language, but rather it focuses on how MATLAB code can be written in order to maximize its effectiveness.

Graphic designers have long known that the appropriate use of space around and within text can enhance the reading experience. Use layout, white space, and visual organization to clarify relationships and avoid straining the reader's short-term memory. When you modify your code, preserve layout and spacing to make sure that its format is correct. Code that is easy to scan and read is more likely to be correct.

Layout

The purpose of layout is to help the reader understand the code. It should accurately and consistently represent the logical structure of the code. Indentation is particularly helpful for revealing code structure and patterns to provide context for individual statements.

Keep Content Within the First Eighty Columns

Avoid writing code in long lines. Short lines are easier to read than long ones. In general, the readability of text decreases as column width increases. The recommended eighty-column width is a common dimension for editors, terminal emulators, printers, and debuggers.

Readability improves if unintentional line breaks and horizontal scrolling are avoided when passing a file between programmers. Limiting lines to eighty columns also makes side-by-side viewing in two windows easier.

Split Long Code Lines at Graceful Points

A long line is one that exceeds the suggested eighty-column limit. If you have two or more statements on one line, then write each on a line of its own.