Skip to main content
PyPowSyBl is built on Java code compiled to native libraries using GraalVM. Understanding how to configure the runtime environment can help optimize performance for your use case.

​
Memory Configuration

The underlying Java runtime (SubstrateVM) manages memory with a garbage collector. You can control memory allocation using the GRAALVM_OPTIONS environment variable.

​
Setting Maximum Heap Size

By default, maximum memory is automatically determined based on your machine’s available memory. To set a specific limit: 
GRAALVM_OPTIONS="-Xmx1G" python
This limits the heap to 1 GB.

​
Verifying Memory Settings

Enable debug logging to see the configured heap size: 
import logging

logging.basicConfig()
logging.getLogger('powsybl').setLevel(logging.DEBUG)

import pypowsybl as pp
# Output: DEBUG:powsybl:Max heap is 1086 MB

​
Common Memory Configurations

GRAALVM_OPTIONS="-Xmx1G" python

​
Environment Variables

​
Setting in Different Environments

Temporary (current session):
export GRAALVM_OPTIONS="-Xmx4G"
python my_script.py
Permanent (add to ~/.bashrc or ~/.zshrc):
echo 'export GRAALVM_OPTIONS="-Xmx4G"' >> ~/.bashrc
source ~/.bashrc
Temporary:
set GRAALVM_OPTIONS="-Xmx4G"
python my_script.py
Permanent:
setx GRAALVM_OPTIONS "-Xmx4G"
Temporary:
$env:GRAALVM_OPTIONS="-Xmx4G"
python my_script.py
Permanent:
[System.Environment]::SetEnvironmentVariable('GRAALVM_OPTIONS','-Xmx4G','User')

import os
os.environ['GRAALVM_OPTIONS'] = '-Xmx4G'

# Must be set BEFORE importing pypowsybl
import pypowsybl as pp

import os

# Set before importing pypowsybl
os.environ['GRAALVM_OPTIONS'] = '-Xmx4G'

import pypowsybl as pp
# Rest of your code

​
Advanced GraalVM Options

​
Garbage Collection Tuning

# Use serial GC (lower memory overhead)
GRAALVM_OPTIONS="-Xmx4G --gc=serial" python

# Use epsilon GC (no GC, for short-running tasks)
GRAALVM_OPTIONS="-Xmx4G --gc=epsilon" python

​
Multiple Options

Combine multiple options: 
GRAALVM_OPTIONS="-Xmx8G -Xms2G --gc=serial" python
Options:
  • -Xmx: Maximum heap size
  • -Xms: Initial heap size
  • --gc: Garbage collector type

​
Performance Optimization Tips

1

Start with default settings

Let the automatic configuration determine initial heap size.
2

Monitor memory usage

Enable debug logging to see actual memory consumption:
import logging
logging.basicConfig()
logging.getLogger('powsybl').setLevel(logging.DEBUG)
3

Adjust as needed

If you see OutOfMemoryError or excessive garbage collection:
  • Increase -Xmx value
  • Set -Xms closer to -Xmx to reduce reallocation
4

Test performance

Benchmark your specific workload with different settings.

​
Troubleshooting

Symptoms: Program crashes with memory errorSolutions:
  1. Increase heap size: 
    GRAALVM_OPTIONS="-Xmx8G" python
  2. Process smaller chunks of data
  3. Use network reduction to limit network size: 
    network.reduce_by_voltage_range(v_min=225)
Symptoms: Operations take longer than expectedSolutions:
  1. Increase initial heap size to reduce allocations: 
    GRAALVM_OPTIONS="-Xmx8G -Xms4G" python
  2. For short scripts, consider epsilon GC: 
    GRAALVM_OPTIONS="-Xmx4G --gc=epsilon" python
  3. Enable debug logging to identify bottlenecks
Symptoms: Memory limits don’t seem to applySolutions:
  1. Ensure variable is set before importing pypowsybl
  2. Verify the environment variable: 
    import os
print(os.environ.get('GRAALVM_OPTIONS'))
  3. Restart Python interpreter/kernel

​
Platform-Specific Considerations

​
Docker Containers

When running in Docker: 
FROM python:3.9

# Set memory limit for container
ENV GRAALVM_OPTIONS="-Xmx2G"

