
*********************************
MTfit
*********************************

Bayesian Moment Tensor Inversion Code by David J Pugh
MTfit is based on the bayesian approach presented in Pugh, D J, 2015,
Bayesian Source Inversion of Microseismic Events, PhD Thesis, Department of Earth Sciences,
University of Cambridge.

The code can be called from the command line directly or from within python itself (see below)


**Restricted:  For Non-Commercial Use Only**
This code is protected intellectual property and is available solely for teaching
and non-commercially funded academic research purposes.

Applications for commercial use should be made to Schlumberger or the University of Cambridge.


Input Data
==================================

There are several different input data types, and it is also possible to add additional parsers using the ``MTfit.parsers`` entry point.


The required data structure for running MTfit is very simple, the inversion expects a python dictionary of the data in the format::

    >>> data={'PPolarity':{'Measured':numpy.matrix([[-1],[-1]...]),
                         'Error':numpy.matrix([[0.01],[0.02],...]),
                         'Stations':{'Name':['Station1','Station2',...],
                                     'Azimuth':numpy.matrix([[248.0],[122.3]...]),
                                     'TakeOffAngle':numpy.matrix([[24.5],[22.8]...]),
                                    }
                         },
              'PSHAmplitudeRatio':{...},
              ...
              'UID':'Event1'
              }

For more information on the data keywords and how to set them up, see :class:`~MTfit.inversion.Inversion` docstrings.

The data dictionary can be passed directly to the :class:`~MTfit.inversion.Inversion` object (simple if running within python), or from a binary pickled object, these can be made by simply using pickle (or cPickle)::

    >>> pickle.dump(data,open(filename,'wb'))


The coordinate system is that the Azimuth is angle from x towards y and TakeOffAngle is the angle from positive z.

For data in different formats it is necessary to write a parser to convert the data into this dictionary format.

There is a parser for csv files with format

CSV
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There is a CSV format parser which reads CSV files.
The CSV file format is to have events split by blank lines, a header line showing where the information is, UID and data-type information stored in the first column, e.g.::

    UID=123,,,,
    PPolarity,,,,
    Name,Azimuth,TakeOffAngle,Measured,Error
    S001,120,70,1,0.01
    S002,160,60,-1,0.02
    P/SHRMSAmplitudeRatio,,,,
    Name,Azimuth,TakeOffAngle,Measured,Error
    S003,110,10,1,0.05 0.04
    ,,,,
    PPolarity ,,,,
    Name,Azimuth,TakeOffAngle,Measured,Error
    S003,110,10,1,0.05

This is a CSV file with 2 events, one event ID of 123, and PPolarity data at station S001 and station S002 and P/SHRMSAmplitude data at station S003,
and a second event with no ID (will default to the event number, in this case 2) with PPolarity data at station S003.


hyp
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There is a hyp format parser which reads hyp files as defined by `NonLinLoc <http://alomax.free.fr/nlloc/soft6.00/formats.html#_location_hypphs_>`_, this allows output files from NonLinLoc to be directly read.

Output
==================================

The default output is to output a MATLAB file containing 2 structures and a cell array, although there are two other possible formats, and others can be added (see MTfit.extensions).
The ``Events`` structure has the following fieldnames: ``MTspace`` and ``Probability``.

    * ``MTspace`` - The moment tensor samples as a 6 by n vector of the form::

        Mxx
        Myy
        Mzz
        sqrt(2)*Mxy
        sqrt(2)*Mxz
        sqrt(2)*Myz

    * ``Probability`` - The corresponding probability values

The ``Other`` structure contains information about the inversion

The ``Stations`` cell array contains the station information, including, if available, the polarity:

    +-----+----------------------+---------------------------+--------------------------+
    |Name |Azimuth(angle from x) |TakeOffAngle(angle from z) |P Polarity (if available) |
    +-----+----------------------+---------------------------+--------------------------+

A log file for each event is also produced to help with debugging and understanding the results.

Pickle format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is also possible to output the data structure as a pickled file using the pickle output options, storing the output dictionary as a pickled file.

