# QOpt

A simple optimization package.

## Optimization Paradigms

The latest version of QOpt supports the following paradigms.
- Steepest Descent (Gradient Descent)
- Newton's Method
- Genetic Optimization
- Simulated Annealing

# Getting Started

## Importing `maria-linalg`

You must import the latest version of the Rust crate [`maria-linalg`](https://crates.io/crates/maria-linalg) in order to use this package.  

## Creating an Objective Function

First, you must define an objective function `struct`.  This represents a function that accepts an `N`-dimensional vector and outputs a scalar.

`Optimizer` accepts up to three functions.
- `Function::objective` (*required*).  Accepts continuous and discrete input.  Evaluates to the function output (`f64`).
- `Function::gradient` (*optional*).  Accepts continuous input.  Evaluates to the function gradient (`Vector<N>`).
- `Function::hessian` (*optional*).  Accepts continuous input.  Evaluates to the function Hessian (`Matrix<N>`).

See the example below.  Note that you must also import `maria_linalg::Vector` and (only if you implement the Hessian) `maria_linalg::Matrix`.

```
use qopt::Function;
use maria_linalg::{Matrix, Veector};

/// Number of continuous variables.
const C: usize = 6;

/// Number of discrete variables.
const D: usize = 0;

fn objective(&self, continuous: Vector<C>, discrete: Vector<D>) -> f64 {
    // Required
}

fn gradient(&self, continuous: Vector<C>) -> Vector<C> {
    // Optional
}

fn hessian(&self, continuous: Vector<C>) -> Matrix<C> {
    // Optional
}
```

## Creating an `Optimizer`

Once you have an `objective` function, you can create your `Optimizer`.

```
use qopt::Optimizer;

/// Number of individuals per optimization iteration.
/// 
/// For deterministic methods (gradient descent or Newton's method), this should be 1.
/// For stochastic methods (genetic optimization or simulated annealing), this should be about 100.
const POPULATION: usize = 100;

fn main() {
    let f = MyFunction::new();
    let optimizer: Optimizer<C, D, POPULATION> = Optimizer::new(objective, Some (gradient), Some (hessian));

    // An initial guess for our continuous variables
    let c = Vector::zero();

    // An initial guess for our discrete variables
    let d = Vector::zero();

    let output = optimizer.optimize(c, d, &[]);

    println!("{}", output);
}
```

## Running the Optimizer

You are now ready to run the optimizer using command-line arguments.

The structure for a command to execute the optimizer is as follows.

```
$ cargo run --release --quiet -- [--flag] [--parameter value]
```

Alternatively, if you have written a binary, you may run the binary according to the same rules.  Suppose the binary is named `myoptimizer`.

```
$ myoptimizer [--flag] [--parameter value]
```

### Command-Line Arguments

The following are permitted command-line arguments and values.  Note that all arguments are optional.

#### `--opt-help`

Prints a help menu.

#### `--quiet`

Does not print status updates.

#### `--no-stop-early`

Disables gradient-based convergence criterion.

#### `--print-every [integer]`

Number of iterations per status update.

Defaults to `0`.  This is the "quiet" option.  No status will be printed until the optimizer converges or the maximum iteration limit is reached.

Accepts an integer.  For example, if this integer is `5`, then the optimizer prints a status update every fifth iteration.

#### `--paradigm [string]`

Optimization paradigm.

Defaults to `steepest-descent`.

Accepts the following options.
- `steepest-descent`.  Steepest (gradient) descent.  It is recommended (but not required) to implement `Function::gradient` for this.
- `newton`.  Newton's method.  It is recommended (but not required) to implement `Function::gradient` and `Function::hessian` for this.
- `genetic`.  Genetic algorithm.
- `simulated-annealing`.  Simulated annealing.

#### `--criterion [float]`

Gradient-based convergence criterion.  When the gradient is less than this value, the optimizer halts.  Note that this requires a locally convex function.

Defaults to `1.0e-3`.

Accepts a floating-point number.

#### `--maxiter [integer]`

Maximum number of optimization iterations.

Defaults to `100`.

Accepts an integer.

#### `--maxtemp [float]`

Maximum temperature.  This is only used for the simulated annealing paradigm.

Defaults to `1.0`.

Accepts a floating-point number.

#### `--stdev [float]`

Standard deviation of mutations.  This is only used for stochastic methods (genetic optimization and simulated annealing).

Defaults to `1.0`.

Accepts a floating-point number.