PyInstaller bundles
PyInstaller is a popular tool in the Python ecosystem used to convert Python applications into standalone executables. It’s beneficial when you want to distribute your Python code as a single package, making it easier for users who might not have Python or the required dependencies installed.
We provide an easy way to use PyInstaller to bundle
optimization applications for distribution with
all dependencies including solvers. You can bundle your optimization application using
python -m amplpy.bundle script_name.py where script_name.py is the main Python script of your application for distribution. In the dist folder you will find the bundled app ready to distribute to your users. This works on Windows, Linux, and macOS.
In case amplpy.bundle is not available, please upgrade amplpy to the latest version with python -m pip install amplpy --upgrade.
Quick Example
Create and enable a new virtual environment.
$ python -m venv venv # Create a new virtual environment
$ source venv/bin/activate # On Linux and macOS
$ venvironment\Scripts\activate # On Windows
Note
The use of a clean virtual environment is important to reduce the dependencies
included in the bundled app.
Install any dependencies you may need on the new virtual environment.
$ python -m pip install -r requirements.txt
Install amplpy and the solver modules you need.
# Install Python API for AMPL
$ python -m pip install amplpy --upgrade
# Install solvers (e.g., HiGHS, Gurobi, COIN-OR)
$ python -m amplpy.modules install highs gurobi coin
Create your main python script.
For instance script_name.py:
from amplpy import AMPL
ampl = AMPL()
ampl.eval(r"""
param n integer > 0; # N-queens
var Row {1..n} integer >= 1 <= n;
s.t. row_attacks: alldiff ({j in 1..n} Row[j]);
s.t. diag_attacks: alldiff ({j in 1..n} Row[j]+j);
s.t. rdiag_attacks: alldiff ({j in 1..n} Row[j]-j);
""")
n = 10
ampl.param["n"] = n
ampl.solve(solver="highs")
solution = ampl.get_data("Row").to_dict()
queens = set((int(r) - 1, int(c) - 1) for c, r in solution.items())
print("Solution")
for r in range(n):
print("".join([" Q " if (r, c) in queens else " + " for c in range(n)]))
Install PyInstaller.
python -m pip install pyinstaller
On Windows, we encountered issues with the latest version, but version 5.1 worked.
You can install it with python -m pip install pyinstaller==5.1. On Linux and macOS,
the latest version worked without issues.
Bundle your application.
python -m amplpy.bundle script_name.py
...
Your executable is at ".../dist/script_name/script_name".
By default the license file will be excluded from the bundle. You can include
the license file with:
python -m amplpy.bundle script_name.py --keep-license
Test your executable.
$ dist/script_name/script_name
HiGHS 1.6.0: optimal solution
155 simplex iterations
1 branching nodes
Objective = find a feasible point.
Solution
Q + + + + + + + + +
+ + + + + + + Q + +
+ + + + + Q + + + +
+ Q + + + + + + + +
+ + + + + + Q + + +
+ + + + + + + + + Q
+ + + Q + + + + + +
+ + + + + + + + Q +
+ + + + Q + + + + +
+ + Q + + + + + + +
Distribute your bundled application.
Distribute the folder dist/script_name.
Licensing
In most situations you will not want to include your own AMPL license in the bundle
for distribution. There are two recommend ways of dealing with that:
a) Specify the location of the license file for instance in the user home directory:
Start your script with:
import os
from amplpy import AMPL
os.environ["AMPL_LICFILE"] = os.path.join(os.path.expanduser("~"), "ampl.lic")
...
The person using your bundled app will just need to have the ampl.lic file
in the home directory.
b) Use an environment variable to pass the license UUID to the application:
Start your script with:
import os
from amplpy import AMPL, modules
modules.activate(os.environ["AMPLKEY_UUID"])
...
The person using your bundled app will just need to set the environment variable
AMPLKEY_UUID with the license UUID to use.