.. lblGettingStarted:

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 <http://ampl.com/try-ampl/download-a-free-demo/>`_ or
`trial page <http://ampl.com/try-ampl/request-a-full-trial/>`_ to download a
working version that can be installed quickly.

Follow the instructions on our `AMPL API <http://ampl.com/products/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
------------

Open the MATLAB application window and set the path to
``amplapi/examples/matlab``. Enter the following to initialize the session
and then run an example:

.. code-block:: matlab

   setupOnce
   firstExample <solver> <modeldir>

where optionally ``<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) 
and ``<modeldir>`` is the location of the model files used in the examples. 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 by passing the path to :mat:meth:`AMPL` as follows:

.. code-block:: matlab

  ampl = AMPL('full path to the AMPL installation directory');

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

Development
-----------

Call the ``setUp`` function defined in ``amplapi/matlab/setUp.m`` from your
MATLAB code to add |ampl_jar| to the class path. 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
(``ampl`` or ``ampl.exe``) 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 MATLAB application the AMPL executable
(``ampl`` or ``ampl.exe``); the folders (directories) ``amplapi/lib`` and
``amplapi/matlab``; binaries needed to run any solvers that are used; and an
appropriate license file for AMPL and solvers.