# Getting started¶

## Installation¶

The AMPL API can function as an add-on to any existing AMPL installation. If you do not yet have an AMPL installation on the computer where you will be working with the API, see our demo page or trial page to download a working version that can be installed quickly.

Follow the instructions on our AMPL API page to download the API package appropriate to your platform, and to add the downloaded folder (directory) amplapi to your AMPL installation.

## Initial test¶

AMPL API includes a CMake script that can be used to build C++ examples on a wide range of platforms. To begin, download and install the free CMake utility. Open a command/terminal window, make amplapi/examples/cpp the current folder (directory), and invoke

cmake .


to generate native makefiles or project files that can be used in the compiler environment of your choice.

• Under Linux or any Unix-like environment, you will see a Makefile in the current directory; you can then build examples by running make.

• Under Windows with Visual Studio installed, the EXAMPLES.sln file and several project files will be created. You can then build examples using Visual Studio or MSBuild. Note that to compile the examples in 64 bits with Visual Studio, the command line above must be amended to something like the following:

cmake -G "Visual Studio 14 2015 Win64" .


where the version and year number can differ depending on the target version of Visual Studio. See cmake --help for a list of valid generators.

• Under Mac OS X with Xcode installed, an .xcodeproj file will be generated and can be used to build the examples.

To complete an initial test, build firstexample using these generated files, and then invoke it with

./firstexample <solver>


where optionally <solver> is the name of a solver that has been installed with AMPL. (If a solver is not specified, AMPL’s default choice will be used.) This will solve several small diet problems and then display the optimal amounts of the foods from the last solution.

Note that the folder containing the AMPL executable should be in the system search path. Otherwise, the error message “AMPL could not be started” will be shown. If the AMPL installation directory is not in the system search path, you can add it passing a new ampl::Environment to ampl::AMPL as follows:

ampl::Environment env("full path to the AMPL installation directory");
ampl::AMPL ampl(env);


Note that you may need to escape backslashes (e.g., “C:\\ampl\\ampl.mswin64”) if included in the path.

## Development¶

Include the ampl/ampl.h header from the amplapi/include folder (directory) in your C++ code and link binaries with the AMPL library (libampl.so on Linux, libampl.dylib on OS X, ampl-2.0.4.0.lib on Windows) from amplapi/lib to use the AMPL API. Together with your existing AMPL implementation, this will provide the full object library and access to all AMPL functions.

The amplapi folder (directory) can be moved to a different location in your computer’s filesystem, provided that the location of your AMPL executable has been placed in the system search path.

## Deployment¶

To deploy AMPL API applications to users who do not have their own AMPL installations, include with your C++ application the AMPL executable (ampl or ampl.exe); the shared library (lib/libampl.so.2.0.4.0 on Linux, lib/libampl.2.0.4.0.dylib on OS X, bin/ampl-2.0.4.0.dll on Windows) which contains the full implementation of the C++ object library; binaries needed to run any solvers that are used; and an appropriate license file for AMPL and solvers.