|
Python interface: Installation |
|
|
Python interface: Installation |
This page first describes a number of options for installation of Python and the Python interface to OrcaFlex. We then consider some of the issues that may be encountered during set up.
The second part of this page presents some details of how the interface is accessed, both by the user, and also by OrcaFlex, and again some solutions to typical problems are noted here.
To use the Python interface to OrcaFlex you need to install:
The Python interface to OrcaFlex requires Python version 3.6 to 3.12 inclusive, although earlier versions of OrcaFlex support older versions of Python as documented below.
| OrcaFlex version | Latest Python version detected |
|---|---|
| 11.4a | Python 3.12 |
| 11.3g | Python 3.12 |
| 11.2e | Python 2.7, 3.11 |
| 11.1e | Python 2.7, 3.10 |
| 11.0g | Python 2.7, 3.9 |
| 10.3e | Python 2.7, 3.8 |
| 10.2d | Python 2.7, 3.7 |
| 10.1c | Python 2.7, 3.6 |
| 10.0a | Python 2.7, 3.5 |
Although 32 and 64 bit versions of Python are supported we would recommend using the 64 bit version.
In the following we talk about embedded Python and non-embedded Python. By embedded Python, we mean Python code that is called by OrcaFlex (or by the OrcFxAPI DLL), e.g. Python external functions, post calculation actions, user defined results and curvilinear constraints. Non-embedded Python is the reverse scenario where the Python executable is the main process, and it uses the OrcFxAPI module to call OrcaFlex code in the OrcFxAPI DLL. Pre-processing and post-processing are the primary examples of non-embedded usage.
Starting with version 11.3, the OrcaFlex installation program can install an embedded Python distribution. This distribution is based on the embedded package available at python.org with a small number of critical third-party modules included: pip, NumPy, SymPy, PyYAML and OrcFxAPI.
If you choose to install this embedded Python distribution whilst installing OrcaFlex, then this Python distribution will be used by OrcaFlex as its preferred embedded Python. This allows you to use Python external functions, post calculation actions, user defined results and curvilinear constraints without having to install a Python distribution separately.
Because the pip module is included it is possible to install modules from PyPI to this distribution. The OrcaFlex installer adds a start menu shortcut to open a command prompt for this embedded Python distribution. You can call pip from this command prompt to install other modules. For example:
pip install pandas
Although this Python distribution is intended for use as an embedded Python, it is possible to use it in a non-embedded manner. The start menu shortcut to open a command prompt is one way to do this. Another way would be to modify the Windows path to include the installed location of the embedded Python distribution. This is installed under %AllUsersProfile%\Orcina\OrcaFlex\<ver>\EmbeddedPython, where %AllUsersProfile% typically expands to C:\ProgramData, <ver> is the version, e.g. 11.3.
For example, assuming you had installed version 11.3, you would add these directories to the path:
However, whilst this is possible, it may not be the best option for non-embedded usage. The embedded Python distribution is quite limited in scope, third-party modules can be tricky to install, and so for non-embedded usage it may be more practical to use a dedicated third-party installation of Python.
Python can be downloaded from http://www.python.org/download/ and is simple to install (full details are given with the downloads).
| Warning: | There is a bug in Python, introduced in version 3.8.0 (32 bit only), which results in Python crashing when using dynamicsProgressHandler or SolveEquation. |
For tutorials on Python, see http://docs.python.org/. We also recommend the book Learning Python by Mark Lutz.
Python has a comprehensive set of supporting libraries, including NumPy and SciPy, which provide some useful functions for scientific computing, see http://numpy.org/ for more details. NumPy is required in order to use the Python interface.
We recommend using the standard installation of Python from http://www.python.org/download/ as OrcaFlex's Python support is developed against this. Unfortunately, this distribution does not include some useful third party modules such as NumPy and SciPy. Many Python modules are available from the Python package repository, PyPI and can be downloaded from here. An easier alternative is to use the pip package installer which is included in most Python releases. This automates the process of downloading and installing packages from the repository. To install the yaml and numpy modules, for instance, you run pip from a Windows console (this requires that Python is on your Windows path):
The PyPI repository does not always have packages for the latest release of Python, or for all 64 bit Python versions. If you cannot find the package you want here for your Python version then try Christoph Gohlke's page which is likely to have the version you need. This site offers the downloads as Python wheels (.whl) which is the format used for Python packages by the pip package manager. To use these files, first download the appropriate wheel then run pip from a Windows console like this example (pip must be on your Windows path, it is located in the \Scripts directory in the Python installation folder):
If you have written your own module that you wish to import then you can add this to the Python library, or include it in the same directory as your Python script. However, if the script is run as an embedded Python script then you need to tell Python where to find the module, see importing my modules for embedded Python code.
The Python interface to OrcaFlex is included on the OrcaFlex installation disk and is installed when you install OrcaFlex, though (clearly) only if Python is already present at the time. To install the Python interface manually (for example, if you only install Python on your machine after you have installed OrcaFlex), you should run the InstallPythonInterface.bat file in the OrcFxAPI\Python\ sub-directory of your OrcaFlex installation directory.
If you run the InstallPythonInterface.bat file for OrcFxAPI installation you should do so using the Windows command prompt. This file produces output messages that should be reviewed after execution, which are lost if the file is run via double-click.
For the most reliable behaviour from the installation batch file, your Python installation directory should be on your Windows path, see Issues installing the Python interface for more information.
A number of Python distributions exist that pre-package some useful supporting libraries (including NumPy and SciPy) such as Anaconda, Enthought, Python-XY and others. Some of these distributions install Python in such a way that OrcaFlex is unable to locate the Python DLL, or the Python DLL is modified and calls from OrcaFlex fail. These problems manifest themselves by errors when trying to run embedded Python code, but calling the OrcaFlex API from the Python console may work.
OrcaFlex is developed and tested against the standard Python distribution from python.org, however there are many other Python distributions available with additional modules included such as NumPy. Many of these distributions will work fine with OrcaFlex when calling the OrcaFlex API from a Python script, but some can fail when called from OrcaFlex by embedded Python code. We describe some common problems below.
The non-standard version of Python does not set the same registry values as the standard version and so the Python installation might not be detected when you run the InstallPythonInterface.bat script. OrcaFlex has a Python Info tool which lists the detected Python installations on your computer, this is located on the About form in OrcaFlex, under the Help menu item:
| Note: | This screenshot contains many more Python installations than we would expect to see on a typical OrcaFlex user's machine. This screenshot was taken on a developer's machine which is used for test purposes and so needs to have all supported Python versions available. We strongly recommend that you rationalise your Python installations and keep them to a minimum. |
If Python is already loaded in the OrcaFlex process, then the loaded distribution is marked in bold. You can force OrcaFlex to attempt to load Python by clicking the test load Python link.
If the OrcFxAPI module is not installed in the Python distribution that OrcaFlex uses, then you may need to install it manually:
Some non-standard Python distributions actually modify or recompile the Python DLL in such a way that OrcaFlex cannot use it, and you will receive a DLL error when trying to run a model using embedded Python code. In this case you will need to install an alternative Python distribution.
This error occurs because the OrcaFlex Python interface module (OrcFxAPI.py) is not present in the Python library. The modules OrcFxAPI.py (and OrcFxAPIConfig.py) should be in <Your python installation directory>\Lib\site-packages\. To resolve this error try the following.
After installing Python, or if you have just installed a new version of OrcaFlex, then you need to run the script InstallPythonInterface.bat which is in the \OrcFxAPI\Python\ sub-directory of your OrcaFlex installation directory. This script copies the OrcaFlex Python modules to the library directories of all the versions of Python present on your computer that can be detected. Note, this script requires that Python is on your Windows path – see the next point.
If after running the InstallPythonInterface.bat file you still get the same error then the likely cause is that your Python installation is not on your Windows path. You can check if this is the case by trying to run Python from a Windows console and you will get the error below:
You can add your Python installation directory to the Windows path by editing the Path environment variable which is accessible from the Control Panel. Navigate to the System window then choose Advanced system settings and then click Environment Variables. There is a Path variable in both System and User variables, you can add your Python location to either of these. Select the Path line in the variable list then click Edit. You then need to append your Python location to the existing values using the New button.
In the example below Python 3.9 is installed at C:\Program Files\Python\39. The folders C:\Program Files\Python\39 and C:\Program Files\Python\39\Scripts have been added to the existing path. Be careful to make sure that you add the correct path for your Python installation which will likely be different from the example given here.
After making changes to the path you will need to re-open the Windows console to pick up the path change.
Once Python is set up, and the OrcFxAPI module is available, then you can write Python scripts that make use of the interface, and run these scripts directly. In addition, once Python is ready it is also possible to have OrcaFlex make use of Python as a component of your models or your automated work flow. We begin by considering interface use in your own scripting.
You include the following line in your Python scripts to access the interface:
import OrcFxAPI
Importing this way does mean that any references to OrcFxAPI classes and variables must be prefixed with OrcFxAPI. For example:
import OrcFxAPI
model = OrcFxAPI.Model()
If just calling OrcaFlex from a Python script, you can use an earlier version of OrcaFlex with a later version of Python; for example you can use OrcaFlex 10.0 from a script running in Python 3.9.
As mentioned above, when executing Python code for external functions, post calculation actions, user defined results or curvilinear constraints, OrcaFlex uses embedded Python. This allows OrcaFlex to execute Python code directly from the OrcaFlex process.
When writing embedded Python scripts you do not need to include import OrcFxAPI in your script as OrcaFlex imports the module for you. You do, however, still need to use the OrcFxAPI prefix for OrcFxAPI classes and variables.
In order to execute embedded Python code OrcaFlex must locate a Python distribution. Because there may be multiple Python distributions installed, OrcaFlex searches for a Python distribution as follows:
If you choose to install the Orcina supplied embedded Python distribution when installing OrcaFlex then a registry value will be written under HKLM\Software\WOW6432Node\Orcina\OrcaFlex\<ver>\EmbeddedPython.
For items 1, 2 and 3 above, the value should be directory containing a Python installation. Because these settings are shared between 32 and 64 bit processes, then the value may alternatively be a directory which itself contains Win32 and Win64 sub-directories which in turn contain Python installations of the approptiate bitness. A good example of how such directories should be laid out is provided by the Orcina supplied embedded Python distribution.
If you wish to force a specific version of Python to be used as the OrcaFlex embedded Python, you do so using one of the environment or registry settings listed above.
If you have a Python module that you wish to import into your embedded Python script but that module is not in the Python library then just including that module in the same directory as your Python script is not sufficient for Python to locate it. Normally, Python checks the current working directory, and the script directory for modules. When running in the context of embedded Python code launched by OrcaFlex, these locations are not set to your script's location. To import another module in your script's directory you need to add its location to the Python path at the runtime of your script (and before trying to import it). The following code does this and must precede your import statement:
import sys
sys.path.append("location of your script")
Typically your script will be located in a known directory relative to the model directory, and so this can be used to modify the Python path.
When running a model that uses embedded Python code, OrcaFlex needs to locate a Python DLL to run the script.
OrcaFlex discovers installations of Python on a computer by querying the Windows registry. The presence of a Python executable in the Windows path environment variable does not affect this process. You can review the detected Python installations using the Python version information form described in the non standard Python section.
If no DLL can be located then this error message will appear. This can be puzzling if Python has been installed on the computer. The following are possible causes of this error:
OrcaFlex is aware of virtual environments, both virtualenv and the more modern venv. These are very similar tools, but if venv is available we would probably recommend it, mainly because it is built in to the Python standard library (starting from 3.3) but also because of various advantages discussed in PEP 405.
Virtual environments provide a means to isolate local Python package installations. In particular this allows you to keep the package dependencies for different projects separate. For instance, perhaps Project A requires version 1 of library C, but project B requires version 2 of library C. Python virtual environments allow you to have a single global Python installation, but separate virtual environments containing the local dependencies for each project.
When OrcaFlex attempts to load the Python DLL, it first checks to see if the VIRTUAL_ENV environment variable is defined. It uses this to determine whether to attempt to use a virtual environment, and if so, where that environment is located. When you activate a venv or virtualenv environment, the VIRTUAL_ENV environment variable is defined, so it would suffice to activate your environment in a command prompt, and then start OrcaFlex, which would inherit the environment variables of that command prompt.
Because a virtual environment isolates the executable as well as the packages, this capability allows you to enforce the use of a specific version of Python. In standard operation, OrcaFlex uses the latest Python version that it can find installed, as described above. However, if you use a virtual environment then you are also choosing a specific executable version. If you are working on projects that use a mix of Python versions, using virtual environments allows you to control which Python version is loaded by OrcaFlex.
OrcaFlex is also aware of Anaconda environments, which are analogous to virtual environments in the Anaconda world.
When OrcaFlex attempts to load the Python DLL, it checks to see if the CONDA_PYTHON_EXE environment variable is defined. It uses this to determine whether to attempt to use the active Anaconda environment, and if so, where that environment is located. For instance, if you start OrcaFlex from an Anaconda console, then OrcaFlex will use the Anaconda environment that is active when you start OrcaFlex.