Disclaimer:

This article describes how to use the GSPy interface, provided by GoldSim Technology Group, to run custom Python scripts from GoldSim models. This feature requires familiarity with Python programming and managing Python environments. While GoldSim provides the interface DLLs (`GSPy.pyd` in 32-bit and 64-bit versions), the user is responsible for writing the Python script (`GSPyModule.py`) and correctly installing and configuring a compatible Python environment for the chosen DLL version. Errors or issues arising from the user's Python code, Python environment configuration (including missing packages), or incorrect setup are not related to the GoldSim framework, and GoldSim Technology Group cannot provide direct support or troubleshooting for custom Python scripts or environments. Please use this feature at your own risk and discretion. You are welcome to ask GSPy-related questions in our public forum: Modeling Application Questions – GoldSim Help Center.

Follow these instructions to set up an environment for using the GSPy interface, which allows Python scripts to be called by a GoldSim External DLL element. These steps use a standard Python installation from python.org.

Choosing Your GSPy Workflow

GoldSim (which is a 32-bit application) can interact with Python using the GSPy interface in two primary ways, depending on which GSPy DLL version you use:

1. Using the 32-bit GSPy DLL:
   • Requires installing 32-bit Python.
   • The 32-bit GSPy.pyd runs directly inside the GoldSim process.
   • Simpler setup, suitable for many tasks.
   • May be limited by the memory constraints of a 32-bit process (~2-3 GB usable RAM) for very large data operations within Python.
   • In GoldSim's External element properties, the "Run 64-bit DLLs in a separate process" option should be unchecked.
2. Using the 64-bit GSPy DLL (via Separate Process):
   • Requires installing 64-bit Python.
   • Requires enabling the "Run 64-bit DLLs in a separate process" option within GoldSim's External element properties.
   • GoldSim launches a background 64-bit process that hosts the 64-bit GSPy.pyd.
   • Allows Python scripts to access much more system memory (limited only by system resources).
   • Environment setup (Python, environment variables, package installation) MUST target the 64-bit Python installation.

Choose the workflow that best suits your needs and the GSPy binaries you intend to use. The setup steps below are divided based on this choice.

Setup the Environment

Below are the steps to install Python and configure the environment for running GoldSim with your chosen GSPy workflow.

Note: It's often easiest to start this process on a machine with a clean Python setup to avoid potential conflicts. If you have existing Python installations, ensure the environment variables point correctly to the specific 32-bit or 64-bit installation you intend to use with GSPy.

A) Setup for 32-bit GSPy (In-Process)

Follow these steps if you plan to use the 32-bit GSPy.pyd DLL.

