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:
If you wish to add any instructions for the user, please add these as comments in the
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
plot.py in the
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
5) Modify the
Please add the necessary tests so that the
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 ../maketest.in 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 clean-usr: 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
We need to add three variables inside the
<!--Planet2D example--> <variable name="Planet2DSetupFile" language="python"> Planet2DSetupFile=file("./Planet2D/INFO/setup_report.txt","r").read() </variable> <variable name="Planet2DErrorFile" language="python"> Planet2DErrorFile=file("./Planet2D/errors.txt0","r").read() </variable> <variable name="Planet2DOutputFile" language="python"> Planet2DOutputFile=file("./Planet2D/output.txt0","r").read() </variable>
And we need to add three tests inside the
<!--Planet2D example--> <test name="nothing in error file" language="python"> import re print "Planet2D test" assert(not(re.search(" ",Planet2DErrorFile,re.M))) </test> <test name="model finished set-up correctly" language="python"> import re assert(re.search("SETTINGS FINISHED, STOPPING.",Planet2DSetupFile,re.M)) </test> <test name="model terminated correctly" language="python"> import re assert(re.search("END OF SIMULATION",Planet2DOutputFile,re.M)) </test>
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.