hyp format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The results can be outputted in the `NonLinLoc hyp format <http://alomax.free.fr/nlloc/soft6.00/formats.html#_location_hypphs_>`_,
with the range of solutions sampled outputted as a binary file with the following format::

    binary file version (unsigned long integer)
    total_number_samples(unsigned long integer)
    number_of_saved_samples(unsigned long integer)
    converted (bool flag)
    Ln_bayesian_evidence (double)
    Kullback-Liebeler Divergence from sampling prior (double)

Then for each moment tensor sample (up to ``number_of_saved_samples`` )::

    Probability (double)
    Ln_probability(double)
    Mnn (double)
    Mee (double)
    Mdd (double)
    Mne (double)
    Mnd (double)
    Med (double)

if Converted is true then each sample also contains::

    gamma (double)
    delta (double)
    kappa (double)
    h (double)
    sigma (double)
    u (double)
    v (double)
    strike1 (double)
    dip1 (double)
    rake1 (double)
    strike2 (double)
    dip2 (double)
    rake2 (double)

If there are multiple events saved, then the next event starts immediately after the last with the same format. The output binary file can be re-read into python using MTfit.inversion.read_binary_output.





Running in parallel
==================================

The code is written to run in parallel using multiprocessing, it will initialise as many threads as the system reports available.
A single thread mode can be forced using:

    * -l, --singlethread, --single, --single_thread flag on the command line
    * parallel=False keyword in the MTfit.inversion.Inversion object initialisation

It is also possible to run this code on a cluster using qsub [requires pyqsub]. This can be called from the commandline using a flag:

    * -q, --qsub, --pbs

This runs using a set of default parameters, however it is also possible to adjust these parameters using commandline flags (use -h flag for help and usage).

There is a bug when using mpi and very large result sizes, giving a size error (negative integer) in mpi4py. If this occurs, lower the sample size and it will be ok.


WARNING:

    If running this on a server, be aware that not setting the number of workers option ``--numberworkers``, when running in parallel, means that as many processes as processors will be spawned, slowing down the machine for any other users.


Command line flags
==================================

To obtain a list of the command line flags use the -h flag::

    $ MTfit -h

This will provide a list of the arguments and their usage.


Running from the command line
==================================