1. Download and install 32-bit Python 3.x from python.org. Select the "Windows installer (32-bit)".
2. During installation, choose "Customize installation" and ensure "pip" is included. IMPORTANT: Do NOT check "Add python.exe to PATH".
3. Note the final installation directory for 32-bit Python (e.g., C:\Users\<User>\AppData\Local\Programs\Python\Python3x-32).
4. Download and unzip the GSPy distribution files (e.g., GSPY_Binaries_Examples.zip) into a known location (e.g., "GSPy_Distribution").
5. Create your project's working directory (e.g., "GSPy_Working").
6. Copy the 32-bit GSPy files into your "Working" directory:
   • From `GSPy_Distribution\bin\32-bit\` copy: GSPy.pyd
   • From `GSPy_Distribution\bin\32-bit\` copy: TestGSPy.exe
   • From an example folder (e.g., `GSPy_Distribution\gsm\Scalar Addition\`) copy: GSPyModule_ScalarAddition.py (and optionally the .gsm file)
7. In the "Working" directory, rename the copied .py file to exactly GSPyModule.py.
8. Set Environment Variables for 32-bit Python:
   • Open "Edit environment variables for your account".
   • Create a New User variable: Name = GSPY32, Value = <Full path to your 32-bit Python installation directory>.
   • Edit the User Path variable: Add new entries for %GSPY32% and %GSPY32%\Scripts.
   • Click OK to save changes.
9. Restart Applications: Close and reopen any Command Prompt/PowerShell windows and GoldSim.

B) Setup for 64-bit GSPy (Separate Process)

Follow these steps if you plan to use the 64-bit GSPy.pyd DLL via GoldSim's "Run 64-bit DLLs in a separate process" option.

1. Download and install 64-bit Python 3.x from python.org. Select the "Windows installer (64-bit)".
2. During installation, choose "Customize installation" and ensure "pip" is included. IMPORTANT: Do NOT check "Add python.exe to PATH".
3. Note the final installation directory for 64-bit Python (e.g., C:\Program Files\Python3x or C:\Users\<User>\AppData\Local\Programs\Python\Python3x).
4. Download and unzip the GSPy distribution files (e.g., GSPY_Binaries_Examples.zip) into a known location (e.g., "GSPy_Distribution").
5. Create your project's working directory (e.g., "GSPy_Working").
6. Copy the 64-bit GSPy files into your "Working" directory:
   • From `GSPy_Distribution\bin\64-bit\` copy: GSPy.pyd
   • From `GSPy_Distribution\bin\64-bit\` copy: TestGSPy.exe
   • From an example folder (e.g., `GSPy_Distribution\gsm\Scalar Addition\`) copy: GSPyModule_ScalarAddition.py (and optionally the .gsm file)
7. In the "Working" directory, rename the copied .py file to exactly GSPyModule.py.
8. Set Environment Variables for 64-bit Python:
   • Open "Edit environment variables for your account".
   • Create a New User variable: Name = GSPY, Value = <Full path to your 64-bit Python installation directory>.
   • Edit the User Path variable: Add new entries for %GSPY% and %GSPY%\Scripts.
   • Click OK to save changes.
9. Restart Applications: Close and reopen any Command Prompt/PowerShell windows and GoldSim.

Install Required Python Packages (e.g., NumPy)

If your GSPyModule.py script requires external packages (like NumPy, Pandas, SciPy), you must install them into the specific Python environment (32-bit or 64-bit) corresponding to the GSPy workflow you set up.

1. Open a NEW Command Prompt or PowerShell window (to ensure it uses the updated environment variables).
2. Navigate to your working directory (using cd).
3. Install the required package(s). Use the full path to pip.exe via the correct environment variable for your chosen setup:
   
   If you set up for 32-bit GSPy:

   "%GSPY32%\Scripts\pip.exe" install numpy

   (Or use -r requirements.txt if you have one listing your packages)
   
   If you set up for 64-bit GSPy:

   "%GSPY%\Scripts\pip.exe" install numpy

   (Or use -r requirements.txt)
4. Let the installation complete. You can verify installation (replace `numpy` with your package):
   • For 32-bit: "%GSPY32%\python.exe" -c "import numpy; print(numpy.__version__)"
   • For 64-bit: "%GSPY%\python.exe" -c "import numpy; print(numpy.__version__)"

Testing the Environment

Follow these steps to test the environment using the GSPy test utility and the GoldSim application.

1. Open a new Command Prompt or PowerShell window and navigate to your working directory.
2. Run the test executable **corresponding to your setup** (32-bit or 64-bit TestGSPy.exe that you copied earlier):

   TestGSPy.exe

3. Check the console output. It should report version, inputs/outputs, run the calculation function, and show results without any Python errors (like `ImportError`, `ValueError`, etc.). See the example output in the GSPy `README.md` file.
4. If `TestGSPy.exe` fails, review the setup steps for your chosen workflow (32-bit or 64-bit), paying close attention to environment variables and ensuring required packages are installed in the *correct* Python environment. Consult the `README.md` Troubleshooting section.
5. If `TestGSPy.exe` succeeded, start GoldSim (remember it is 32-bit).
6. Open the example GoldSim model (e.g., GSPyScalarAddition.gsm or GSPyMatrixAddition.gsm) located in your working directory.
7. Go to the properties of the External element (e.g., 'External_Calc').
8. In "DLL File Path", ensure it points to the correct GSPy.pyd (32-bit or 64-bit) in your working directory (using .\GSPy.pyd often works).
9. Configure Execution Mode:
   • If using the 32-bit GSPy.pyd, ensure the option "Run 64-bit DLLs in a separate process" is **UNCHECKED**.
   • If using the 64-bit GSPy.pyd, ensure the option "Run 64-bit DLLs in a separate process" is **CHECKED**.
10. On the "Interface" tab, verify the number of Inputs and Outputs matches those reported by the `NumberOfInputs()` and `NumberOfOutputs()` functions in your current `GSPyModule.py`.
11. Run the GoldSim model. It should run without errors related to loading the DLL or executing the Python script.

Troubleshooting

If you encounter errors when running TestGSPy.exe or your GoldSim model, please refer first to the detailed Troubleshooting section in the README.md file included with the GSPy distribution. Common issues include:

• Architecture Mismatch: The most common issue! Ensure the Python version (32/64-bit), GSPy binaries (`.pyd`, `.exe`) (32/64-bit), and GoldSim configuration ("Separate process" checked/unchecked) are all consistent for your chosen workflow (either all 32-bit in-process OR 64-bit separate process).
• Incorrect Environment Variables: Using `GSPY` when `GSPY32` was needed (or vice-versa), incorrect paths assigned to the variables, or forgetting to add `%GSPY%` / `%GSPY32%` to the `Path`. Verify paths and restart Command Prompt/GoldSim after changes.
• Path Issues: Windows cannot find the Python DLL (e.g., `python3.dll`). Ensure the correct Python directory (`%GSPY%` or `%GSPY32%`) is effectively included in the system's search path.
• `GSPyModule.py` Issues: File not found (must be in the same directory as the `.gsm` model or `TestGSPy.exe`), file incorrectly named, required functions missing or misspelled (ReturnPyModuleVersion, NumberOfInputs, NumberOfOutputs, DoCalcsAndReturnValues), functions returning wrong data types or tuple sizes.
• Python Package Errors (`ImportError`): A required package (like NumPy) is not installed in the *specific* Python environment (32-bit or 64-bit) being used by GSPy. Use the explicit pip path (e.g., "%GSPY%\Scripts\pip.exe" install ...) to install into the correct environment.
• Python Script Runtime Errors: Errors within your Python code's logic (e.g., `ValueError`, `IndexError`, `TypeError`). Use `TestGSPy.exe` from the command line and add `print()` statements or `try...except` blocks to your `GSPyModule.py` to debug.