Garden with Insight v1.0 Help: Translation of EPIC to Pascal

To create the models for Garden with Insight we wanted to work with an existing model that was well accepted in the scientific community, was well validated, and had some data we could provide to our users. We decided on the EPIC model created by the USDA Agricultural Research Service as the best candidate. EPIC was created to simulate hundreds of years of soil erosion in one relatively large field (around one hectare) with one crop species at a time. We wanted to adapt the model for use in a small garden situation with multiple soil patches and multiple plants of several species, with attention to small- scale fruiting, flowering, and harvesting. So we set out to translate EPIC's public-domain FORTRAN code to Pascal (actually, we started out in C++, but later converted to Pascal).

The science in EPIC and similar models is beyond doubt excellent, and we are grateful to have had the chance to work with such a solid and thorough model as EPIC. However, from a programmer's point of view, much of the source code that has been developed by the agricultural science community is extremely difficult to understand, maintain, and enhance. For example, few variable names in EPIC are longer than two or three characters; therefore the user is required to memorize long lists of cryptic names in order to understand even small pieces of code. It took one of us over a year of full-time work to translate the EPIC FORTRAN code to Pascal, notwithstanding the fact that we were not trained as soil scientists. We think this problem hampers the agricultural science community's ability to communicate about scientific models and to work together to enhance existing models.

In order to understand the EPIC source code, we expanded variable names to around 20-40 characters and added a unit suffix to each variable name showing the units in which the variable is represented. The unit suffixes have proved to be a great help in understanding the code because one can see how the variables in equations work out in terms of units, and because the constants that convert between units make sense instead of being "magic" constants. Compare the same function in the EPIC FORTRAN code and the translated Pascal code.

We also typed the entire text of a publication by J.R. Williams, the main author of EPIC (Williams 1994), into the source code as comments, so that the explanation of the model could be read along with the source code. We added our own notes on the model to the comments, as well as notes on our changes to the model. In fact, most of this model section of the help system was taken directly from our source code.