mosox 0.4.3

# mosox

An LP matrix generator for GMPL (GNU MathProg).

Can be used in two ways:
- Generate an MPS file for solving elsewhere
- Solve directly with the [HiGHS](https://highs.dev/) integration, no other binary needed

**Currently a work-in-progress.**

It works for a subset of GMPL (specifically the subset required to run [Osemosys](https://osemosys.github.io/)).
The goal is to full coverage of GMPL and compatibility with GLPK, but this may take a while.
See [Known limitations](#known-limitations) section below.

## Quickstart

### Installation
#### Using Cargo
```bash
cargo install mosox
```

#### Using Homebrew (macOS)
```bash
brew tap carderne/mosox-tap
brew install mosox
```

#### Pre-built binaries (macOS, Windows, Linux)
Binaries are built for a small set of systems and architectures.
Available to download (compressed) from the [Releases page](https://github.com/carderne/mosox/releases).
Please choose the appropriate archive.

### Usage overview

Usage overview:
```bash
> mosox help

MathProg Translation Kit

Usage: mosox <COMMAND>

Commands:
  check     Check for errors and quit
  generate  Load and output to MPS
  solve      Solve with HiGHS
  normalize  Normalize an MPS file for diffing
  compare    Compare two normalized MPS files with epsilon tolerance
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
```

### Generate MPS
Generate MPS for one of the examples in this repo.
Output will be written to stdout.
```bash
mosox generate examples/basic/model.mod
```

Or an example with a separate data file, piping MPS to a file:
```bash
mosox generate examples/sets/model.mod examples/sets/data.dat > output.mps
```

### Solve a model
Results summary will be printed to stdout.
```bash
mosox solve examples/basic/model.mod

# output
OBJECTIVE VALUE
2200.000

CONSTRAINTS
labor = 100.000; marginal = 16.667
material = 80.000; marginal = 6.667

VARS
x1 = 40.000; marginal = -0.000
x2 = 20.000; marginal = -0.000
```



## Development
Please install [cargo-make](https://github.com/sagiegurari/cargo-make):
```bash
cargo install cargo-make
```

The most useful dev commands are listed in `Makefile.toml`.

You can view available commands by running `cargo make`.

### Formatting, linting
```bash
cargo make fmt
cargo make lint
```

### Testing
In addition to other tests, this will run mosox against all the examples under `examples/` and confirm that the output is identical to the existing MPS files.
```bash
cargo make test
```

This will additionally run a regression test against `examples/osemosys_large` if present.
```bash
cargo make testlarge
```

### Benchmarks
Run performance benchmarks across all examples (except `osemosys_large`):
```bash
cargo make bench
```

Include `osemosys_large` (requires the example to be present):
```bash
cargo make benchlarge
```

Run with `glpsol` comparison (requires `glpsol` on `PATH`):
```bash
cargo make benchglpsol
```

#### Performance vs glpsol (median, release build, Macbook Air M2)
Note that some of the performance advantage over glpsol may be caused by the limitations enumerated below.

| Example           | N   | glpsol | mosox   | Speedup |
|---------          |---  |--------|-------  |---------|
| basic             | 200 | 2.0ms  | 1.9ms   | 1.1x    |
| 2d_params         | 200 | 2.0ms  | 2.0ms   | 1.0x    |
| sets              | 200 | 2.1ms  | 1.9ms   | 1.1x    |
| osemosys_small    | 50  | 68.1ms | 17.0ms  | 4.0x    |
| osemosys_atlantis | 10  | 2.4s   | 372.5ms | 6.5x    |
| osemosys_large    | 4   | 130.3s | 20.0s   | 6.5x    |

## Known limitations
Hopefully this list is shorter then the "supported feature" list!

This list of limitations is made with reference to the GNU MathProg Language Reference which can be viewed [here](./docs/gmpl.pdf) or downloaded from the original [here](https://www.gnu.org/software/glpk).

It is intended that all of these will ultimately be supported, and most of them are "trivial" to add.

### Functions
Not yet implemented:
- The following functions: `abs`, `atan`, `card`, `ceil`, `cos`, `exp`, `floor`, `gmtime`, `length`, `log`, `prod`, `round`, `sin`, `sqrt`, `str2time`, `trunc`, `Irand224`, `Uniform`, `Normal`.

### Expressions
Not yet implemented:
- These arithmetic operators: `less` (positive difference operator), `div` (quotient), `mod`
- These symbolic operators: `&` (string concatenation)
- These set expressions: "arithmetic" set, conditional set expressions, parenthesized set expressions
- These set operators: `union`, `diff`, `symdiff`.
- These logical expressions: iterated expressions (`forall`, `exists`)
- These logical relational expressions: `in`, `not in`, `within`, `not within`
- These logical operators: `not`

### Sets
Not yet supported:
- Elements larger than two-tuple.
- `within` (parsed but not enforced)

### Parameters
Not yet supported:
- Alias
- Relational condition (parsed but not enforced)
- Superset expression (parsed but not enforced)
- Type specifier (integer, binary, symbolic) (parsed but not enforced)

### Variables
Not yet supported:
- Bounds specified as expressions (currently only constant accepted)

### Constraints
Not yet supported:
- Alias
- Multiple expressions (comma-separated)

### Objective function
Not yet supported:
- Alias

### Other statements
These are parsed but are otherwise ignored:
- Check statement
- Display statement
- Printf statement
- For statement