faithsim.rst
################################################
Dag Generator for Doing Faithfulness Comparisons
################################################
============
Introduction
============
This page describes how to use the faithfulness dag generator within
PyCBC.
==========================
How to generate a workflow
==========================
------------------------------------
Creating a configuration (.ini) file
------------------------------------
All the choices when setting up a faithsim are contained
in a single configuration file.
Below is an example.
.. literalinclude:: ../examples/faith/faithsim_simple.ini
There are four sections that must be present [inspinj], [executables], [workflow], and [faithsim-XXX].
#. inspinj
This section sets the paramaters of all of the injection waveforms.
The arguments in the configuration file are fed directly to the
lalapps_inspinj program to create an injection file.
The same arguments are available, and the same restrictions apply.
The number of injections can be set by using the gps start and end time
options along with the time step.
Note, however, that the waveform name is required but does not
determine the actual approximants that will be compared. That is set in the [banksim]
section.
#. executables
This section lists the location of the pycbc_faithsim script. Make note
that the script is copied to the executables folder
and that is the version that will be used.
#. workflow
This section has options that configure the workflow.
The required options are 'log-path' and 'templates-per-job'. The
'log-path' specifies the directory to store
condor log files. The 'templates-per-job' section determines
how many faithfulness calculations each job will do. The
injection file is split into smaller portions to match this
restriction. This option
is directly proportional to the running time of
each job.
Faith simulations running on LDG clusters must include the
'accounting-group' option in the workflow section. The value
must be choosen according to the
`Accounting information web page <https://ldas-gridmon.ligo.caltech.edu/ldg_accounting/>`_.
#. faithsim-XXX
Multiple sections with a a name of the form 'faithsim-USER_STRING' can exist.
The generator will create jobs that correspond to each of these sections
and each will generate an independent results file
file labeled with the same USER_STRING.
These sections corresponds to the arguments sent to the
banksim executable. The two approximants to compare, along with their
PN order paramters (if relevant), are set here. Note that
the option filter-waveform-length must be set to a value
greater than the duration of the longest generated
approximant.
------------------------
Generating the workflow
------------------------
Once a configuration file as been made, create a
workspace directory and place the file into it.
Running the following command will generate a dag
that will submit the required jobs.
.. code-block:: bash
pycbc_make_faithsim --conf YOUR_INI_FILE.ini
The workflow can then be submitted by running the
generated shell script.
.. code-block:: bash
sh submit.sh
-------------------------
Understanding the results
-------------------------
The main results of the faithsim are result files, one for each
faithsim section in the file. These are whitespace separated ASCII files.
Some basic plots are also generated automatically and
placed into the 'plots' folder.
The pycbc_faithsim_plots script located in the
scripts folder is an example of
how to read the results files.
--------------------
Example config files
--------------------
*ADD SOME HERE*
Contact Alex Nitz for some more detailed examples of configuration files.