Initial Setup#

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.

There are two main ways of installing the API:

  1. Using the NuGet packages (reccomended)

  2. Using the distributed assembly and libraries

Create a new project using NuGet (reccomended)#

Visual Studio (Windows)#

  • Create a new project using any .NET framework

  • Right click on the project icon and click Manage NuGet Packages

  • Search for AMPL.Api

VS Code or command line#

  • Make sure you have .NET 6.0+ installed

  • Create the project executing dotnet new console

  • Add the AMPL API package executing dotnet add package AMPL.Api

Use the distributed assembly#

  • Reference the appropriate assembly in bin/dotnet/framework

  • Make sure all the files in bin are copied where the target will be executed

Running the examples#

AMPL API is distributed as one .NET assembly and a native library. They must be both accessible for the API to work. A valid Mono .NET or .NET framework configuration is needed to use the .NET AMPL API; some examples are provided for the user to familiarize with the API; for users of Visual Studio, some ready-to-use solution files are provided, whilst users of Mono .NET must follow the instructions or build their own assemblies taking care to reference the assembly provided.

Visual Studio#

Open the solution file at amplapi/examples/csharp/csharp-examples.sln. Visual Studio 2017 or above are required to open the solution files. The solution file contains all the examples as separate projects. Note that depending on the architecture of the AMPL API in use (32 bits or 64 bits), the appropriate solution platform should be selected, this is easily achieved using the dropdown in the figure below:

Visual studio configuration

Command line with dotnet#

Change the current directory to amplapi/examples/csharp and then:

Windows#

dotnet new console -n FirstExample
copy FirstExample.cs FirstExample\Program.cs
cd FirstExample
dotnet add package AMPL.Api
set solver=highs
dotnet run

Linux / macOS#

dotnet new console -n FirstExample
cp FirstExample.cs FirstExample/Program.cs
cd FirstExample
dotnet add package AMPL.Api
export solver=highs
dotnet run

Mono#

Windows#

Note that the csharp examples look for model files in ..\..\models, hence they should be compiled in a subdirectory of the path containing them, which must be created. Moreover, they expect AMPL.Api.dll to be accessible. So, for example:

  • Change the current directory to amplapi\examples\csharp

  • Create a directory

  • Change current directory to the directory created above

  • Copy the required assembliy to this directory:

    • The assembly bin\dotnet\netstandard2.0\AMPL.API.dll

  • Either:

    1. Copy the required libraries to the directory above:

      • The mono/native interface bin\dotnet\ampl-dotnet-native.dll

      • The C++ AMPLAPI library bin\ampl-2.3.13.dll

    2. Add the bin and bin\dotnet directories of the AMPL API distribution to the system path

  • Compile any of the example files taking care of referencing the API assembly.

  • The procedure above is implemented by the script below:

md bin
cd bin
copy ..\..\..\bin\dotnet\*.dll .
copy ..\..\..\bin\ampl-2.*.dll .
copy ..\..\..\bin\dotnet\netstandard2.0\* .
mcs /t:exe /out:firstexample /platform:anycpu /sdk:4 /reference:System.dll /reference:AMPL.Api.dll ../FirstExample.cs

To complete an initial test, build FirstExample.cs using the script above and then invoke it with:

mono firstexample <modeldir> <solver>

where optionally <modeldir> is the location of the model files used in the examples and <solver> is the name of a solver that has been installed with AMPL (if a solver is not specified, then AMPL 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 as follows:

ampl.Environment env = new ampl.Environment("full path to the AMPL installation directory");
ampl.AMPL a = new ampl.AMPL(env);

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

Linux / macOS#

Note that the csharp examples look for model files in ../../models, hence they should be compiled in a subdirectory of the path containing them, which must be created. Moreover, they expect AMPL.Api.dll to be accessible. So, for example:

  • Change the current directory to amplapi/examples/csharp

  • Create a directory

  • Change current directory to the directory created above

  • Copy the mono assembly bin/dotnet/ampl-dotnet-native.dll to this directory.

  • Adjust the environment variable LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH for macOS) to look for the dynamic libraries in the correct directory

  • Compile any of the example files taking care of referencing the API assembly

  • The procedure above is implemented by the script below:

    mkdir bin
cd bin
cp ../../../bin/dotnet/libampl-dotnet-native.* .
cp ../../../bin/dotnet/netstandard2.0/* .
export LD_LIBRARY_PATH=$PWD/../../../lib:$LD_LIBRARY_PATH # for Linux
export DYLD_LIBRARY_PATH=$PWD/../../../lib:$DYLD_LIBRARY_PATH # for macOS
mcs /t:exe /out:firstexample /platform:anycpu /sdk:4 /reference:System.dll /reference:./AMPL.Api.dll ../FirstExample.cs

To complete an initial test, build FirstExample.cs using the script above and then invoke it with:

mono firstexample <modeldir> <solver>

where optionally <modeldir> is the location of the model files used in the examples and <solver> is the name of a solver that has been installed with AMPL (if a solver is not specified, then AMPL 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. If some libraries are not found, see the note on LD_LIBRARY_PATH in the next section.

Development#

Reference the assembly bin/dotnet/<framework>/AMPL.Api.dll in your C# project. The binary files that must be accessible are platform dependent and listed below, using the main amplapi directory as root:

  • Windows:

    • bin\dotnet\<framework>\AMPL.Api.dll

    • bin\dotnet\ampl-dotnet-native.dll

    • bin\ampl-2.3.13.dll

  • Linux/Unix:

    • bin/dotnet/<framework>/AMPL.Api.dll

    • bin/dotnet/libampl-dotnet-native.so on Linux o bin/dotnet/libampl-dotnet-native.dylib on macOS

    • lib/libampl.so.2.3.13 on Linux or lib/libampl.2.3.13.dylib on macOS

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. In Unix/Linux environments, note that the environment variable LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH for macOS) may need to be set appropriately. To search for the libraries in the current directory, on Linux execute export LD_LIBRARY_PATH=$PWD:$LD_LIBRARY_PATH, on macOS execute export DYLD_LIBRARY_PATH=$PWD:$DYLD_LIBRARY_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 additional files listed in the previous section, the binaries needed to run any solvers that are used and an appropriate license file for AMPL and solvers.