Skip to content

Quick start with simulations

Jump to bottom
Kartik Ayyer edited this page Mar 9, 2021 · 5 revisions

Welcome, impatient one! This quick start guide will take you through the following simulation workflow.

Install the package using the standard CMake pipeline

$ mkdir build && cd build
$ cmake ..
$ make install

By default, this will install the package to the following path ~/.local/dragonfly/. You can use the ccmake .. command to update the target path or the library locations if desired. At the end, add the binary directory to your path as suggested by the script.

$ export PATH=$PATH:<installation_path>

Spawn a reconstruction directory

Go to a directory where you have plenty of space and start a reconstruction session:

$ dragonfly_init

This makes the binaries needed for the package and links them into a new reconstruction directory named "recon_nnnn". For help on customizing this setup script (e.g. custom folder name or counter):

 $ dragonfly_init -h

Configure experiment

Go to your newly created recon directory

cd recon_nnnn

Change the experiment parameters in config.ini to your liking. Here are some things that you might like to change:

  • in_pdb_file: relative path to your own PDB file
  • scattering setup (detector distance, photon wavelength, etc)
    • [parameter] section:
      • detd (detector distance): millimeter
      • lambda (photon wavelength): Angstrom
      • detsize (linear size of detector): pixels in integer
      • pixsize: millimeter
      • stoprad (radius of beamstop): pixels in float
  • num_data: the number of diffraction patterns
  • fluence: the incident beam intensity in photons per micron squared
  • log_file: name of log file

When ready to start creating synthetic data, type:

./utils/sim_setup.py

Again, you can get help to customize this using the command:

./utils/sim_setup.py -h

Start your EMC reconstruction

You can use the convenience script run_emc.py that we provided to start the reconstruction: Typing

./utils/run_emc.py

will start the reconstruction with the default of 10 iterations.

You can continue to refine the last reconstruction by typing

./utils/run_emc.py -r

or if you wanted to increase the quaternion sampling by one,

./utils/run_emc.py -R

If you have enough processors to do an MPI reconstruction:

./utils/run_emc.py -m <number of MPI processes>

For more information, type:

./utils/run_emc.py -h

Or you can start a single process reconstruction in the recon directory with more control:

./emc -c [path to config file] -t [threads per process] <num_iterations>

where <necessary arguments> and [optional arguments]. The default number of threads per process is defined by the system parameter OMP_NUM_THREADS. The default config file is config.ini in the working directory. By default, the intermediate output of the reconstruction is stored in the recon directory's data subdirectory.

To spawn multiple MPI reconstructions from your recon directory:

mpirun -n <num_mpi_processes> ./emc  -c [path to config file] -t [threads per process] <num_iterations>

To continue an existing reconstruction, use the -r flag

Monitor the progress of your reconstruction

In the recon directory type:

./utils/autoplot.py

Checking the "Keep checking" box will automagically look for new reconstructed 3D volumes in the default data directories. By default, images from the reconstruction that are generated by this script are saved to the data/images subdirectory.

Checking your "answers"

So we tried doing this quick start ourselves from a fresh clone of this repository and reconstructed with 8 cores using the default config.ini file.

./dragonfly_init                        #spawn new reconstruction directory
cd recon_0001                           #changed into new reconstruction directory
./utils/sim_setup.py                    #Setup data stream simulator using default config.ini
./utils/run_emc.py -m 2 -t 4 -i 30 &    #Started an MPI+openMP reconstruction in the background
./utils/autoplot.py                     #Monitor the progress of the reconstruction

Here is a screenshot from autoplot.py to show how it went for us. The entire reconstruction took about 2.5 hours with 8 cores.

Ready for a larger reconstruction?

Look into the sample_configs folder. Replace your configuration files with these ones to try the reconstructions we did for the paper. Tell us how these went for you! Show us your most enormous reconstructions!

Additional hints

For a more verbose, and maybe informative, view of the underlying setup and reconstruction processes, look at the log files recon.log and EMC.log files respectively.

Clone this wiki locally