https://github.com/diantonioandrea/pacs-first

A gradient method for the minimization of a multivariate function.
https://github.com/diantonioandrea/pacs-first

Last synced: about 2 months ago
JSON representation

A gradient method for the minimization of a multivariate function.

• Host: GitHub
• URL: https://github.com/diantonioandrea/pacs-first
• Owner: diantonioandrea
• License: mit
• Created: 2024-03-08T15:39:37.000Z (10 months ago)
• Default Branch: main
• Last Pushed: 2024-04-17T09:27:21.000Z (8 months ago)
• Last Synced: 2024-04-17T11:27:41.532Z (8 months ago)
• Language: C++
• Homepage:
• Size: 341 KB
• Stars: 0
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Advanced Programming for Scientific Computing - First Challenge

_A Gradient Method for Multivariate Function Minimization_

## Table of Contents

- [Introduction](#introduction)

- [Overview](#overview)

- [Setup](#setup)

    - [Cloning the Repository](#cloning-the-repository)

    - [Compilation and Execution](#compilation-and-execution)

- [Usage](#usage)

    - [Parameters](#parameters)

    - [Options](#options)

    - [_MuParser_ Functions](#muparser-functions)

## Introduction

This repository offers an implementation of a gradient-based method designed for minimizing multivariate functions.

It introduces new classes and structures, including:

- `pacs::Vector`: Responsible for managing vectors in $\mathbb{R}^n$.

- `pacs::Target`: Manages the target function to be minimized along with its gradient. This can be provided as an input or evaluated numerically via finite differences.

- `pacs::Data`: Handles the output of the solver and facilitates communication with various routines and strategies.

- `pacs::Arguments` and `pacs::Parameters`: These classes manage command-line arguments and parameters. They utilize a custom and simple `argv` parser and the `nlohmann::json` class.

The implemented solver needs the following parameters for the target function minimization:

- Initial guess $x_0$

- Initial learning rate value $\alpha_0$

- Tolerances $\varepsilon_s$ and $\varepsilon_r$

- Maximum number of iterations

- An optional parser string for _MuParser_

- Strategy parameters $\mu$ and $\sigma$

Additionally, it requires two components:

1. A routine for evaluating the next point $x_{k + 1}$. (Defaults to the Newton routine).

2. A strategy for determining the learning rate value $\alpha_{k}$. (Defaults to the Fixed strategy).

Refer to [Options](#options) for the available routines and strategies.

## Overview

Key components include:

- `main.cpp`: Core script serving as a testing suite.

- `main.hpp`: Primary includes for `main.cpp`.

- `include/`:

    - `Solver.hpp`: Central solver method and associated routines/strategies.

    - `Arguments.hpp`: Methods for parsing command-line arguments.

    - `Parameters.hpp`: Methods for evaluating parameters from `parameters.json`.

    - `Vector.hpp`: Definition for the Vector class.

    - `Target.hpp`: Definition for the Target class, encapsulating the target function and its gradient or numerical evaluation.

    - `Default.hpp`: Definition of default target function and its gradient.

`src/` contains the implementations of the methods defined earlier.

## Setup

### Cloning the Repository

To begin, clone the repository from [here](https://github.com/diantonioandrea/pacs-first):

    git clone [email protected]:diantonioandrea/pacs-first.git

### Compilation and Execution

:warning: Ensure the `PACS_ROOT` variable is set to `/path/to/pacs-examples/Examples` and `LD_LIBRARY_PATH` includes `${PACS_ROOT}/lib` as required by _MuParser_.

Compile the code:

    make

Execute the code:

    ./main

For further details on options and parameters, refer to the [Usage](#usage) section.

Furthermore, the executable could potentially be accelerated by removing the comment from the following line in the [Makefile](./Makefile)[^1]:

[^1]: This ignores some safety checks for the `pacs::Vector` class.

```make

# CXXFLAGS += -O2 -DNDEBUG

```

## Usage

Below is a summary of parameters and command-line options for this challenge.

### Parameters

Parameters are specified in a [parameters.json](/parameters.json) file, parsed during execution.

Here are the [default](./defaults.json) values:

```json

{

    "guess": [0, 0],

    "alpha": 0.1,

    "step_tolerance": 1.0e-6,

    "residual_tolerance": 1.0e-6,

    "max_iterations": 10000,

    "parser": "x0 * x1 + 4 * x0 * x0 * x0 * x0 + x1 * x1 + 3 * x0",

    "strategy_mu": 0.2,

    "strategy_sigma": 0.25

}

```

### Options

The `./main` executable supports the following options:

- `-v/--verbose`: Enable verbosity.

- `-n/--numerical`: Consider numerical gradient for the target function.

- `-m/--muparser`: Parse `parser` parameter as the target function.

- `-h/--help`: Display usage help.

- `-p/--parameters (FILENAME)`: Specify parameters filename (default: `parameters.json`).

- `--r_(ROUTINE)`: Specify a routine, including:

    - `--r_newton` for **Newton**'s routine (default).

    - `--r_hb` for **Heavy-Ball** routine.

    - `--r_nesterov` for **Nesterov**'s routine.

- `--s_(STRATEGY)`: Specify a strategy, including:

    - `--s_fixed` for **Fixed** strategy (default).

    - `--s_exponential` for **Exponential Decay** strategy.

    - `--s_inverse` for **Inverse Decay** strategy.

    - `--s_armijo` for **Armijo** strategy.

### _MuParser_ Functions

Define functions' variables as `x` followed by its index, starting from zero. Example:

```json

"parser": "x0 + 2 * x1 - x2"

```

The number of variables in the _MuParser_ string **must** match the dimension of the `guess` vector.