EMC implementation

The EMC reconstruction program takes primarily three inputs:

• photons written in a sparse data format (see this page);
• a list of detector pixel positions and status (this page);
• a configuration file that describes where to look for input and return output (see this page).

This page describes how to start the EMC reconstruction once these inputs are prepared.

---

emc

We start by saying that you'll probably forget which flags you ought to pass to this function. If this happens to you, simply run the executable without any options/flags to get the help text:

./emc

Format: ./emc [-c config_fname] [-t num_threads] [-r] num_iter
Default: -c config.ini -t 12
Missing <num_iter>

There are two basic ways to run this executable: start a new reconstruction or continue an existing one. We explore these two options in turn. Before we proceed, note that since the convenience utility [run_emc.py](Convenience utilities#run_emc.py) basically uses the emc executable, the options here are also available to run_emc.py.

Starting a new reconstruction

First, ensure that you have the following:

• config.ini properly filled out pointing to the right files (details here),
• photons.emc in the correct format (data format listed here, also shown in figure below),
• and detector.dat correctly labeled (data format listed here).

To start a reconstruction you'll have to decide how many MPI processes, openMP threads, and number of iterations to perform. Note that the number of iterations is a required command line input. Once decided, you can run:

mpirun -n <num_mpi_jobs> ./emc -t <num_threads> num_iter    

Alternatively, if you only have a shared memory system and don't want to use MPI, then you can do the following instead:

./emc -t <num_threads> num_iter     

Continuing a previously completed reconstruction

Let's say you would like to continue a reconstruction but now changing the config.ini parameters, rotation group samples and/or photon data. Ensure that these preparation are complete then continue from a previous reconstruction using this command:

mpirun -n <num_mpi_jobs> ./emc -r -t <num_threads> num_iter    

where the -r flag makes the executable look for the last entry in the previous EMC.log file and continue reconstructions from last 3D diffraction volume reconstructed. The EMC.log file will also be appended rather than overwritten.

Beware! Do the following only if you screw up in the prescribed manner! If you accidentally left out the -r flag, the reconstruction will start from the beginning again. However, the emc executable will not delete previous reconstructions stored in data/output. So if you abort this mis-started reconstruction quickly enough, you can still restart reconstructions by adding the following line to your config.ini file in the emc section:

start_model_file = <relative path of last reconstruction> 

Diagnostics

In our manuscript (citation needed) we describe how to diagnose the progress of a reconstruction. Go download the paper and read about it!

But to get started you can try using our GUI utility described here.

The danger zone

You are, of course, free to dig into the source code and experiment as you wish. You'll likely find some cobwebs and easter eggs. These are not officially supported.