ComDetective.HowToRun

Usage
=====
1. To run ComDetective with default configuration (sampling period: 500K, bulletin board size: 127, number of watchpoints: 4, and name of output folder "<timestamp>_timestamped_results"):

ComDetectiverun <./your_executable> your_args

2. To run ComDetective with custom configuration (user-chosen sampling period, bulletin board size, number of watchpoints, minimum size of data objects to be detected, and name of output folder):

ComDetectiverun --period <sampling rate> --bulletin-board-size <bulletin board size> --debug-register-size <number of debug registers> --object-size-threshold <minimum number of bytes of detectable objects> --output <name of output folder> <./your_executable> your_args

or

ComDetectiverun -p <sampling rate> -b <bulletin board size> -d <number of debug registers> -t <minimum number of bytes of detectable objects> -o <name of output folder> <./your_executable> args_for_executable

3. To monitor a program that has multiple processes (e.g. an MPI program):

mpirun -n <process count> ComDetectiverun <./your_executable> your_args

4. To run ComDetective with ADAMANT:

ComDetectiverun --enable-object-level <./your_executable> your_args

Results
=====
Communication matrices are dumped to the output folder. 

Each application level matrix file is named as follow: <executable name>-<pid of the process>-<matrix type>_matrix.csv, 
while data object level matrix file is named as follow: <executable name>-<pid of the process>-<object id>-<matrix type>_matrix_rank_<object rank>.csv. 

<matrix type> can be "as" for any communication among threads, "ts" for true sharing among threads, 
"fs" for false sharing among threads, "as_core" for any communication among cores, 
"fs_core" for false sharing among cores, or "ts_core" for true sharing among cores. 
<object id> is associated with the corresponding data object's name in file <executable name>-<pid of the process>-<matrix type>_object_ranking.txt. 
In this txt file, all data objects are ranked with respect to the counts of communication whose type is indicated by the <matrix type>. 
Total counts of communications are printed in the log file named <executable name>-*.log within the output folder.