RUN pip install pypowsybl

COPY . /app
WORKDIR /app

CMD ["python", "analysis.py"]
Make sure Docker container has sufficient memory allocated.

​
Cluster/HPC Environments

For SLURM or similar: 
#!/bin/bash
#SBATCH --mem=16G
#SBATCH --cpus-per-task=4

export GRAALVM_OPTIONS="-Xmx14G"
python large_network_analysis.py

​
Cloud Notebooks (Google Colab, etc.)

import os

# Set before importing pypowsybl
os.environ['GRAALVM_OPTIONS'] = '-Xmx12G'

import pypowsybl as pp
Cloud platforms may have memory limits. Check your instance’s available memory.

​
Development

# Moderate memory, debug enabled
export GRAALVM_OPTIONS="-Xmx2G"

import logging
logging.basicConfig(format='%(asctime)s - %(levelname)s - %(message)s')
logging.getLogger('powsybl').setLevel(logging.DEBUG)

​
Production

# Higher memory, minimal logging
export GRAALVM_OPTIONS="-Xmx8G -Xms4G"

import logging
logging.basicConfig()
logging.getLogger('powsybl').setLevel(logging.WARNING)

​
Batch Processing

# Maximum memory, epsilon GC for short jobs
export GRAALVM_OPTIONS="-Xmx16G --gc=epsilon"

​
Interactive Analysis

# Moderate memory, info logging
export GRAALVM_OPTIONS="-Xmx4G"

import logging
logging.basicConfig()
logging.getLogger('powsybl').setLevel(logging.INFO)

​
Monitoring Memory Usage

Track memory consumption in your scripts: 
import pypowsybl as pp
import psutil
import os

def print_memory_usage():
    process = psutil.Process(os.getpid())
    mem_info = process.memory_info()
    print(f"Memory usage: {mem_info.rss / 1024 / 1024:.2f} MB")

print_memory_usage()
network = pp.network.load('large_network.xiidm')
print_memory_usage()

result = pp.loadflow.run_ac(network)
print_memory_usage()

​
Best Practices

Don’t wait for memory errors. Estimate your needs:
  • Small network (< 1000 buses): 1-2 GB
  • Medium network (1000-10000 buses): 4-8 GB
  • Large network (> 10000 buses): 16+ GB
Set heap size to 70-80% of available system memory:
# For 16 GB system
GRAALVM_OPTIONS="-Xmx12G"
Use production-sized networks for testing memory requirements.
Include memory requirements in your project documentation:
## Requirements
- Python 3.8+
- PyPowSyBl
- Minimum 8 GB RAM
- Recommended: `GRAALVM_OPTIONS="-Xmx6G"`

​
Configuration Functions

PyPowSyBl provides utility functions for managing configuration settings. Display version information for PyPowSyBl and its components: 
import pypowsybl as pp

pp.print_version()
This prints a table showing versions of:
  • PyPowSyBl Python package
  • PowSyBl Core Java libraries
  • Native library components
Use case: Debugging, verifying installation, reporting issues

​
set_config_read()

Control whether PyPowSyBl reads the ~/.itools/config.yml configuration file: 
import pypowsybl as pp

# Disable config file reading (use defaults only)
pp.set_config_read(False)

# Re-enable config file reading
pp.set_config_read(True)
​
read_config
bool
default:true
Whether to read the configuration file
Use case: Override system-wide configuration, isolate test environments

​
is_config_read()

Check the current configuration file reading status: 
import pypowsybl as pp

if pp.is_config_read():
    print("Using ~/.itools/config.yml")
else:
    print("Using default configuration")
Returns: bool - True if config file is being read, False otherwise

​
Configuration File Format

The ~/.itools/config.yml file allows system-wide configuration of PowSyBl parameters: 
load-flow-default-parameters:
  voltageInitMode: DC_VALUES
  transformerVoltageControlOn: true
  
security-analysis-default-parameters:
  flowProportionalThreshold: 0.1
Configuration file settings can be overridden by explicitly passing parameters to functions.

​
Next Steps

Logging

Configure detailed logging

Network

Back to network basics

Build docs developers (and LLMs) love

Get started for freeTalk to us