Adding an example

When substantial new functionality is added to iSALE it should be accompanied by an example problem that demonstrates the use of the new feature. Here we will work through how to add a new example that demonstrates the use of central gravity in iSALE2D. This is example Planet2D.

1) Design your example problem

Keep in mind that other people, including iSALE novices, will be running our example. We should therefore keep the example quite simple and if possible, it should run in a few hours at most. This can generally be achieved simply by reducing the resolution. However, we also want to demonstrate the full functionality of our new feature, so we should not make the problem so simple that it is not very insightful.

In the Planet2D example, we will create a problem of a large impact on the moon---approximately of the relevant scale for the South Pole-Aitkin (SPA) impact. We will make the problem quite low resolution (10CPPR), and only set the model to run until the transient crater is formed, but we will include all the important layers of the Moon (crust, mantle and core) and will include strength.

2) Add your example

Assuming you are in the iSALE root directory, change into the example subdirectory and create a directory for your example files:

cd iSALE/example
mkdir Planet2D

Now add the input files for your example to the directory. Note that your input files must have the standard names: asteroid.inp and material.inp.
If you wish to add any instructions for the user, please add these as comments in the asteroid.inp file.

3) Add any files for post-processing

If this is a 2D example, you can add an iSALEPlot input file in the example directory. This must be called iSALEPlot.inp. Alternatively, if you want to include multiple iSALEPlot input files or some other plotting scripts, you can create a subdirectory Plotting/ and include any number of files in here. Note that Plotting/ should have no subdirectories.

In the Planet2D example, we have added iSALEPlot.inp to the Planet2D directory and we have put another iSALEPlot input file iDenTmp.inp and a simple plotting scipt in the Planet2D/Plotting/ directory.

4) Add any files for benchmarking

If you want to include any files for users to benchmark their data against (this might be experimental data or data from the last stable release of iSALE), these can be added in a subdirectory called: BenchmarkData/. Note that BenchmarkData/ should have no subdirectories and the file size for benchmarking data should be kept to a minimum. If you wish to provide images for comparison, please add these to the example's wiki page, rather than the repository.

In the Planet2D example, we have added some text files with profiles through the moon from a benchmark simulation (using iSALE-Chicxulub), e.g., density.txt, to the Planet2D/BenchmarkData/ directory.

5) Modify the options_check_2D/3D test

Please add the necessary tests so that the options_check_2D (or options_check_3D) test will verify that the input files for your problem are correct and up-to-date. Assuming you are in the iSALE root directory:

cd iSALE/tests/options_check_2D
nano Makefile

Add to the makefile instructions for how to run your new example(s) and for how to cleanup. In the Makefile below we have added: $(ISALE2D) -i $(EXAMPLEDIR)/Planet2D/asteroid.inp -M $(EXAMPLEDIR)/Planet2D/material.inp -C, which is the instruction for running iSALE in "check input only" mode. We have also added Planet2D to the list of directories to remove when cleaning up.

include ../

run: prerun
        $(ISALE2D) -i $(EXAMPLEDIR)/demo2D/asteroid.inp -M $(EXAMPLEDIR)/demo2D/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/Chicxulub/asteroid.inp -M $(EXAMPLEDIR)/Chicxulub/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/Collision2D/asteroid.inp -M $(EXAMPLEDIR)/Collision2D/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/planar_eulerian_2D/asteroid.inp -M $(EXAMPLEDIR)/planar_eulerian_2D/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/planar_eulerian_2D/asteroid.inp -f Planar-800mps --OBJVEL -8.D2 -M $(EXAMPLEDIR)/planar_eulerian_2D/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/planar_lagrangian_2D/asteroid.inp -M $(EXAMPLEDIR)/planar_lagrangian_2D/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/aluminum_1100_2D/asteroid.inp -M $(EXAMPLEDIR)/aluminum_1100_2D/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/aluminum_6061_2D/asteroid.inp -M $(EXAMPLEDIR)/aluminum_6061_2D/material.inp -C
        $(ISALE2D) -i $(EXAMPLEDIR)/Planet2D/asteroid.inp -M $(EXAMPLEDIR)/Planet2D/material.inp -C

        rm -rf Chicxulub JNCK-Al1100 JNCK-Al6061 Planar-Lagrangian Planar-600mps Planar-800mps Collision2D demo2D Planet2D

Please use as the modelname the same name as the example.

We also need to add variables and tests to the options_check_2D.xml file:

nano options_check_2D.xml

We need to add three variables inside the <variables>...</variables> tags:

    <!--Planet2D example-->
    <variable name="Planet2DSetupFile" language="python">
    <variable name="Planet2DErrorFile" language="python">
    <variable name="Planet2DOutputFile" language="python">

And we need to add three tests inside the <pass_tests>...</pass_tests> tags:

    <!--Planet2D example-->
    <test name="nothing in error file" language="python">
import re
print "Planet2D test" 
assert(not(" ",Planet2DErrorFile,re.M)))
    <test name="model finished set-up correctly" language="python">
import re
assert("SETTINGS FINISHED, STOPPING.",Planet2DSetupFile,re.M))
    <test name="model terminated correctly" language="python">
import re  
assert("END OF SIMULATION",Planet2DOutputFile,re.M))

6) Ensure that the test passes and the example installs

Before we commit your example to the repository, we should make sure we run:

make tests
make install

from the iSALE root directory and verify that the options_check_2D test passes (and checks your new example options file) and that your example is installed correctly into <prefix>/share/examples. In particular, if we have included any post-processing files (in Plotting/) and/or benchmark data (in BenchmarkData/) we should check that these files are all installed correctly.

7) Make sure your problem runs

Run your simulation from the install directory to verify that the problem runs in a reasonable time. Also work through the post-processing steps to make sure they work.

8) Commit your example to the repository

If we are adding our example files to the repository we will need to svn add all new files. This is most straightforwardly done from the iSALE/example/ directory using:

svn add Planet2D

as this will add all files, subdirectories, etc., in the example directory. However, before you do this, make sure that only those files that you wish to commit are in the example directory.

We also need to commit our changes to the options_check_2D example, so before committing, we go back to the iSALE root directory (or the iSALE/ subdirectory) and do:

svn update
svn checkin -m"Adding new example (Planet2D) to demonstrate PLANET model with central-gravity in iSALE2D.  Options check test is updated." 

Note the first command will make sure that our working copy is up-to-date and any potential conflicts are resolved before we commit the new example.

9) Add a wiki page

Please add a wiki page here that describes how to run your example problem and perform any post-processing. You should add a general description of the problem and provide illustrations for comparison. The Planet2D example is described here.