'\" t
.\"     Title: bumps
.\"    Author: Drew Parsons <dparsons@debian.org>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 10/29/2017
.\"    Manual: python-bumps man page
.\"    Source: bumps
.\"  Language: English
.\"
.TH "BUMPS" "1" "10/29/2017" "bumps" "python-bumps man page"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bumps \- data fitting and Bayesian uncertainty modeling for inverse problems
.SH "SYNOPSIS"
.HP \w'\fBbumps\fR\ 'u
\fBbumps\fR [\fIoptions\fR] \fImodelfile\fR [\fImodelargs\fR]
.HP \w'\fBbumps\fR\ 'u
\fBbumps\fR [{\fB\-?\fR\ |\ \fB\-h\fR\ |\ \fB\-\-help\fR}]
.SH "DESCRIPTION"
.PP
This manual page documents briefly the
\fBbumps\fR
command (
\fBbumps3\fR
for python3)\&.
.PP
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
\fBinfo\fR(1)
format; see below\&.
.PP
\fBbumps\fR
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\&.
.PP
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\&.
.PP
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 \*(Aq\-\*(Aq\&.
.SH "OPTIONS"
.PP
The program follows the usual GNU command line syntax, with long options starting with two dashes (`\-\*(Aq)\&. A summary of options is included below\&. For a complete description, see the HTML documentation or
\fBinfo\fR(1)
files\&.
.PP
\fB\-\-preview\fR
.RS 4
display model but do not perform a fitting operation
.RE
.PP
\fB\-\-pars=filename\fR
.RS 4
initial parameter values; fit results are saved as
\fImodelname\fR\&.par
.RE
.PP
\fB\-\-plot=log [linear|log|residuals]\fR
.RS 4
type of plot to display
.RE
.PP
\fB\-\-simulate\fR
.RS 4
simulate a dataset using the initial problem parameters
.RE
.PP
\fB\-\-simrandom\fR
.RS 4
simulate a dataset using random problem parameters
.RE
.PP
\fB\-\-shake\fR
.RS 4
set random parameters before fitting
.RE
.PP
\fB\-\-noise=5%\fR
.RS 4
percent noise to add to the simulated data
.RE
.PP
\fB\-\-seed=integer\fR
.RS 4
random number seed
.RE
.PP
\fB\-\-err\fR
.RS 4
show uncertainty estimate from curvature at the minimum
.RE
.PP
\fB\-\-cov\fR
.RS 4
show the covariance matrix for the model when done
.RE
.PP
\fB\-\-entropy\fR
.RS 4
compute entropy for the model when done [dream only]
.RE
.PP
\fB\-\-staj\fR
.RS 4
output staj file when done
.RE
.PP
\fB\-\-edit\fR
.RS 4
start the gui
.RE
.PP
\fB\-\-view=linear|log\fR
.RS 4
one of the predefined problem views; reflectometry also has fresnel, logfresnel, q4 and residuals
.RE
.PP
\fB\-\-store=path\fR
.RS 4
output directory for plots and models
.RE
.PP
\fB\-\-overwrite\fR
.RS 4
if store already exists, replace it
.RE
.PP
\fB\-\-resume=path [dream]\fR
.RS 4
resume a fit from previous stored state
.RE
.PP
\fB\-\-parallel\fR
.RS 4
run fit using multiprocessing for parallelism
.RE
.PP
\fB\-\-mpi\fR
.RS 4
run fit using MPI for parallelism (use command "mpirun \-n cpus \&.\&.\&.")
.RE
.PP
\fB\-\-batch\fR
.RS 4
batch mode; save output in \&.mon file and don\*(Aqt show plots after fit
.RE
.PP
\fB\-\-noshow\fR
.RS 4
semi\-batch; send output to console but don\*(Aqt show plots after fit
.RE
.PP
\fB\-\-remote\fR
.RS 4
queue fit to run on remote server
.RE
.PP
\fB\-\-notify=user@email\fR
.RS 4
remote fit notification
.RE
.PP
\fB\-\-queue=http://reflectometry\&.org\fR
.RS 4
remote job queue
.RE
.PP
\fB\-\-time=inf\fR
.RS 4
run for a maximum number of hours
.RE
.PP
\fB\-\-fit=amoeba [amoeba|de|dream|lm|newton|ps|pt|rl|snobfit]\fR
.RS 4
fitting engine to use; see manual for details
.RE
.PP
\fB\-\-steps=400 [amoeba|de|dream|lm|newton|ps|pt|rl|snobfit]\fR
.RS 4
number of fit iterations after any burn\-in time
.RE
.PP
\fB\-\-samples=1e4 [dream]\fR
.RS 4
set steps so the target number of samples is drawn
.RE
.PP
\fB\-\-xtol=1e\-4 [de, amoeba]\fR
.RS 4
minimum population diameter
.RE
.PP
\fB\-\-ftol=1e\-4 [de, amoeba]\fR
.RS 4
minimum population flatness
.RE
.PP
\fB\-\-pop=10 [dream, de, rl, ps]\fR
.RS 4
population size
.RE
.PP
\fB\-\-burn=100 [dream, pt]\fR
.RS 4
number of burn\-in iterations before accumulating stats
.RE
.PP
\fB\-\-thin=1 [dream]\fR
.RS 4
number of fit iterations between steps
.RE
.PP
\fB\-\-nT=25\fR
.RS 4
.RE
.PP
\fB\-\-Tmin=0\&.1\fR
.RS 4
.RE
.PP
\fB\-\-Tmax=10 [pt]\fR
.RS 4
temperatures vector; use a higher maximum temperature and a larger nT if your fit is getting stuck in local minima
.RE
.PP
\fB\-\-CR=0\&.9 [de, rl, pt]\fR
.RS 4
crossover ratio for population mixing
.RE
.PP
\fB\-\-starts=1 [newton, rl, amoeba]\fR
.RS 4
number of times to run the fit from random starting points\&.
.RE
.PP
\fB\-\-keep_best\fR
.RS 4
when running with multiple starts, restart from a point near the last minimum rather than using a completely random starting point\&.
.RE
.PP
\fB\-\-init=eps [dream]\fR
.RS 4
population initialization method:
.PP
eps
.RS 4
ball around initial parameter set
.RE
.PP
lhs
.RS 4
latin hypercube sampling
.RE
.PP
cov
.RS 4
normally distributed according to covariance matrix
.RE
.PP
random
.RS 4
uniformly distributed within parameter ranges
.RE
.sp
.RE
.PP
\fB\-\-stepmon\fR
.RS 4
show details for each step
.RE
.PP
\fB\-\-resynth=0\fR
.RS 4
run resynthesis error analysis for n generations
.RE
.PP
\fB\-\-time_model\fR
.RS 4
run the model \-\-steps times in order to estimate total run time\&.
.RE
.PP
\fB\-\-profile\fR
.RS 4
run the python profiler on the model; use \-\-steps to run multiple models for better statistics
.RE
.PP
\fB\-\-chisq\fR
.RS 4
print the model description and chisq value and exit
.RE
.PP
\fB\-m\fR, \fB\-c\fR, \fB\-p command\fR
.RS 4
run the python interpreter with bumps on the path:
.PP
m
.RS 4
command is a module such as bumps\&.cli, run as __main__
.RE
.PP
c
.RS 4
command is a python one\-line command
.RE
.PP
p
.RS 4
command is the name of a python script
.RE
.sp
.RE
.PP
\fB\-i\fR
.RS 4
start the interactive interpreter
.RE
.PP
\fB\-?\fR, \fB\-h\fR, \fB\-\-help\fR
.RS 4
display this help
.RE
.SH "SEE ALSO"
.PP
Bumps is documented fully in HTML at
\m[blue]\fB/usr/share/doc/python\-bumps\-doc/html/index\&.html\fR\m[]\&\s-2\u[1]\d\s+2
and also in the
\fBinfo\fR(1)
system\&.
.SH "AUTHOR"
.PP
\fBDrew Parsons\fR <\&dparsons@debian\&.org\&>
.RS 4
Wrote this manpage for the Debian system\&.
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2017 Drew Parsons
.br
.PP
This manual page was written for the Debian system (and may be used by others)\&.
.PP
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\&.
.PP
On Debian systems, the complete text of the GNU General Public License can be found in
/usr/share/common\-licenses/GPL\&.
.sp
.SH "NOTES"
.IP " 1." 4
/usr/share/doc/python-bumps-doc/html/index.html
.RS 4
\%file:///usr/share/doc/python-bumps-doc/html/index.html
.RE