Ubuntu Manpage: bumps - data fitting and Bayesian uncertainty modeling for inverse problems

NAME

       bumps - data fitting and Bayesian uncertainty modeling for inverse problems

SYNOPSIS

       bumps [options] modelfile [modelargs]

       bumps [{-? | -h | --help}]

DESCRIPTION

This manual page documents briefly the bumps command ( bumps3 for python3).

This manual page was written for the Debian distribution because the original program does
not have a manual page. Instead, it has documentation in HTML and in the GNU info(1)
format; see below.

bumps provides a set of routines for curve fitting and uncertainty analysis from a
Bayesian perspective. In addition to traditional optimizers which search for the best
minimum they can find in the search space, bumps provides uncertainty analysis which
explores all viable minima and finds confidence intervals on the parameters based on
uncertainty in the measured values. Bumps has been used for systems of up to 100
parameters with tight constraints on the parameters. Full uncertainty analysis requires
hundreds of thousands of function evaluations, which is only feasible for cheap functions,
systems with many processors, or lots of patience.

Bumps includes several traditional local optimizers such as Nelder-Mead simplex, BFGS and
differential evolution. Bumps uncertainty analysis uses Markov chain Monte Carlo to
explore the parameter space. Although it was created for curve fitting problems, Bumps can
explore any probability density function, such as those defined by PyMC. In particular,
the bumps uncertainty analysis works well with correlated parameters.

The modelfile is a Python script (i.e., a series of Python commands) which sets up the
data, the models, and the fittable parameters. The model arguments are available in the
modelfile as sys.argv[1:]. Model arguments may not start with '-'.

OPTIONS

       The program follows the usual GNU command line syntax, with long options starting with two
       dashes (`-'). A summary of options is included below. For a complete description, see the
       HTML documentation or info(1) files.

       --preview
           display model but do not perform a fitting operation

       --pars=filename
           initial parameter values; fit results are saved as modelname.par

       --plot=log [linear|log|residuals]
           type of plot to display

       --simulate
           simulate a dataset using the initial problem parameters

       --simrandom
           simulate a dataset using random problem parameters

       --shake
           set random parameters before fitting

       --noise=5%
           percent noise to add to the simulated data

       --seed=integer
           random number seed

       --err
           show uncertainty estimate from curvature at the minimum

       --cov
           show the covariance matrix for the model when done

       --entropy
           compute entropy for the model when done [dream only]

       --staj
           output staj file when done

       --edit
           start the gui

       --view=linear|log
           one of the predefined problem views; reflectometry also has fresnel, logfresnel, q4
           and residuals

       --store=path
           output directory for plots and models

       --overwrite
           if store already exists, replace it

       --resume=path [dream]
           resume a fit from previous stored state

       --parallel
           run fit using multiprocessing for parallelism

       --mpi
           run fit using MPI for parallelism (use command "mpirun -n cpus ...")

       --batch
           batch mode; save output in .mon file and don't show plots after fit

       --noshow
           semi-batch; send output to console but don't show plots after fit

       --remote
           queue fit to run on remote server

       --notify=user@email
           remote fit notification

       --queue=http://reflectometry.org
           remote job queue

       --time=inf
           run for a maximum number of hours

       --fit=amoeba [amoeba|de|dream|lm|newton|ps|pt|rl|snobfit]
           fitting engine to use; see manual for details

       --steps=400 [amoeba|de|dream|lm|newton|ps|pt|rl|snobfit]
           number of fit iterations after any burn-in time

       --samples=1e4 [dream]
           set steps so the target number of samples is drawn

       --xtol=1e-4 [de, amoeba]
           minimum population diameter

       --ftol=1e-4 [de, amoeba]
           minimum population flatness

       --pop=10 [dream, de, rl, ps]
           population size

       --burn=100 [dream, pt]
           number of burn-in iterations before accumulating stats

       --thin=1 [dream]
           number of fit iterations between steps

       --nT=25

       --Tmin=0.1

       --Tmax=10 [pt]
           temperatures vector; use a higher maximum temperature and a larger nT if your fit is
           getting stuck in local minima

       --CR=0.9 [de, rl, pt]
           crossover ratio for population mixing

       --starts=1 [newton, rl, amoeba]
           number of times to run the fit from random starting points.

       --keep_best
           when running with multiple starts, restart from a point near the last minimum rather
           than using a completely random starting point.

       --init=eps [dream]
           population initialization method:

           eps
               ball around initial parameter set

           lhs
               latin hypercube sampling

           cov
               normally distributed according to covariance matrix

           random
               uniformly distributed within parameter ranges

       --stepmon
           show details for each step

       --resynth=0
           run resynthesis error analysis for n generations

       --time_model
           run the model --steps times in order to estimate total run time.

       --profile
           run the python profiler on the model; use --steps to run multiple models for better
           statistics

       --chisq
           print the model description and chisq value and exit

       -m, -c, -p command
           run the python interpreter with bumps on the path:

           m
               command is a module such as bumps.cli, run as __main__

           c
               command is a python one-line command

           p
               command is the name of a python script

       -i
           start the interactive interpreter

       -?, -h, --help
           display this help

AUTHOR

       Drew Parsons <dparsons@debian.org>
           Wrote this manpage for the Debian system.

COPYRIGHT

       Copyright © 2017 Drew Parsons

       This manual page was written for the Debian system (and may be used by others).

       Permission is granted to copy, distribute and/or modify this document under the terms of
       the GNU General Public License, Version 2 or (at your option) any later version published
       by the Free Software Foundation.

       On Debian systems, the complete text of the GNU General Public License can be found in
       /usr/share/common-licenses/GPL.

NOTES

        1. /usr/share/doc/python-bumps-doc/html/index.html
           file:///usr/share/doc/python-bumps-doc/html/index.html