Skip to content

Python Integration

A compiled interface allows HERA to be integrated directly into your Python data science pipelines. It wraps the underlying MATLAB functions and provides them as native objects.

Note

The package utilizes the MATLAB Runtime. It must be installed separately as described below.

1. Installation (For End Users)

The easiest way to install the package is via pip from PyPI.

Step 1: Install Package

pip3 install hera-matlab

Step 2: Install MATLAB Runtime

HERA requires the MATLAB Runtime R2025b (v25.2). After installing the package, run the following command to check if you have the correct runtime installed or to get the direct download link:

python3 -m hera_matlab.install_runtime

Follow the instructions provided by this command to download and install the runtime if it is missing.

Step 3: macOS Specifics (Critical)

On macOS, you cannot use the standard python interpreter to import the package, as it will likely fail with a library loading error. Instead, you must use the mwpython wrapper provided by the MATLAB Runtime.

Location of mwpython: Typically found at: /Applications/MATLAB/MATLAB_Runtime/R2025b/bin/mwpython

Usage: Instead of running python3 script.py, run:

/Applications/MATLAB/MATLAB_Runtime/R2025b/bin/mwpython script.py

You may want to add this to your PATH variable for easier access.

Warning

Python Version Compatibility: HERA (via MATLAB Runtime) currently supports Python 3.9, 3.10, 3.11, and 3.12. Python 3.13 is NOT supported.

If you have Python 3.13 installed, mwpython will fail to load your packages. Solution: Create and activate a Virtual Environment with Python 3.12 before running mwpython.

# Example using brew to install python 3.12
brew install python@3.12
/opt/homebrew/bin/python3.12 -m venv .venv_hera
source .venv_hera/bin/activate
pip3 install hera-matlab
# Now mwpython will automatically use this environment
mwpython script.py

2. Usage Modes

A. Standard Pipeline (File-Based)

This mode replicates the MATLAB batch processing workflow. It runs the complete analysis based on a JSON configuration file and automatically generates all PDF reports and plots on disk.

Note

The interactive command-line interface (CLI) is not supported in the Python package. You must use a configuration file.

import hera_matlab

# Initialize Runtime
hera = hera_matlab.initialize()

# Run with JSON configuration
# Outputs (PDFs, Images) will be saved to the 'output_dir' defined in the config
hera.start_ranking('configFile', 'analysis_config.json', nargout=0)

hera.terminate()

See Configuration & Parameters for a complete list of available options.

B. Direct Data Integration (NumPy/Pandas)

This mode allows you to use HERA as a computational engine within your Python scripts (e.g., Jupyter Notebooks). You can pass data directly from NumPy/Pandas and receive the ranking results as a Python dictionary, enabling seamless integration into larger data science pipelines.

Automatic Data Conversion (v1.2.0+)

Starting with version 1.2.0, the package includes a wrapper that performs bidirectional conversion:

  1. Input: Automatically converts NumPy arrays and Pandas DataFrames to the required MATLAB types.
  2. Output: Automatically converts returned MATLAB data (e.g., matlab.double) back into NumPy arrays for easy processing in Python.

This eliminates the need for manual conversion in both directions.

Tip

Performance (v1.4.0+): Input conversion utilizes modern MATLAB direct buffer access (R2022a+). This avoids unnecessary Python list overhead.

import hera_matlab
import numpy as np

# Initialize
hera = hera_matlab.initialize()

# Option 1: Using NumPy Arrays
data_m1 = np.array([[0.1, 0.5], [0.2, 0.4]])
data_m2 = np.array([[1.0, 3.0], [1.2, 2.9]])

# (Option 2: Pandas DataFrames are also supported)

config = {
    'custom_data': [data_m1, data_m2],
    'metric_names': ['Runtime', 'Accuracy'],
    'dataset_names': ['Method A', 'Method B'],
    'ranking_mode': 'M1_M2',
    'output_dir': 'hera_numpy_results'
}

# The wrapper automatically converts the data before calling MATLAB
results = hera.run_ranking(config, nargout=1)

print(f"Final Ranks: {results['final_rank']}")

Note

Explicit termination (hera.terminate()) is optional in scripts, as the package handles cleanup automatically. However, it is recommended for interactive sessions (e.g., Jupyter) to free up resources immediately.

See Results Structure Reference for a complete list of available fields

3. Running the Test Suite

You can execute the internal HERA verification and test suite (Scientific, System, and Unit tests) directly from Python to ensure the installation is valid and mathematically correct. For more details on the test suite, see the Testing section in the main documentation.

import hera_matlab

# Initialize
hera = hera_matlab.initialize()

# Launch Test Mode
# Arguments: 'runtest', 'true'
# This will execute all tests and print the results to standard output/log files.
hera.start_ranking('runtest', 'true', nargout=0)

hera.terminate()

This is useful for verifying deployments on new machines (e.g., CI/CD).

4. Running Convergence Analysis

You can also trigger the robust convergence analysis directly from Python. This is identical to the MATLAB HERA.start_ranking('convergence', 'true') command. For more details on the analysis and its parameters, see Convergence Analysis.

import hera_matlab

# Initialize
hera = hera_matlab.initialize()

# Run Convergence Analysis
# Arguments: 'convergence', 'true'
# Optional: 'sims', 50 (for higher precision)
# Optional: 'logPath', '/path/to/log' (or 'interactive')
hera.start_ranking('convergence', 'true', nargout=0)

# Run with custom JSON configuration (Advanced)
# HERA will automatically load all parameters from the file
hera.start_ranking('convergence', 'analysis_config.json', nargout=0)

hera.terminate()

5. Build Instructions (For Maintainers)

To generate the installer and Python package from source (requires MATLAB Compiler SDK):

  1. Run the Build Helper:
./deploy/build_and_prep_pypi.sh

This script compiles the MATLAB code, injects the runtime checks, and prepares the distribution artifacts (.whl, .tar.gz) in deploy/dist.

  1. Distribution: Upload the generated artifacts from deploy/dist to PyPI or GitHub Releases.

Tip

Release Scope & Policy

  • Full Suite Releases: Releases are not just for Python. A release MUST always include all artifacts: the MATLAB Toolbox (.mltbx), standalone executables, and the Python distribution.
  • Mandatory Review: All changes must be reviewed and approved by the repository owner before a release is prepared.
  • Compliance: Contributors must strictly follow the rules outlined in CODE_OF_CONDUCT.md and CONTRIBUTING.md.