View source for Using Python from Analytica

                                               [[category:Python integration]]
''New in [[Analytica 7.0]]''

Requires the [[Analytica Developer]] (formerly [[Analytica Enteprise]] edition.


== Introduction ==
Analytica's Python integration is the two-way bridge between Analytica and Python. An Analytica model can execute Python code, pass data—including multi-dimensional arrays—to it, and retrieve the results. Conversely, Python code can call back into Analytica to evaluate variables or expressions. Together the two environments combine Analytica’s intuitive influence-diagram interface, intelligent arrays, and built-in uncertainty analysis with Python’s vast open-source ecosystem.

''Theoretically'', the Python integration supports Python versions '''3.3+''', although it is recommended to use Python versions '''3.8+'''.

[https://videos.analytica.com/Analytica-Python/AnaPythonBasics.mp4 Watch video on Analytica-Python integration basics]

=== Motivation: Why use Python? ===
Python offers thousands of purpose-built libraries that extend what you can do in a model.

{| class="wikitable"
! Library !! What it adds when used from Analytica
|-
|[https://numpy.org/ NumPy], [https://pandas.pydata.org/ Pandas]|| Efficient numerical arrays and data-frame operations that underlie many other Python analytics libraries
|-
|[https://pillow.readthedocs.io/en/stable/ Pillow]|| Programmatic image manipulation for tasks such as satellite-image preprocessing before feeding data back into Analytica.
|-
|[https://matplotlib.org/ Matplotlib],  [https://seaborn.pydata.org/ Seaborn]|| Visualizations not native to Analytica, including violin plots, heatmaps, network graphs, and 3-D surface plots.
|-
|[https://pytorch.org/ PyTorch],  [https://www.tensorflow.org/ Tensorflow]|| Training or running machine-learning models, then passing predictions into Analytica for further probabilistic analysis.
|}

=== Advantages: When to use Python in Analytica ===
{| class="wikitable"
! Situation in Analytica !! Why using Python helps
|-
| Want custom visualizations beyond Analytica graphs || Generate plots with [https://matplotlib.org/ Matplotlib] or [https://seaborn.pydata.org/ Seaborn], save images, and display them in a Result window
|-
| Require advanced text or Natural-Language Processing || Apply Python packages like [https://spacy.io/ spaCy], [https://www.nltk.org/ NLTK], or built-in <code>re</code> for parsing, classification, and transformation
|-
| Need a specialized statistical, ML, or optimization algorithm not built into Analytica || Leverage PyPI libraries such as [https://scikit-learn.org/ scikit-learn], [https://pandas.pydata.org/ pandas], or [https://coin-or.github.io/pulp/ pulp] without re-implementing the math
|}

=== Downsides: When native Analytica is sometimes the better choice ===
{| class="wikitable"
! Concern !! Why pure Analytica can be preferable
|-
|[[Array Abstraction|Array abstraction]]|| Operating on arrays with different dimensions is a one-liner in Analytica but often requires verbose reshape/broadcast code in NumPy or Pandas.
|-
| Performance overhead || Transferring data and compiling Python incurs latency; tight loops or lightweight formulas run much faster as native Analytica expressions. For repeated Python calls, define a [[Callable]] to compile once and reuse.
|-
|[[Monte Carlo and probabilistic simulation|Monte Carlo]]|| Analytica’s built-in stochastic simulation is deeply integrated; recreating these in Python is rarely worth the effort.
|}

== Setting up a Python environment ==

=== Installing Conda ===
Download and run the Anaconda or Miniconda [https://www.anaconda.com/download/success installer] for Windows.

=== Creating and activating a Python environment ===
Open the newly installed '''Anaconda Prompt''' app and run this command, which will create a new Python 3.11 environment named <code>MyEnv</code> and install the Python libraries [https://pandas.pydata.org/ Pandas] and [https://numpy.org/ NumPy]:

<code>conda create -n MyEnv python=3.11 pandas numpy</code>  

=== Telling Analytica which Python environment to use ===
Open the '''Definition / Application integration / Python''' submenu.

Set either '''Python Environment''' or '''Python Model Environment''' to the environment’s name (e.g. <code>MyEnv</code>) or to the full folder path of the Python installation home directory, for example:

<code>C:\Users\username\anaconda3\envs\MyEnv</code>

'''Python Environment''' is stored with the Analytica installation and becomes the default for any model that does not set '''Python Model Environment'''.

'''Python Model Environment''' is saved inside the current model and overrides the installation-wide setting.

''See [[Using Python from Analytica/Setting up a Python environment|Setting up a Python environment]] for a detailed walkthrough.''

=== Loading and Unloading of Python ===

Python (core, environment, and libraries) loads only when your model first executes or evaluates Python code, and unloads when you close the model. Reopening the same model, or opening another that uses Python, starts a fresh Python session; any prior Python state (variables, imports) is lost. If the new model uses a different environment, it may run a different Python release.

If Python is already loaded and you change the '''Python Environment''' or '''Python Model Environment''', Python unloads immediately. The selected environment’s Python loads the next time your model runs Python code. Unloading discards all Python state (variables, imports).

Python runs in the same process as Analytica.

== The Python menu ==

The core Analytica functions and system variables for configuring and interacting with Python are found on the '''Definition / Application integration / Python''' submenu.

<center>[[image:Python menu.png]]</center>

== Importing Python libraries ==

The ''preferred'' way to make Python libraries available in Analytica models is to place their import statements in the system variable '''PythonStartupCode'''. These lines execute when Python gets loaded, so the libraries are ready for use in later Python code.

''If you edit '''PythonStartupCode''' after Python has already been loaded in the current Analytica model, you must reload the model (or close and reopen Analytica) for the modified startup code to take effect.''

=== Importing from nodes ===
When creating a filed Analytica library or module, it is ''highly recommended'' to perform imports within a [[Variable]] or [[Callable]] node inside the library/module itself. This practice ensures that the library/module remains self-contained, as '''PythonStartupCode''' is not saved as part of a filed module or library. You should then create dependencies from nodes that use the Python libraries to the import node(s) to ensure the Python libraries are loaded before use.

Python supports two main import styles:

* Module import – e.g., <code>import numpy</code>  
* Selective / wildcard import – e.g., <code>from numpy import array, zeros</code> or <code>from numpy import *</code>

When an import statement is the final expression, Analytica returns its value:

{| class="wikitable"
! Import statement
! Return value when it is the last statement
! Output image
|-
| <code>import numpy as np, os</code>
| The module’s string representation e.g.,<br/><code>«Python <module 'numpy' from …>»</code><br/><code>«Python <module 'os' from …>»</code>)
| [[Image:PythonMultipleModuleImports.png|thumb|250px]]
|-
| <code>from numpy import array, zeros</code>
| A list of the imported names (alias names if provided, otherwise the original names)
| [[Image:PythonMultipleSelectiveImports.png|thumb|250px]]
|}

== Python <code>py::</code> namespace   ==
Analytica exposes the embedded Python interpreter through the <code>py::</code> namespace prefix.  Any name visible at the top level of the interpreter—global variables, functions, classes, or imported modules—can be accessed through Analytica with the same spelling and case, preceded by <code>py::</code>.

Example: Incrementing a Python global variable '''counter''' by 2

<code>py::counter := py::counter + 2;</code>

== Calling a Python function ==
Invoking a Python function from Analytica is as simple as writing it:

<code>py::len(MyArray)</code>

Arguments may be:
* Analytica scalars
* Analytica arrays (which get [[Array Abstraction|array abstracted]])
* Python objects

=== Keyword arguments (kwargs) ===
When a Python function accepts keyword arguments (<code>**kwargs</code>), use a syntax ''similar'' to Analytica’s [[Function calls and parameters#Name-based function calls|name-based function calls]], a colon after the parameter name, followed by the parameter value, instead of the equal sign used in Python.

<code>py::my_func("arg1", kwarg1:1, kwarg2:"abc")</code>

The equivalent call in native Python is:

<code>my_func("arg1", kwarg1=1, kwarg2="abc")</code>

=== Python <code>print()</code> function  ===
The standard Python <code>print()</code> function sends its text output to Analytica's [[Typescript|Typescript console]] window, just as it appears in a native Python console.  
* When called from Analytica with <code>py::print()</code>, the printed text will appear in the window.  
* When called inside a Python script executed by Analytica, any <code>print()</code> statements also stream to the window.

== Using Python classes ==
=== Using an existing Python class ===
To instantiate a Python class, call its constructor with the <code>py::</code> prefix and pass any arguments exactly as you would in native Python.

<code>py::MyClass(42, 'widgets')</code>

=== Arrow operator (<code>-></code>)  ===
The arrow operator (<code>-></code>) lets you access the attributes and methods of a Python object, analogous to the dot operator (<code>.</code>) in Python:

:<code>ColNames := MyDf->columns      { attribute }</code>
:<code>Head5    := MyDf->head(5)      { method }</code>

You can chain these accesses and calls:

<code>FirstName := MyDf->columns->tolist()</code>

You can also assign through the arrow operator; the assignment will update the underlying Python object:

<code>MyObj->value := 42</code>

== Using Python code in a definition ==
When you choose '''Python expr''' from the [[Definition]] drop-down, the entire definition is passed verbatim to the embedded Python interpreter.

=== Defining a UDF with a Python expr definition ===
When you set a Function node’s [[Definition]] to '''Python expr''', you can write the entire body in Python. Analytica recompiles that code every time the function is evaluated, which can noticeably slow large array computations. To eliminate this overhead, place the code in a reusable Python [[Callable]] so the compiled version remains cached between calls.

''Inside '''Python expr''', Analytica function parameters behave like local Python variables.''

== Callables ==

[[Callable|Callables]] let you embed full Python functions or classes directly inside Analytica, then invoke them like any other [[User-Defined Functions|UDF]].

=== Creating a Python Callable node ===
* Create a new [[Variable]] node.
* In the node’s [[Object Window|Object window]], change the [[Class details|Class]] dropdown from '''Variable''' to '''Callable'''.
* Enter your Python code in the Definition pane.

=== Writing Python Callable code ===
Use standard Python syntax to define a <code>def</code> function or a <code>class</code> inside the [[Definition]] pane of your '''Callable'''. For example:

<pre>
def compound_interest(p, r, n):
    return p * (1 + r) ** n
</pre>

=== Caching compiled functions in Callables ===
When you evaluate a node, Analytica compiles your function and caches the resulting callable object as the node’s value. This differs from [[UDF|UDFs]] which cannot store a value, so they compile every time they run.

=== Parameters attribute ===
'''Callables''' do '''not''' have a Parameters attribute; all arguments are declared in your <code>def</code> or <code>class</code> signature.

=== Importing custom Python modules ===
Import modules exactly as you would in native Python. For example:

<pre>
import myutils
from mylib.finance import NPV
</pre>

Ensure the module is on Python’s <code>sys.path</code> by appending the module's directory to the path. For additional guidance, see the official [https://docs.python.org/3/tutorial/modules.html Python documentation on modules].

== Dependencies ==
Analytica's automatic dependency graph is a key advantage over working in environments like Jupyter notebooks or regular Python scripts, where you are responsible for manually re-running cells or scripts to reflect changes.

When integrating Python code, however, Analytica's dependency system cannot parse the Python script to automatically detect when an Analytica node is being used. You must explicitly declare these dependencies by drawing influence arrows. Drawing an influence arrow from any node to a node that uses '''Python Expr''' creates a true dependency, adding it to Analytica's dependency graph.

''As an alternative for nodes that access Python global variables without using '''Python Expr''', you can establish a dependency by including the Identifier of the influencing node directly within the Definition of the dependent node.''

If dependencies for Python nodes are not manually defined with arrows, your model will not invalidate results correctly. Updates to an input variable will not trigger re-computation in the Python node that depends on it, leaving it with a stale, incorrect value.

== Functions for evaluating Python code ==

=== PyEval ===
[[PyEval]] is used to evaluate a single Python expression and return its value to Analytica. It is designed to be side-effect-free, meaning it won't change the state of variables or objects in Python. This makes it ideal for safe, simple calculations.

''Since <code>PyEval</code> only evaluates a single expression, it cannot execute multi-line code or statements like variable assignments or imports.''

It also includes an optional <code>excludeTypes</code> parameter, which allows you to specify Python types that should not be converted to Analytica Values.

=== PyExec ===
[[PyExec]] is used to execute a block of Python code, which can contain multiple lines or statements. Unlike <code>PyEval</code>, <code>PyExec</code> is intended to have side effects. You can use it to import libraries, define functions, or set the values of variables in the Python environment.

Use <code>PyExec</code> when you need to run a script to set up an environment or perform operations that modify the Python state for use in later evaluations.

=== PyCall ===
[[PyCall]] offers a direct and efficient way to call a specific Python function. You provide the callable Python function object followed by its positional and keyword arguments.

This is the preferred function when your primary goal is to execute an existing Python function and retrieve its result.

== Non-scalar data structures ==
Any Python object that is not converted automatically to an Analytica type comes back as an ''opaque wrapper'' displayed as <code>«Python …»</code>, where the ellipsis is the object’s [https://docs.python.org/3/library/functions.html#repr repr]. Keep this wrapper when the object merely passes between Python calls, and invoke [[PyExplode]] when the data must be examined or manipulated within Analytica.

=== Converting from Python data to Analytica ===
When a Python function invoked from Analytica returns a result, Analytica automatically attempts to convert the Python data into the most appropriate Analytica value. For complex data structures, the dedicated [[PyExplode]] function is available to perform more specific conversions.

==== Automatic conversions ====
The following Python types are automatically converted to their corresponding Analytica equivalents without any extra steps:
{| class="wikitable"
! Python type !! Analytica type !! Notes
|-
| <code>int</code> || <code>Integer</code> ||''If the <code>int</code> exceeds the 64-bit signed-integer range, Analytica converts it to a double floating-point '''Number''' instead of an '''Integer'''.''
|-
| <code>float</code> || <code>Number</code> || 
|-
| <code>bool</code> || <code>Boolean</code> || 
|-
| <code>complex</code> || <code>ComplexNumber</code> || 
|-
| <code>str</code> || <code>Text</code> || 
|-
| <code>None</code> || <code>Null</code> || 
|-
| <code>date</code> || <code>DateTime</code> || 
|-
| <code>time</code> || <code>DateTime</code> || 
|-
| <code>datetime</code> || <code>DateTime</code> || 
|-
| <code>analytica.Value</code> || Unwrapped Analytica value || 
|-
| Any other Python object || ''Python opaque wrapper'' ||''Can be passed to other Python function calls or converted with <code>PyExplode</code>.''
|}

==== PyExplode ====
The [[PyExplode]] function provides explicit control for converting complex Python objects that are not converted automatically.

Key capabilities include:
* Unpacking Python built-in collections, like <code>list</code>, <code>tuple</code>, <code>set</code>, into a 1D Analytica array.
* Converting a Python <code>dict</code> into a 1D Analytica array, using the dictionary keys to create a new local index.
* Using nested calls to convert multi-dimensional data into multi-dimensional Analytica arrays.
* Fully converting a [https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html NumPy Array] into an n-dimensional Analytica array.
* Converting image objects from [https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image PIL.Image] or [https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html matplotlib.figure.Figure] directly into Analytica images.
* Optionally excluding specific Python types from conversion with <code>excludeTypes</code>, which keeps them as opaque Python object handles.

''To convert a [https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html Pandas DataFrame], you must use the <code>PyExplodeDataFrame</code> function. This function is not built-in and requires you to include the [[Python Pandas library]] in your model.''

=== Converting from Analytica to Python data structures ===
The bridge between Analytica and Python performs two kinds of mappings: ''automatic scalar conversions'' and ''explicit conversion functions'' for arrays.

==== Automatic scalar conversions ====
{| class="wikitable"
! Analytica type !! Python type
|-
| <code>Text</code> ||<code>str</code>
|-
| <code>Integer</code> ||<code>int</code>
|-
| <code>Number</code> ||<code>float</code>
|-
| <code>Boolean</code> ||<code>bool</code>
|-
| <code>ComplexNumber</code> ||<code>complex</code>
|-
| <code>DateTime</code> ||<code>datetime.datetime</code> / <code>datetime.time</code> / <code>datetime.date</code>
|-
| <code>Handle</code> ||<code>analytica.Object</code>
|-
| <code>Null / Undefined</code> ||<code>None</code>
|-
| ''Python opaque wrapper'' || unwrapped Python object
|-
| <code>Reference</code> ||<code>set</code>of the dereferenced contents
|-
| <code>Image</code> ||<code>PIL.Image.Image</code>
|-
| Everything else ||<code>analytica.Value</code> (wrapper for Analytica Values)
|}

==== Explicit conversion functions for arrays ====
Analytica has a single collection type—the array—whereas Python offers several (<code>list</code>, <code>tuple</code>, <code>dict</code>, <code>set</code>, <code>numpy.ndarray</code>, …). Because there is no one-to-one mapping, arrays are ''not'' converted implicitly; instead call one of the system functions below.

''<code>PyList</code>'', ''<code>PyTuple</code>'', ''<code>PySet</code>'', ''<code>PyDict</code> create a Python collection over the single dimension that you specify. In contrast, <code>PyArray</code> converts an entire Analytica array into a single <code>numpy.ndarray</code>.''

*[[PyList]] – Creates a Python <code>list</code> from the specified index, retaining other dimensions in Analytica.
* [[PyTuple]] – Creates a Python <code>tuple</code> from the chosen index of the array, retaining other dimensions in Analytica.
* [[PySet]] – Creates a Python <code>set</code> from the specified index, duplicate entries will be removed.
* [[PyDict]] – Creates a Python <code>dict</code> from an Analytica vector. The elements of a specified index are used as keys and the corresponding vector values become the dictionary values. The input vector must be indexed by the key index.
* [[PyArray]] – Converts an entire Analytica array into a single multi-dimensional <code>numpy.ndarray</code>. This function always converts all dimensions. The optional index parameters are used to specify the order of the axes in the resulting NumPy array. For any Analytica dimension not explicitly passed as a parameter, a local, positional index is created for that axis in the NumPy array. An optional <code>dtype</code> string passes directly to NumPy.

== Using Analytica locals from Python code ==

Analytica locals are visible by default to [[PyEval]] and [[PyExec]] when called within the same definition that introduces them (e.g., a definition using [[Local_Values|Local]] or a [[User-Defined_Functions|Function]] with parameters). To change visibility, pass explicit Python <code>globals</code> and <code>locals</code> mappings; providing an empty <code>locals</code> isolates the Python code from Analytica locals.

'''Example:''' <code>Local a := 5; PyEval("a + 1")</code> returns 6 because <code>a</code> is visible to the Python expression in that evaluation.

== Accessing Analytica objects from Python code ==
To interact with your Analytica model from Python, use the <code>analytica</code> module. This module is bundled with your Analytica installation and provides the necessary functions to access, evaluate, and manipulate objects within your model directly from Python.

To begin, you must [[#Importing Python libraries|import the module]] in your Python code:
<code>import analytica</code>

=== Getting a handle to an Analytica object ===
You can obtain a handle to any object in your model using<code>analytica.get('object_identifier')</code> in Python. This is useful when you want to refer to an object itself rather than its computed value. The function takes the identifier of the Analytica object as its argument and returns an <code>analytica.Object</code>.

''Example:''
To get a handle to a variable named <code>Revenue</code>, you would use:
<code>revenue_handle = analytica.get('Revenue')</code>

This assigns an <code>analytica.Object</code> representing the <code>Revenue</code> Analytica variable to the <code>revenue_handle</code> Python variable.

=== Evaluating an Analytica expression ===
To evaluate an Analytica expression, use <code>analytica.eval('Analytica_expression')</code>. This function processes its string argument as an Analytica expression within the context of your model.

<code>analytica.eval()</code> is the primary method for retrieving the calculated value of a variable. When it returns a value, it will [[#Converting from Analytica to Python data structures|implicitly convert]] many Analytica data types into their Python equivalents.

''Example:''
To get the computed value of the <code>Revenue</code> variable, you would evaluate its identifier:
<code>revenue_result = analytica.eval('Revenue')</code>

This executes the expression for <code>Revenue</code> and stores its final value in the <code>revenue_result</code> Python variable.

== Using Python in ACP or ADE ==

== See also ==
* [[Using Python from Analytica/Setting up a Python environment|Setting up a Python environment]]
* [[Using Python from Analytica/Examples using Python|Examples using Python]]
* [https://videos.analytica.com/Analytica-Python/AnaPythonBasics.mp4 Video on Analytica-Python integration basics]