To run from the command line on  linux/*nix  it is necessary to make sure that the MTfit script installed is on the path,
or to set up a manual alias/script, e.g. for bash::

    $ python -c "import MTfit;MTfit.run.MTfit()" $*


On windows using powershell add the following commandlet to your profile (for information on customizing your powershell profile see: http://www.howtogeek.com/50236/customizing-your-powershell-profile/)::

    function MTfit{
        $script={
            python -c "import MTfit;MTfit.run.MTfit()" $args
        }
        Invoke-Command -ScriptBlock $script -ArgumentList $args
    }




Running from within python
==================================

To run from within python, (assuming the module is on your PYTHONPATH) first::

    >>> import MTfit

Then to run the inversion it is necessary to set up an MTfit.inversion.Inversion object::

    >>> myInversion=MTfit.Inversion(**kwargs)

For more information on the arguments for initialising the inversion object, see the MTfit.inversion.Inversion docstrings


Running Module Tests
==================================

There is a unittest suite for this module that can be run from the python interpreter::

    >>> import MTfit
    >>> MTfit.run_tests()

Or during setup:

    >>> python setup.py test

If there are any errors please see the documentation and if necessary contact the developer for assistance.




Command Line Options
==================================

Usage:

	MTfit [-h] [-d DATAFILE] [-s LOCATION_PDF_FILE_PATH]
             [-a {iterate,time,mcmc,transdmcmc}] [-l] [-n N] [-m MEM] [-c]
             [-b] [--nstations NUMBER_STATIONS]
             [--nanglesamples NUMBER_LOCATION_SAMPLES] [-f] [--not_file_safe]
             [-i INVERSION_OPTIONS] [-o FID] [-x MAX_SAMPLES] [-t MAX_TIME]
             [-e] [-r] [--marginalise_relative] [-R] [--invext DATA_EXTENSION]
             [--angleext ANGLE_EXTENSION] [-S MINIMUM_NUMBER_INTERSECTIONS]
             [-M] [-B] [-X MIN_NUMBER_INITIALISATION_SAMPLES] [-T]
             [-Q [QUALITY_CHECK]] [-D] [-V VERBOSITY] [-g]
             [-j DIMENSION_JUMP_PROB] [-y {grid}] [-u MIN_ACCEPTANCE_RATE]
             [-v MAX_ACCEPTANCE_RATE] [-w ACCEPTANCE_RATE_WINDOW]
             [-W WARNINGS] [-z LEARNING_LENGTH] [--version] [--mpi_call]
             [--output-format {matlab,pickle,hyp}]
             [--results-format {full_pdf,hyp}] [--no-dist]
             [--dc-prior DC_PRIOR] [--sampling SAMPLING]
             [--sample-models SAMPLE_DISTRIBUTION]
             [--sampling-prior SAMPLING_PRIOR] [--no-normalise] [--convert]
             [--discard DISCARD] [--mpioutput] [--combine_mpi_output]
             [--c_generate] [--relative_loop] [--bin-scatangle]
             [--bin-size BIN_SCATANGLE_SIZE] [-q] [--nodes QSUB_NODES]
             [--ppn QSUB_PPN] [--pmem QSUB_PMEM] [--email QSUB_M]
             [--emailoptions QSUB_M] [--name QSUB_N]
             [--walltime QSUB_WALLTIME] [--queue QSUB_Q]
             [--bladeproperties QSUB_BLADE_PROPERTIES]
             [--feature QSUB_BLADE_FEATURE]
             [data_file]

Positional Arguments:
============================

  data_file             Data file to use for the inversion, optional but must
                        be specified either as a positional argument or as an
                        optional argument (see -d below) If not specified
                        defaults to all *.inv files in current directory, and
                        searches for all anglescatterfiles in the directory
                        too. Inversion file extension can be set using
                        --invext option. Angle scatter file extension can be
                        set using --angleext option
                         
                         

Optional Arguments:
============================

  -h, --help            show this help message and exit
                         
                         
  -d DATAFILE, --datafile DATAFILE, --data_file DATAFILE
                        Data file to use for the inversion. Can be provided as
                        a positional argument.
                            There are several different data file types:
                         
                                * pickled dictionary
                                * csv file
                                * NLLOC hyp file
                         
                            The data file is a pickled python dictionary of
                        the form::
                        {'DataType':{'Stations':{'Name':['STA1','STA2',...],
                                'Azimuth':np.matrix([[190],[40],...]),
                                'TakeOffAngle':np.matrix([[70],[40],...])},
                                'Measured':np.matrix([[1],[-1],...]),
                                'Error':np.matrix([[0.01],[0.02],...])}}
                         
                            e.g.::
                              {'P/SHRMSAmplitudeRatio':{'Stations':{'Name':['S
                        0649',"S0162"],
                                'Azimuth':np.array([90.0,270.0]),
                                'TakeOffAngle':np.array([30.0,60.0])},
                                'Measured':np.matrix([[1],[-1]]),
                                'Error':np.matrix([[ 0.001,0.02],[
                        0.001,0.001]])}}
                         
                            Or a CSV file with events split by blank lines, a
                        header line showing which row corresponds to which
                        information (default is as shown here),
                            UID and data-type information stored in the first
                        column,
                            e.g.::
                                    UID=123,,,,
                                    PPolarity,,,,
                                    Name,Azimuth,TakeOffAngle,Measured,Error
                                    S001,120,70,1,0.01
                                    S002,160,60,-1,0.02
                                    P/SHRMSAmplitudeRatio,,,,
                                    Name,Azimuth,TakeOffAngle,Measured,Error
                                    S003,110,10,1,0.05 0.04
                                    ,,,,
                                    PPolarity ,,,,
                                    Name,Azimuth,TakeOffAngle,Measured,Error
                                    S003,110,10,1,0.05
                         
                            Is a CSV file with 2 events, one event UID of 123,
                        and PPolarity data at S001 and S002 and
                        P/SHRMSAmplitude data at S003,
                            and a second event with no UID (will default to
                        the event number, in this case 2) with PPolarity data
                        at S003.
                         
                            This data format can be constructed manually or
                        automatically.
                         
                         
  -s LOCATION_PDF_FILE_PATH, --anglescatterfilepath LOCATION_PDF_FILE_PATH,
  --location_pdf_file_path LOCATION_PDF_FILE_PATH,
  --location_file_path LOCATION_PDF_FILE_PATH,
  --scatterfilepath LOCATION_PDF_FILE_PATH,
  --scatter_file_path LOCATION_PDF_FILE_PATH

                        Path to location scatter angle files - wild cards
                        behave as normal.
                            To include the model and location uncertainty, a
                        ray path angle pdf file must be provided.
                            This is of the form::
                            probability1
                            Station1    Azimuth1    TakeOffAngle1
                            Station2    Azimuth2    TakeOffAngle2
                            .
                            .
                            .
                            StationN    AzimuthN    TakeOffAngleN
                         
                            probability2
                            Station1    Azimuth1    TakeOffAngle1
                            Station2    Azimuth2    TakeOffAngle2
                            .
                            .
                            .
                            StationN    AzimuthN    TakeOffAngleN
                         
                            e.g.::
                            504.7
                            S0529   326.1   131.7
                            S0083   223.7   118.2
                            S0595   42.6    117.8
                            S0236   253.6   118.6
                            &&
                            504.7
                            S0529   326.1   131.8
                            S0083   223.7   118.2
                            S0595   42.7    117.9
                            S0236   253.5   118.7
                         
                         
  -a {iterate,time,mcmc,transdmcmc}, --algorithm {iterate,time,mcmc,transdmcmc}
                        Selects the algorithm used for the search.
                        [default=time]
                            Possible algorithms are:
                                iterate (random sampling of the source space
                        for a set number of samples)
                                time (random sampling of the source space for
                        a set time)
                                mcmc (Markov chain Monte Carlo sampling)
                         
                         
  -l, --singlethread, --single, --single_thread
                        Flag to disable parallel computation
                         
                         
  -n N, --numberworkers N, --number_workers N
                        Set the number of workers used in the parallel
                        computation. [default=all available cpus]
                         
                         
  -m MEM, --mem MEM, --memory MEM, --physical_memory MEM, --physicalmemory MEM
                        Set the maximum memory used in Gb if psutil not
                        available [default=8Gb]
                         
                         
  -c, --doublecouple, --double-couple, --double_couple, --dc, --DC
                         Flag to constrain the inversion to double-couple
                        sources only
                         
                         
  -b, --compareconstrained, --compare_constrained
                         Flag to run two inversions, one constrained to
                        double-couple and one unconstrained
                         
                         
  --nstations NUMBER_STATIONS
                        Set the maximum number of stations without having to
                        load an angle pdf file - used for calculating sample
                        sizes and memory sizes, and can speed up the
                        calculation a bit, but has no effect on result.
                         
                         
  --nanglesamples NUMBER_LOCATION_SAMPLES,
  --nlocationsamples NUMBER_LOCATION_SAMPLES,
  --number_location_samples NUMBER_LOCATION_SAMPLES,
  --number-location-samples NUMBER_LOCATION_SAMPLES

                        Set the maximum number of angle pdf samples to use. If
                        this is less than the total number of samples, a
                        subset are randomly selected [default=0].
                         
                         
  -f, --file_sample, --file-sample, --filesample, --disk_sample,
  --disk-sample, --disksample

                        Save sampling to disk (allows for easier recovery and
                        reduces memory requirements, but can be slower)
                         
                         
  --not_file_safe, --not-file-safe, --notfilesafe, --no_file_safe,
  --no-file-safe, --nofilesafe

                        Disable file safe saving (i.e. copy and write to .mat~
                        then copy back
                         
                         
  -i INVERSION_OPTIONS, --inversionoptions INVERSION_OPTIONS,
  --inversion_options INVERSION_OPTIONS

                        Set the inversion data types to use: comma delimited.
                            If not set, the inversion uses all the data types
                        in the data file.
                            e.g.
                            PPolarity,P/SHRMSAmplitudeRatio
                         
                            Needs to correspond to the data types in the data
                        file.
                         
                            If not specified can lead to independence errors:
                        e.g.
                            P/SH Amplitude Ratio and P/SV Amplitude Ratio can
                        give SH/SV Amplitude Ratio.
                            Therefore using SH/SV Amplitude Ratio in the
                        inversion is reusing data and will artificially
                        sharpen the PDF.
                            This applies to all forms of dependent
                        measurements.
                         
                         
                         
  -o FID, --out FID, --fid FID, --outputfile FID, --outfile FID
                        Set output file basename [default=MTfitOutput]
                         
                         
  -x MAX_SAMPLES, --samples MAX_SAMPLES, --maxsamples MAX_SAMPLES,
  --max_samples MAX_SAMPLES, --chain_length MAX_SAMPLES,
  --max-samples MAX_SAMPLES, --chain-length MAX_SAMPLES, --chainlength MAX_SAMPLES

                        Iteration algorithm: Set maximum number of samples to
                        use [default=6000000]. McMC algorithms: Set chain
                        length [default=10000], trans-d McMC [default=100000]
                         
                         
  -t MAX_TIME, --time MAX_TIME, --maxtime MAX_TIME, --max_time MAX_TIME
                        Time algorithm: Set maximum time to use [default=600]
                         
                         
  -e, --multiple_events, --multiple-events
                        Run using events using joint PDF approach
                         
                         
  -r, --relative_amplitude, --relative-amplitude
                        Run using events using joint PDF approach
                         
                         
  --marginalise_relative, --marginalise, --marginalise-relative
                        Flag to marginalise location uncertainty in relative
                        amplitude case [default=False]
                         
                         
  -R, --recover         Recover crashed run (ie restart from last event not
                        written out)]
                         
                         
  --invext DATA_EXTENSION, --dataextension DATA_EXTENSION,
  --dataext DATA_EXTENSION, --data-extension DATA_EXTENSION,
  --data_extension DATA_EXTENSION

                        Set data file extension to search for when inverting
                        on a folder
                         
                         
  --angleext ANGLE_EXTENSION, --locationextension ANGLE_EXTENSION,
  --locationext ANGLE_EXTENSION, --location-extension ANGLE_EXTENSION,
  --location_extension ANGLE_EXTENSION

                        Set location sample file extension to search for when
                        inverting on a folder
                         
                         
  -S MINIMUM_NUMBER_INTERSECTIONS,
  --minimum_number_intersections MINIMUM_NUMBER_INTERSECTIONS,
  --min_number_intersections MINIMUM_NUMBER_INTERSECTIONS,
  --minimum-number-intersections MINIMUM_NUMBER_INTERSECTIONS,
  --min-number-intersections MINIMUM_NUMBER_INTERSECTIONS

                        For relative amplitude inversion, the minimum number
                        of intersecting stations required (must be greater
                        than 1) [default=2]
                         
                         
  -M, --mpi, --MPI      Run using mpi - will reinitialise using mpirun (mpi
                        etc needs to be added to path)
                         
                         
  -B, --benchmark, --benchmarking
                        Run benchmark tests for the event
                         
                         
  -X MIN_NUMBER_INITIALISATION_SAMPLES,
  --min_number_check_samples MIN_NUMBER_INITIALISATION_SAMPLES,
  --min_number_initialisation_samples MIN_NUMBER_INITIALISATION_SAMPLES

                        Minimum number of samples for McMC initialiser, or the
                        minimum number of samples required when using quality
                        check (-Q)
                         
                         
  -T, --test, --test    Run MTfit Test suite (if combined with -q runs test
                        suite on cluster
                         
                         
  -Q [QUALITY_CHECK], --quality [QUALITY_CHECK]
                        Run MTfit with quality checks enabled [default=False].
                        Checks if an event has a percentage of non-zero
                        samples lower than the flag - values from 0-100.
                         
                         
  -D, --debug           Run MTfit with debugging enabled.
                         
                         
  -V VERBOSITY, --verbosity VERBOSITY
                        Set verbosity level for non-fatal errors [default=0].
                         
                         
  -g, --diagnostics     Run MTfit with diagnostic output. Outputs the full
                        chain and sampling - wil make a large file.
                         
                         
  -j DIMENSION_JUMP_PROB, --jumpProbability DIMENSION_JUMP_PROB,
  --jumpProb DIMENSION_JUMP_PROB, --jumpprob DIMENSION_JUMP_PROB,
  --jumpProb DIMENSION_JUMP_PROB, --dimensionJumpProb DIMENSION_JUMP_PROB,
  --dimensionjumpprob DIMENSION_JUMP_PROB

                        Sets the probability of making a dimension jump in the
                        Trans-Dimensional McMC algorithm [default=0.01]
                         
                         
  -y {grid}, --initialSampling {grid}
                        Sets the initialisation sampling method for McMC
                        algorithms choices:
                        grid - use grid based sampling to find non-zero
                        initial sample [default=grid]
                         
                         
  -u MIN_ACCEPTANCE_RATE, --minAcceptanceRate MIN_ACCEPTANCE_RATE,
  --minacceptancerate MIN_ACCEPTANCE_RATE,
  --min_acceptance_rate MIN_ACCEPTANCE_RATE

                        Set the minimum acceptance rate for the McMC algorithm
                        [mcmc default=0.3, transdmcmc default=0.05]
                         
                         
  -v MAX_ACCEPTANCE_RATE, --maxAcceptanceRate MAX_ACCEPTANCE_RATE,
  --maxacceptancerate MAX_ACCEPTANCE_RATE,
  --max_acceptance_rate MAX_ACCEPTANCE_RATE

                        Set the maximum acceptance rate for the McMC algorithm
                        [mcmc default=0.5, transdmcmc default=0.2]
                         
                         
  -w ACCEPTANCE_RATE_WINDOW,
  --acceptanceLearningWindow ACCEPTANCE_RATE_WINDOW,
  --acceptancelearningwindow ACCEPTANCE_RATE_WINDOW

                        Sets the window for calculating and updating the
                        acceptance rate for McMC algorithms [default=500]
                         
                         
  -W WARNINGS, --warnings WARNINGS, --Warnings WARNINGS
                        Sets the warning visibility.
                         
                            options are:
                         
                                * "e","error" - turn matching warnings into
                        exceptions
                                * "i","ignore" - never print matching warnings
                                * "a","always" - always print matching
                        warnings
                                * "d","default" - print the first occurrence
                        of matching warnings for each location where the
                        warning is issued
                                * "m","module" - print the first occurrence of
                        matching warnings for each module where the warning is
                        issued
                                * "o","once" - print only the first occurrence
                        of matching warnings, regardless of location
                         
                         
                         
  -z LEARNING_LENGTH, --learningLength LEARNING_LENGTH,
  --learninglength LEARNING_LENGTH, --learning_length LEARNING_LENGTH

                        Sets the number of samples to discard as the learning
                        period [default=5000]
                         
                         
  --version             show program's version number and exit
                         
                         
  --mpi_call            DO NOT USE - only for spawning mpi subprocess
                         
                         
  --output-format {matlab,pickle,hyp}, --output_format {matlab,pickle,hyp},
  --outputformat {matlab,pickle,hyp}, --format {matlab,pickle,hyp}

                        Output file format [default=matlab]
                         
                         
  --results-format {full_pdf,hyp}, --results_format {full_pdf,hyp},
  --resultsformat {full_pdf,hyp}

                        Output results data format (extensible)
                        [default=full_pdf]
                         
                         
  --no-dist, --no_dist, --nodist
                        Do not output station distribution if running location
                        samples
                         
                         
  --dc-prior DC_PRIOR, --dc_prior DC_PRIOR, --dcprior DC_PRIOR
                        Prior probability for the double-couple model when
                        using the Trans-Dimensional McMC algorithm
                         
                         
  --sampling SAMPLING, --sampling SAMPLING, --sampling SAMPLING
                        Random moment tensor sampling distribution
                         
                         
  --sample-models SAMPLE_DISTRIBUTION,
  --sample_distribution SAMPLE_DISTRIBUTION, --samplemodels SAMPLE_DISTRIBUTION

                        Alternate models for random sampling (Monte Carlo
                        algorithms only)
                         
                         
  --sampling-prior SAMPLING_PRIOR, --sampling_prior SAMPLING_PRIOR,
  --samplingprior SAMPLING_PRIOR

                        Prior probability for the model distribution when
                        using the McMC algorithm, alternatively the prior
                        distribution for the source type parameters gamma and
                        delta for use by the Bayesian evidence calculation for
                        the MC algorithms
                         
                         
  --no-normalise, --no-norm, --no_normalise, --no_norm
                        Do not normalise the output pdf
                         
                         
  --convert             Convert the output MTs to Tape parameters, hudson
                        parameters and strike dip rakes.
                         
                         
  --discard DISCARD     Fraction of maxProbability * total samples to discard
                        as negligeable.
                         
                         
  --mpioutput, --mpi_output, --mpi-output
                        When the mpi flag -M is used outputs each processor
                        individually rather than combining
                         
                         
  --combine_mpi_output, --combine-mpi-output, --combinempioutput
                        Combine the mpi output from the mpioutput flag. The
                        data path corresponds to the root path for the mpi
                        output
                         
                         
  --c_generate, --c-generate, --generate
                        Generate moment tensor samples in the probability
                        evaluation
                         
                         
  --relative_loop, --relative-loop, --relativeloop, --loop
                        Loop over independent non-zero samples randomly to
                        construct joint rather than joint samples
                         
                         

Scatangle:
============================

  
   

  --bin-scatangle, --binscatangle, --bin_scatangle
                        Bin the scatangle file to reduce the number of samples
                        [default=False]. --bin-size Sets the bin size
                        parameter .
                         
                         
  --bin-size BIN_SCATANGLE_SIZE, --binsize BIN_SCATANGLE_SIZE,
  --bin_size BIN_SCATANGLE_SIZE

                        Sets the scatangle bin size parameter [default=1.0]
                         
                         

Cluster:
============================

  
  Commands for using MTfit on a cluster environment using qsub/PBS

  -q, --qsub, --pbs     Flag to set MTfit to submit to cluster
                         
                         
  --nodes QSUB_NODES    Set number of nodes to use for job submission.
                        [default=1]
                         
                         
  --ppn QSUB_PPN        Set ppn to use for job submission. [default=8]
                         
                         
  --pmem QSUB_PMEM      Set pmem (Gb) to use for job submission.
                        [default=2Gb]
                         
                         
  --email QSUB_M        Set user email address.
                         
                         
  --emailoptions QSUB_M
                        Set PBS -m mail options. Requires email address using
                        -M. [default=bae]
                         
                         
  --name QSUB_N         Set PBS -N job name options. [default=MTfit]
                         
                         
  --walltime QSUB_WALLTIME
                        Set PBS maximum wall time. Needs to be of the form
                        HH:MM:SS. [default=24:00:00]
                         
                         
  --queue QSUB_Q        Set PBS -q Queue options. [default=batch]
                         
                         
  --bladeproperties QSUB_BLADE_PROPERTIES
                        Set desired PBS blade properties. [default=False]
                         
                         
  --feature QSUB_BLADE_FEATURE
                        Set desired Torque feature arguments. [default=False]
                         
                         
