The PYTHON_RUN statement is used as an interface to Python. The interface allows easy transfer of matrices from Gekko to Python, execution of a Python program, and easy returning of matrices from Python to Gekko. Instead of matrices, you may alternatively use parquet files to communicate with Python. To use Gekko completely from the inside of Python, you may use the Python package PyGekko.

When executing PYTHON_RUN, you need Python on your system, and Gekko will attempt to auto-detect the location of Python (trying to locate it from the Windows PATH). If this fails, you may indicate the location via option python exe folder = ... ;. If you just need to export matrices for use in Python (without returning to Gekko), try the EXPORT<python> statement. Regarding an equivalent interface to R, see R_RUN.

Syntax

python_run <MUTE TARGET=...> matrix1, matrix2, ... FILE = filename ;

python_run <MUTE TARGET=...> filename ;

MUTE	(Optional). With this option set, Python is run silently in Gekko. Alternatively, Python output is shown in the Gekko main window. Do not used <mute> when debugging your Python program, since it shows potential Python error messages.
TARGET =	(Optional string). If for instance <target = 'data1' >, the matrices are inserted at the exact location in the Python file, where there is a line starting with gekkoimport data1. If the option is not given, the matrices are inserted at the top of the Python file (this is often sufficient, the target logic is intended for larger Python programs)
filename	Filenames may contain an absolute path like c:\projects\gekko\bank.gbk, or a relative path \gekko\bank.gbk. Filenames containing blanks and special characters should be put inside quotes. Regarding reading of files, files in libraries can be referred to with colon (for instance lib1:bank.gbk), and "zip paths" are allowed too (for instance c:\projects\data.zip\bank.gbk). See more on filenames here.

Example syntax:

python_run <target = 'data1'> #x, #y file = ols.py;

Example

The example below estimates (in Python) a linear least squares model with five parameters. You may consult the OLS section to see the same parameters calculated via the OLS solver, or the MATRIX section to see the same parameters calculated via linear algebra. See also the R interface.

First, put the following Python file ols.py into your working folder:

gekkoimport data1   # Gekko data is inserted here
import statsmodels.api as sm # OLS functionality
x = sm.add_constant(x)   # constant term (ones column)
model = sm.OLS(y, x)   # define the model
results = model.fit()     # fit the model
print(results.summary())   # print results
beta = results.params   # estimated parameters
yfit = results.predict()   # predicted values for y
gekkoexport(beta)     # writes beta vector back to Gekko
gekkoexport(yfit)     # writes fitted values back to Gekko

# ---------- example of plotting via Python ----------
import matplotlib
import matplotlib.pyplot as plt
import numpy as np
t = np.arange(2000, 2011, 1)
fig, ax = plt.subplots()
ax.plot(t, y, label='s0')
ax.plot(t, yfit, label='s0fit')
ax.set(title='Python plot')
ax.grid()
plt.legend()
plt.show()

Next, you can run the following program in Gekko:

reset; cls;
lna1 <1998 2010> = data('166.223000 173.221000 179.571000 187.343000 194.888000 202.959000
  209.426000 215.134000 222.716000 230.520000 238.518000 246.654000 254.991000') ;
pcp <1998 2010> = data('0.9502030 0.9699920 1.0000000 1.0235000 1.0401100 1.0605400
  1.0754700 1.0977800 1.1121200 1.1314800 1.1513000 1.1717600 1.1871600') ;
bul1 <1998 2010> = data('0.0684791 0.0591698 0.0560344 0.0535439 0.0535003 0.0631703
  0.0649875 0.0578112 0.0473207 0.0404508 0.0467488 0.0472923 0.0475191') ;
%t1 = 2000;
%t2 = 2010;
time %t1 %t2;
s0 = dlog(lna1);
s1 = dlog(pcp);
s2 = dlog(pcp.1);
s3 = bul1;
s4 = bul1.1;
#x = pack(%t1, %t2, s1, s2, s3, s4); //matrix
#y = pack(%t1, %t2, s0); //matrix
python_run <target = 'data1'>  #x, #y file = ols.py; //returns matrices #beta and #yfit from Python
prt #beta;
s0fit = #yfit[.., 1].unpack(%t1, %t2);
plot s0, s0fit;

The program prints Python output on the screen, and plots actual and predicted values. Plotting is done using both Python's Matplotlib, and Gekko's own PLOT (the Python plot is shown below).

clip0040

The #beta vector looks like this:

#beta
   1
   1 0.0298
   2 0.1445
   3 0.6139
   4 0.1867
   5 -0.3509

Some of the output from Python shown in Gekko is the following (cf. the same example in the OLS section):

==============================================================================

coef std err t P>|t| [0.025 0.975]

------------------------------------------------------------------------------

const 0.0298 0.009 3.333 0.016 0.008 0.052

x1 0.1445 0.227 0.637 0.548 -0.411 0.700

x2 0.6139 0.236 2.596 0.041 0.035 1.193

x3 0.1867 0.203 0.922 0.392 -0.309 0.682

x4 -0.3509 0.203 -1.727 0.135 -0.848 0.146

==============================================================================

Omnibus: 1.122 Durbin-Watson: 1.865

Prob(Omnibus): 0.571 Jarque-Bera (JB): 0.895

Skew: 0.544 Prob(JB): 0.639

Kurtosis: 2.122 Cond. No. 253.

==============================================================================

Note that in this example, the <target= 'data1'> option and the corresponding gekkoimport data1 in the ols.py file are not really necessary, since the data could just be put at the top of the Python file anyway. The code that is injected into the Python file before it is executed looks like the following:

x = numpy.array([[0.0304674549413991,0.0206121780628441, ...], ...])
y = numpy.array([[0.0360024370055795],[0.0423704884205201], ... ])

And the file that Python produces for Gekko to consume looks like the following (this is actually what the gekkoexport() function in Python does):

Python2Gekko version 1.0

------------------------

name = beta

rows = 5

cols = 1

0.0298038917827622

0.1445172984105897

0.6138751350035226

0.18674011629660836

-0.35090825010498294

-------------------

...

This text-based way of interchanging data back and forth works fine, as long as the datasets are not too voluminous (otherwise see the following section). The interface is more stable than COM-based automation, and interchange of values, text, etc. could also be provided if needed.

Parquet files

You may use parquet files as a data interface regarding Python (and R and SQL etc.). The Gekko parquet interface supports metadata, and can both read and write parquet files. See this appendix.

Note

Note that with python_run<mute>, you will not see any potential Python errors on the screen. So please do not use <mute> when you are still debugging the Python program.

Note that at the moment, the gekkoexport() function only takes one argument/matrix at the time. The gekkoexport() function will work with simple names, else you must indicate the name as a string, for instance gekkoexport(results.params, 'beta').

You need to have Python installed on your computer. Gekko will try to auto-detect the location of Python from the Windows PATH, otherwise you may indicate the path via this option: option python exe folder = ... ; (Gekko will automatically add python.exe or \python.exe, unless the path ends with .exe, .bat or .cmd). To locate your python.exe file location, you may try this in Python: import sys; print(sys.executable) (this works for Python 3, for Python 2 you must omit the parentheses).

You can also use EXPORT<python> to export matrices to a file suitable for Python.

Related options

option python exe folder = '';

Related statements

EXPORT, MATRIX, R_RUN