NAME: mcmcsamp PURPOSE: (one line only) Markov-chain Monte-Carlo sampling tool DESCRIPTION: CATEGORY: Statistics CALLING SEQUENCE: mcmcsamp,vals,scale,region,pdf INPUTS: vals - n-dimensional vector with initial guess for solution scale - inital estimate of size of variation to sample, roughly 2x of the expected standard deviation. One value per input variable. If burn-in is running, this input information is modified and will contain the final dynamically determined values. region - size of sampling region, roughly 5x bigger than scale. One value per input variable. OPTIONAL INPUT PARAMETERS: KEYWORD INPUT PARAMETERS: FUNCTION_NAME - [REQUIRED!!!] Name of function that evaluates the merit function being minimized and sampled. This function must take a single vector of input (ie., vals) and will return a scalar value (typically a chi-squared metric). NSTEPS - Number of samples to collect in the chain. Default=1000 NOBURNIN - Flag, if set, will suppress any burn-in calculations and vals/scale are assumed to already be fully tuned and ready to go. With judicious use of the input arguments you can, if desired, fully control the burn-in process if the built-in algorithm is not effective. VERBOSE - Flag, if set, will generate some verbose comments to be printed during operation. Default is no printed output. DISPLAY - Flag, if set, will provide output graphics to watch the sampling process. OUTPUTS: pdf - [NxM] array that is the Markov chain. N is the dimenison of vals and M is the number of steps requested. KEYWORD OUTPUT PARAMETERS: ACCEPTANCE - Scalar value that is the total acceptance rate for the returned chain (does not include burn-in). COMMON BLOCKS: SIDE EFFECTS: RESTRICTIONS: PROCEDURE: MODIFICATION HISTORY: 2016/12/22, Written by Marc W. Buie, Southwest Research Institute with input from Alex Parker. 2017/01/06, modified to allow imposing restricted domains for sampling