MOCASSIN 2.02 manual
Pure photoionisation benchmarks
The benchmark problems
Once you have downloaded, unpacked and compiled MOCASSIN successfully you can first of all try to run one or more of the available benchmark problems. These were designed at a series of workshops on photoionised plasma codes held at Meudon (France) and Lexington (USA). The latest version of these benchmarks are included in Pequignot et al. (2001) in Spectroscopic Challenges of Photoionised Plasmas, ASP Conference Series Vol 247; G. Ferland and D.W. Savina eds. Should these conference proceedings not be available to you, the same benchmarks are also reported in Ercolano et al., 2003, MNRAS, 340, 1136. Here you will also find some more general info about MOCASSIN. (There is also a link to this paper on the publications page).
Please note that the MOCASSIN results included in the Pequignot et al. (2001) were only from a very early version of the code. Best results are those listed in the Ercolano et al., 2003, MNRAS, 340, 1136 paper.
Input files for benchmarks
Copy the input file of the benchmark you wish to run (you should have found these in a subdirectory called benchmarks, also included in the tar ball)
into the mocassin.X.XX/input subdirectory and rename it input.in or link the input.in file to the benchmark file.
e.g. for the Meudon standard HII region (Tstar=40kK) (assume MOCASSIN is in ~/mocassin.X.XX/ ) type
cp ~/mocassin.X.XX/benchmarks/gas/HII40/meudonHII40.in ~/mocassin.X.XX/`input.in`put.in
or
ln -s ~/mocassin.X.XX/benchmarks/gas/HII40/meudonHII40.in ~/mocassin.X.XX/`input.in`
also copy the respective nebular abundance file into the same directory (no need to rename!). In the case of the Meudon standard HII region benchmark this will be abunHII40.in (you can check the name of the abundance file, which is given in the input.in file with keyword nebComposition)
cp ~/mocassin.X.XX/benchmarks/gas/HII40/abunHII40.in ~/mocassin.X.XX/input/abunHII40.in
Run a MOCASSIN pure photoionisation benchmark
The command you need to use to actually run MOCASSIN will depend on how your system is set up, and whether you are required to run your models through a queueing system, in which case you will probably need some sort of shell script to do that (ask your network administrator if unsure).
If you want to run MOCASSIN outside any queueing system then you can try one of the following commands and hope that one works, if not ask your network administrator about how to interactively run MPI programs on your system.
For the SUN:
mprun -np N ./mocassin
(where N=number of processors you wish to use)
for the IBM
./mocassin -procs N
(where N=number of processors you wish to use)
For the SGI, Beowulf and single Linux PCs using the standard MPI as above:
mpirun -np N ./mocassin
(where N=number of processors you wish to use)
Checking that everything is going OK
If the 'output' keyword is included in the input file, at the end of each iteration MOCASSIN will write out a number of output files in the output/ directory. Some of them are written out regardless of whether the output keyword is included, these are grid files that are needed by the mocassinWarm driver (should you decide to stop the simulation and re-start it from the same iteration); see the 'writeGrid' keyword to see how to control the output grid files. Also MOCASSIN will keep you updated on what he is doing by outputting stuff to the screen (if that annoys you, just pipe it to a file e.g. ./mocassin -procs N > log; and then you can check the log at any time you wish).
After each iteration it will tell you the percentage of grid-cells converged so far, as well as the number of 'dark cells' (i.e. those cells not reached by any of the photon packets) and also will provide a summary of eventual convergence problems generally this is the last bit of info written before the beginning of the new iteration, so, if you have decided to pipe the screen output into a file called log, then you can easily check the progress so far by typing tail -f log, or grep Summary log, or more simply, the convergence history is summarised in a file called output/summary.out.
For the benchmark cases you can start having an idea of whether MOCASSIN is working properly by waiting until it's about 60-70% converged and then checking the output/lineFlux.out file. A description of this file is given in output files. Also check the output/temperature.out and the output/ionratio.out files (also described in output files).
Completing the benchmark runs
The benchmark input files included are set up to run a simulation of 13×13×13 grid cells (this is sufficient to reproduce the benchmark results; see Ercolano et al., 2003) and a given starting number of energy packets (e.g. this can be set by the keyword nPhotons 100000); one iteration of 100000 packet should run in a few minutes on most systems.
The benchmarks input files make use of the autoPackets option, which automatically increases the number of energy packets to be used as soon as a convergence plateau is reached.
This could also be done manually, by excluding the autoPackets option from the input file and starting off with about 1000000 packets. However 1000000 photons are not enough to reach full convergence in this case and you will have to stop the simulation when the percentage convergence reaches 30-40%, then edit the grid3.out file changing 1000000 to 3000000, and restart the simulation using the previously compiled mocassinWarm driver, e.g.
mprun -np N ./mocassinWarm
This will basically tell MOCASSIN to increase the number of energy packets to be used in the simulation from 1000000 to 3000000. It will, of course, now take longer to complete each iteration, but the convergence percentage should increase quite quickly. You can stop the simulation when you reach convergence > 90%. For simplicity, until you familiarise yourself with the program, it is advised that you keep the autoPackets option as set in the input files, in which case it will not be needed to manually stop and restart the simulation.
Comparing with the benchmark tables
The description of the output files is given in output files. The output files contain all the info (and much more) you need to compare your simulation with the benchmark tables. Remember that MOCASSIN employs a statistical method, so do NOT expect to see exactly the same figures as those quote in the benchmark paper as some of the differences will be due to the statistical error and also to the convergence level/limit employed. Furthermore some of the atomic data has been updated since the publication of the paper.