Configuration & Environment

This page collects the practical knobs for running py3plex: configuration files, environment variables, supported I/O formats, and common algorithm parameters.

Configuration Files

py3plex supports configuration files for reproducible workflows. Provide them as YAML or JSON; omit sections you do not need.

Network Configuration (YAML):

# network_config.yaml
network:
  input_file: "data/multilayer.edges"
  input_type: "multiedgelist"  # one of: multiedgelist, edgelist, json, graphml, parquet
  directed: false
  weighted: true

# field meanings:
# input_file: path to your dataset
# input_type: parser to use (match the file format)
# directed/weighted: toggle graph properties

# Load with:
# network.load_network(**config['network'])

Algorithm Parameters:

# algorithm_config.yaml
community_detection:
  algorithm: "louvain_multilayer"
  params:
    gamma: 1.0          # resolution; higher favors smaller communities
    omega: 0.5          # inter-layer coupling strength
    random_state: 42

node2vec:
  dimensions: 128
  walk_length: 80
  num_walks: 10
  p: 1.0               # return hyperparameter (p > 1 biases against revisiting)
  q: 1.0               # in-out hyperparameter (q < 1 encourages outward exploration)

dynamics:
  model: "SIR"
  beta: 0.3            # infection probability per contact
  gamma: 0.1           # recovery probability
  initial_infected: 0.05  # fraction of nodes initially infected (0–1)
  steps: 100

Section meanings:

  • community_detection — choose algorithm and pass algorithm-specific params

  • node2vec — structural embedding hyperparameters (p/q control walk bias)

  • dynamics — compartmental model parameters; initial_infected expects a fraction

Visualization Settings:

# viz_config.yaml
visualization:
  layout: "force_directed"
  node_size: 50
  edge_width: 2
  dpi: 300
  output_format: "png"
  color_by_layer: true

Loading configuration:

import yaml
from py3plex.core import multinet

# Load config
with open('config.yaml', 'r') as f:
    config = yaml.safe_load(f)

# Use config
network = multinet.multi_layer_network(
    directed=config['network']['directed']
)
network.load_network(
    config['network']['input_file'],
    input_type=config['network']['input_type']
)

Environment Variables

py3plex respects the following environment variables for customization. Override them in your shell before running scripts or set them in code via os.environ.

Data Directories:

  • PY3PLEX_DATA_DIR — Override default data directory location

    • Default: ~/.py3plex/data

    • Used for: Cached datasets, downloaded networks

  • PY3PLEX_CACHE_DIR — Cache directory for computed results

    • Default: ~/.py3plex/cache

    • Used for: Embedding caches, computation results

Performance Tuning:

  • PY3PLEX_NUM_WORKERS — Suggested number of parallel workers for algorithms

    • Default recommendation: os.cpu_count() when you wire this through to APIs

    • Effect: only applied by functions/scripts that read the variable

  • PY3PLEX_MEMORY_LIMIT — Optional memory budget for large-scale operations (in GB)

    • Default: unset (falls back to library defaults)

    • Effect: honored only by routines that support explicit memory caps

Setting environment variables:

# Linux/macOS
export PY3PLEX_DATA_DIR="/path/to/data"
export PY3PLEX_NUM_WORKERS=8

# Or in Python
import os
os.environ['PY3PLEX_DATA_DIR'] = '/path/to/data'

Debugging and Development:

  • PY3PLEX_DEBUG — Enable debug mode (verbose output)

    • Values: 0 (off), 1 (on)

    • Default: 0

  • PY3PLEX_PROFILE — Enable profiling for performance analysis

    • Values: 0 (off), 1 (on)

    • Default: 0

Input Formats

Supported file formats:

  • multiedgelist — Multilayer edge list format with layer annotations

  • edgelist — Standard edge list (single layer)

  • json — JSON network format produced by py3plex tools

  • graphml — GraphML format for interoperability with NetworkX/Gephi

  • parquet — Apache Parquet for columnar, high-performance I/O

See How to Load and Build Networks for format details.

Output Formats

Networks can be exported to:

  • Pickle (Python serialization)

  • JSON

  • CSV/TSV

  • GraphML

  • Parquet

See How to Export and Serialize Networks for export details.

Algorithm Configuration

Many algorithms accept configuration parameters. The snippets below show common defaults and what each parameter controls.

Community Detection

from py3plex.algorithms.community_detection import multilayer_louvain

communities = multilayer_louvain(
    network,
    resolution=1.0,  # Higher → more, smaller communities
    omega=0.5        # Inter-layer coupling strength
)

Node2Vec

from py3plex.wrappers import train_node2vec

embeddings = train_node2vec(
    network,
    dimensions=128,      # Embedding size
    walk_length=80,      # Steps per walk
    num_walks=10,        # Walks per node
    p=1.0,               # Return parameter (larger discourages backtracking)
    q=1.0,               # In-out parameter (smaller explores outward)
    workers=4            # Parallel workers
)

Dynamics

from py3plex.dynamics import SIRDynamics

sir = SIRDynamics(
    network,
    beta=0.3,            # Infection probability per contact
    gamma=0.1,           # Recovery probability per step
    initial_infected=0.05  # Fraction of nodes initially infected (0–1)
)

See Algorithm Roadmap for complete parameter documentation.

Visualization Configuration

Customize visualization; adjust node/edge sizes to match network scale. Set show=False for headless rendering:

network.visualize_network(
    output_file='network.png',
    layout_algorithm='force_directed',
    node_size=50,
    edge_width=2,
    dpi=300,
    show=False
)

See How to Visualize Multilayer Networks for visualization options.

Logging Configuration

py3plex uses Python’s standard logging module. Configure logging for debugging and monitoring:

Basic Logging Setup:

import logging

# Set log level
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Now py3plex operations will log to console
from py3plex.core import multinet
network = multinet.multi_layer_network()
# ... logs will appear

Log Levels:

  • DEBUG — Detailed information, typically of interest only when diagnosing problems

  • INFO — Confirmation that things are working as expected (default)

  • WARNING — An indication that something unexpected happened

  • ERROR — A more serious problem, the software has not been able to perform some function

  • CRITICAL — A serious error, the program may be unable to continue running

Log to File:

import logging

# Configure file handler
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('py3plex.log'),
        logging.StreamHandler()  # Also log to console
    ]
)

Log File Location:

By default, logs are written to:

  • Console (stdout) when using StreamHandler

  • Custom file when using FileHandler

  • Environment variable PY3PLEX_LOG_FILE can override default location

Component-Specific Logging:

import logging

# Enable debug logging only for specific components
logging.getLogger('py3plex.algorithms').setLevel(logging.DEBUG)
logging.getLogger('py3plex.dsl').setLevel(logging.INFO)
logging.getLogger('py3plex.dynamics').setLevel(logging.WARNING)

Custom Logging Handlers:

For advanced use cases (e.g., sending logs to external systems):

import logging
from logging.handlers import RotatingFileHandler

# Rotating file handler (10MB max, keep 5 backups)
handler = RotatingFileHandler(
    'py3plex.log',
    maxBytes=10*1024*1024,
    backupCount=5
)
handler.setLevel(logging.DEBUG)
handler.setFormatter(
    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
)

# Add to py3plex logger
logger = logging.getLogger('py3plex')
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)

Performance Tuning

Quick levers:

  • Match PY3PLEX_NUM_WORKERS to available cores when parallelism is supported.

  • Use parquet I/O for large networks to reduce load time.

  • Set PY3PLEX_MEMORY_LIMIT when supported to avoid oversubscription on shared machines.

See Benchmarking & Performance for performance optimization strategies.

Next Steps