Content

This package provides Tcl wrapper for optimization procedures.

Currently, next list of optimization algorithms is supported:

• Levenberg-Marquardt Least Squares Fitting
• Differential Evolution algorithm
• Generalized Simulated Annealing algorithm
• Limited-memory Broyden–Fletcher–Goldfarb–Shanno algorithm (L-BFGS)

Many parts of source code were re-implemented, others reuse the original C routines through native Tcl C API bindings.

The sources of procedures are:

• Levenberg-Marquardt Least Squares Fitting
• Differential Evolution algorithm
• Generalized Simulated Annealing algorithm
• Limited-memory Broyden–Fletcher–Goldfarb–Shanno algorithm (L-BFGS)

Native numerical interface

The Tcl optimizer classes keep their existing options and result dictionaries. Their numerical helper methods call C adapters directly with Tcl lists and scalars. The adapters perform list conversion, allocate temporary arrays, invoke the original numerical routines, build Tcl results, and free all temporary arrays before returning, including on input errors. Input lists are not modified. There are no pointer handles, array allocation commands, or manual cleanup calls.

The following internal commands are in the ::tclopt namespace. Matrix lists use the original column-major layout. Index intervals are zero-based with an exclusive end. The diagonal passed to mp_lmpar is indexed by ifree and can contain fixed parameters as well as free parameters.

Command arguments	Result
mp_qrfac m n a lda pivot lipvt	Dictionary: a, rdiag, acnorm, wa, ipvt.
mp_enorm x	Euclidean norm of the list x.
mp_lmpar n r ldr ipvt ifree diag qtb delta par	Dictionary: par, r, x, sdiag, wa1, wa2.
mp_covar n r ldr ipvt tol	Dictionary: r, wa.
update_trial_interval x fx dx y fy dy t ft dt tmin tmax brackt	Dictionary: uinfo, info, x, fx, dx, y, fy, dy, t, ft, dt, brackt.
owlqn_pseudo_gradient x g n c start end	List containing the n pseudo-gradient values.
owlqn_project d sign start end	Projected copy of d; values outside the interval are preserved.
owlqn_x1norm x start end	Sum of absolute values over the interval.
rnd_uni seedVar	Random value; updates the named Tcl seed variable in the caller frame.

For rnd_uni, initialize an ordinary variable to a negative seed, for example set seed -1234, then call ::tclopt::rnd_uni seed. The original generator and sequence are retained, including its existing static internal state; this is not an independent random stream per variable.

Installation and dependencies

For building you need:

• Tcl9
• gcc compiler
• make tool

For run you also need:

• argparse
• Tcllib

Plots and graphs in examples need ticklecharts package.

To build run

./configure
make
sudo make install

If you have different versions of Tcl on the same machine, you can set the path to this version with -with-tcl=path flag to configure script.

For Windows build it is strongly recommended to use MSYS64 UCRT64 environment, the above steps are identical if you run it from UCRT64 shell.

Installation and distribution targets

make install installs the binary, pkgIndex.tcl, and tclopt.tcl into $(libdir)/tclopt0.3, the C headers into $(includedir), manpages into $(mandir)/mann, and HTML documentation plus the license into $(datadir)/tclopt0.3/doc. The directories follow the configured prefix. DESTDIR stages the entire installation without changing that layout. Set both --prefix and --exec-prefix when relocating the complete installation:

./configure --prefix=/desired/prefix --exec-prefix=/desired/prefix --with-tcl=/path/to/tcl/lib
make
make install DESTDIR=/temporary/stage
make uninstall DESTDIR=/temporary/stage

make uninstall includes uninstall-binaries, uninstall-libraries, and uninstall-doc. It removes the package directory and its named headers and manpages, and preserves unrelated files in shared include, man, and documentation directories. Run it with the same directory overrides used for installation.

make dist creates dist/tclopt0.3.tar.gz by staging make install. make dist-zip also creates dist/tclopt0.3.zip with the same contents. Extract the archive directly into the desired installation prefix: its root contains lib, include, and share (or their configured equivalents), without an enclosing package directory. These are binary installation archives for the build platform and Tcl ABI; source files, tests, and examples remain in the checkout. All configured installation directories must be beneath prefix for distribution.

DIST_ROOT changes the staging/output directory and DIST_NAME changes the staging directory and archive basename. make dist-clean removes those outputs. Installation and distribution use the existing documentation and do not invoke Ruff or Sphinx. Re-run configure after generating documentation to refresh the HTML/static-file list.

Supported platforms

I've tested it on:

• Kubuntu 24.04 with Tcl 9
• Windows 11 in MSYS64 UCRT64 environment with Tcl9

Documentation

You can find documentation with examples here

Interactive help

All public methods have interactive help. To get information about method (including new and create) and its arguments call it with -help switch:

package require tclopt
namespace import ::tclopt::*
Mpfit new -help

Creates optimization object that does least squares fitting using modified
Levenberg-Marquardt algorithm. For more detailed description please see
documentation. Can accepts unambiguous prefixes instead of switches names.
Accepts switches only before parameters.
    Switches:
        -funct value - Required. Name of the procedure that should be
            minimized.
        -m value - Required. Number of data points.
        -pdata value - List or dictionary that provides private data to funct
            that is needed to evaluate residuals. Usually it contains x and y values
            lists, but you can provide any data necessary for function residuals
            evaluation. Will be passed upon each function evaluation without
            modification. Default value is .
        -ftol value - Control termination of mpfit. Termination occurs when both
            the actual and predicted relative reductions in the sum of squares are
            at most ftol. Default value is 1e-10.
        -xtol value - Control termination of mpfit. Termination occurs when the
            relative error between two consecutive iterates is at most xtol. Default
            value is 1e-10.
        -gtol value - Control termination of mpfit. Termination occurs when the
            cosine of the angle between fvec and any column of the jacobian is at
            most gtol in absolute value. Default value is 1e-10.
        -stepfactor value - Used in determining the initial step bound. This
            bound is set to the product of factor and the euclidean norm of diag*x
            if nonzero, or else to factor itself. Default value is 100.
        -covtol value - Range tolerance for covariance calculation. Default
            value is 1e-14.
        -maxiter value - Maximum number of iterations. Default value is 200.
        -maxfev value - Control termination of mpfit. Termination occurs when
            the number of calls to funct is at least maxfev by the end of an
            iteration. If it equals to 0, number of evaluations is not restricted.
            Default value is 0.
        -epsfcn value - Finite derivative step size. Default value is
            2.2204460e-16.
        -nofinitecheck - Boolean. Enable check for infinite quantities.
        -help - Help switch, when provided, forces ignoring all other switches
            and parameters, prints the help message to stdout, and returns up to 2
            levels above the current level.

Best to do it in interactive console, see tkcon