Configuration Examples

Complete guide to configuring Epochly for your needs.

Configuration Methods

Epochly can be configured through multiple methods, in order of precedence:

Runtime API - epochly.configure() (highest priority)
Environment Variables - System environment variables
Configuration File - epochly.toml or .epochly.toml
CLI Flags - Command-line arguments
Defaults - Built-in sensible defaults (lowest priority)

Environment Variables

Basic Configuration

# Set enhancement level (0-4)
export EPOCHLY_LEVEL=2
# Set maximum worker threads
export EPOCHLY_MAX_WORKERS=8
# Set optimization mode
export EPOCHLY_MODE=balanced

Disable Epochly

# Disable Epochly completely
export EPOCHLY_DISABLE=true
# Emergency disable (bypasses all checks)
export EPOCHLY_EMERGENCY_DISABLE=1

JIT Configuration

# Enable/disable JIT compilation
export EPOCHLY_JIT_ENABLED=true
# Select JIT backend (numba, native, pyston)
export EPOCHLY_JIT_BACKEND=numba
# Set hot path threshold (number of calls before JIT)
export EPOCHLY_JIT_HOT_PATH_THRESHOLD=100

GPU Configuration

# Enable GPU acceleration
export EPOCHLY_GPU_ENABLED=true
# Set GPU memory limit (MB)
export EPOCHLY_GPU_MEMORY_LIMIT=4096
# Set workload threshold for GPU (min array size)
export EPOCHLY_GPU_WORKLOAD_THRESHOLD=1000000

Logging Configuration

# Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
export EPOCHLY_LOG_LEVEL=INFO
# Set log file path
export EPOCHLY_LOG_FILE=/var/log/epochly.log
# Disable logging
export EPOCHLY_DISABLE_LOGGING=false

Complete Environment Example

# Production configuration
export EPOCHLY_LEVEL=2
export EPOCHLY_MAX_WORKERS=4
export EPOCHLY_MODE=conservative
export EPOCHLY_JIT_ENABLED=true
export EPOCHLY_JIT_BACKEND=numba
export EPOCHLY_LOG_LEVEL=WARNING
export EPOCHLY_LOG_FILE=/var/log/epochly.log

Runtime API

Basic Configuration

import epochly
# Configure at startup
epochly.configure(
    enhancement_level=2,
    max_workers=8,
    mode='balanced'
)
# Your code here
@epochly.optimize()
def my_function(data):
    return process(data)

Full Configuration Options

import epochly
epochly.configure(
    # Core settings
    enhancement_level=2,
    mode='balanced',
    
    # Worker settings
    max_workers=8,
    reserve_cores=2,
    
    # JIT settings
    jit_enabled=True,
    jit_backend='numba',
    jit_hot_path_threshold=100,
    
    # GPU settings
    gpu_enabled=False,
    gpu_memory_limit=4096,
    gpu_workload_threshold=1_000_000,
    
    # Monitoring settings
    enable_monitoring=True,
    track_memory=True,
    
    # Logging settings
    log_level='INFO',
    log_file=None,
    log_console=True
)

Get Current Status

import epochly
# Get configuration status
status = epochly.get_status()
print(f"Level: {status['enhancement_level']}")
print(f"Mode: {status['mode']}")
print(f"Workers: {status['max_workers']}")
print(f"JIT enabled: {status['jit_enabled']}")
print(f"GPU available: {status['gpu_available']}")

Enable/Disable Monitoring

import epochly
# Enable monitoring
epochly.enable_monitoring()
# Run your code
result = compute_heavy_task()
# Get metrics
metrics = epochly.get_metrics()
print(f"Total time: {metrics['total_time']:.3f}s")
print(f"Function calls: {metrics['total_calls']}")
# Disable monitoring
epochly.disable_monitoring()

Dynamic Reconfiguration

import epochly
# Start with conservative settings
epochly.configure(
    enhancement_level=1,
    max_workers=2
)
# Process small data
small_data = range(1000)
result1 = process(small_data)
# Reconfigure for large data
epochly.configure(
    enhancement_level=3,
    max_workers=16
)
# Process large data
large_data = range(10_000_000)
result2 = process(large_data)

CLI Configuration

Show Current Configuration

# Show all configuration settings
epochly config show
# Show specific setting
epochly config get EPOCHLY_LEVEL

Output:

Current Epochly Configuration:
  enhancement_level: 2
  mode: balanced
  max_workers: 8
  jit_enabled: true
  jit_backend: numba
  gpu_enabled: false
  log_level: INFO

Set Configuration

# Set enhancement level
epochly config set EPOCHLY_LEVEL 3
# Set worker count
epochly config set EPOCHLY_MAX_WORKERS 16
# Set mode
epochly config set EPOCHLY_MODE aggressive

Get Specific Setting

# Get enhancement level
epochly config get EPOCHLY_LEVEL
# Get max workers
epochly config get EPOCHLY_MAX_WORKERS

Output:

Reset Configuration

# Reset all settings to defaults
epochly config reset
# Reset specific setting
epochly config reset EPOCHLY_LEVEL

Export Configuration

# Export to file
epochly config export > my-config.toml
# Export to environment variables
epochly config export --format env > epochly.env

Import Configuration

# Import from file
epochly config import my-config.toml
# Import and override existing
epochly config import --force my-config.toml

Configuration File (epochly.toml)

Create an epochly.toml file in your project directory:

# epochly.toml - Full configuration example
[core]
# Enhancement level (0-4)
enhancement_level = 2
# Optimization mode (off, monitor, conservative, balanced, aggressive)
mode = "balanced"
# Enable/disable Epochly
enabled = true
[workers]
# Maximum number of workers
max_workers = 8
# Reserve cores for system
reserve_cores = 2
# Maximum percentage of cores to use
max_cores_percent = 75
[jit]
# Enable JIT compilation
enabled = true
# JIT backend (numba, native, pyston)
backend = "numba"
# Hot path threshold (calls before compilation)
hot_path_threshold = 100
# Cache compiled functions
cache_enabled = true
[gpu]
# Enable GPU acceleration
enabled = false
# GPU memory limit in MB
memory_limit = 4096
# Minimum array size for GPU (elements)
workload_threshold = 1000000
# CUDA device ID
device_id = 0
[monitoring]
# Enable performance monitoring
enabled = true
# Track memory usage
track_memory = true
# Track CPU usage
track_cpu = true
# Metrics retention (seconds)
metrics_retention = 3600
[logging]
# Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
level = "INFO"
# Log file path (null for no file)
file = "/var/log/epochly.log"
# Log to console
console = true
# Log format
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Minimal Configuration File

# .epochly.toml - Minimal configuration
[core]
enhancement_level = 2
mode = "balanced"
[workers]
max_workers = 8
[logging]
level = "INFO"

Configuration File Location

Epochly searches for configuration files in the following order:

Current Directory: ./epochly.toml or ./.epochly.toml
User Config: ~/.config/epochly/config.toml (Linux/Mac)
User Config: %APPDATA%\\epochly\\config.toml (Windows)
System Config: /etc/epochly/config.toml (Linux/Mac)

Specify Custom Config File

# Use custom config file
epochly --config /path/to/custom.toml script.py
# Or with environment variable
export EPOCHLY_CONFIG=/path/to/custom.toml
python script.py

# In Python
import epochly
epochly.load_config('/path/to/custom.toml')

Mode Presets

Epochly provides predefined optimization modes:

Mode	Level	Workers	JIT	GPU	Use Case
off	0	1	No	No	Debugging, testing
monitor	0	1	No	No	Performance monitoring only
conservative	1	2-4	No	No	Production with limited resources
balanced	2	4-8	Yes	No	General-purpose optimization
aggressive	3	All cores	Yes	Yes	Maximum performance

Using Mode Presets

import epochly
# Use a preset mode
epochly.configure(mode='balanced')
# Or via environment variable
# export EPOCHLY_MODE=aggressive

# Via CLI
epochly config set EPOCHLY_MODE balanced

Use Case Examples

Development Environment

Full optimization with debug logging:

import epochly
epochly.configure(
    enhancement_level=3,
    max_workers=8,
    jit_enabled=True,
    enable_monitoring=True,
    log_level='DEBUG',
    log_console=True
)

# Or via environment
export EPOCHLY_LEVEL=3
export EPOCHLY_MAX_WORKERS=8
export EPOCHLY_LOG_LEVEL=DEBUG

Production Environment

Conservative settings with limited workers:

import epochly
epochly.configure(
    mode='conservative',
    max_workers=4,
    reserve_cores=2,
    jit_enabled=True,
    enable_monitoring=True,
    log_level='WARNING',
    log_file='/var/log/epochly.log'
)

# production.toml
[core]
mode = "conservative"
[workers]
max_workers = 4
reserve_cores = 2
[logging]
level = "WARNING"
file = "/var/log/epochly.log"

CI/CD Pipeline

Disabled for deterministic tests:

# Disable Epochly in CI
export EPOCHLY_DISABLE=true
# Or use monitoring mode for metrics
export EPOCHLY_MODE=monitor

# In test setup
import epochly
if os.getenv('CI'):
    epochly.configure(mode='off')
else:
    epochly.configure(mode='balanced')

GPU Workloads

Level 4 with GPU enabled:

import epochly
epochly.configure(
    enhancement_level=4,
    gpu_enabled=True,
    gpu_memory_limit=8192,
    gpu_workload_threshold=1_000_000,
    max_workers=4  # Limit CPU workers when using GPU
)

# Via environment
export EPOCHLY_LEVEL=4
export EPOCHLY_GPU_ENABLED=true
export EPOCHLY_GPU_MEMORY_LIMIT=8192
export CUDA_VISIBLE_DEVICES=0,1

Memory-Constrained Environment

Level 1 with few workers:

import epochly
epochly.configure(
    enhancement_level=1,  # Threading only
    max_workers=2,        # Minimal workers
    jit_enabled=False,    # Disable JIT to save memory
    track_memory=True     # Monitor memory usage
)

# memory-constrained.toml
[core]
enhancement_level = 1
[workers]
max_workers = 2
reserve_cores = 1
[jit]
enabled = false
[monitoring]
track_memory = true

Validation

Verify Configuration

# Basic validation
epochly doctor
# Verbose validation
epochly doctor --verbose
# JSON output for scripting
epochly doctor --json

Output:

Epochly Configuration Validation:
✓ Epochly installed correctly
✓ Python version: 3.11.5 (compatible)
✓ Configuration file found: ./epochly.toml
✓ Enhancement level: 2 (valid)
✓ Max workers: 8 (valid, 8 cores available)
✓ JIT backend: numba (available)
✓ GPU: not configured
✓ All dependencies installed
Configuration summary:
  Mode: balanced
  Workers: 8
  JIT: enabled (numba)
  GPU: disabled
  Monitoring: enabled
  Log level: INFO
Recommendations:
  - Consider Level 3 for parallel workloads
  - GPU available but not enabled

Verbose Validation

epochly doctor --verbose

Output:

Detailed Epochly Configuration:
Environment:
  EPOCHLY_LEVEL: 2
  EPOCHLY_MAX_WORKERS: 8
  EPOCHLY_MODE: balanced
  EPOCHLY_JIT_ENABLED: true
  EPOCHLY_JIT_BACKEND: numba
Configuration file: ./epochly.toml
  [core]
    enhancement_level = 2
    mode = "balanced"
  [workers]
    max_workers = 8
    reserve_cores = 2
System:
  Python: 3.11.5
  Platform: Linux-5.15.0-x86_64
  CPU cores: 8
  Memory: 16.0 GB
  GPU: NVIDIA GeForce RTX 3080 (available)
Dependencies:
  ✓ numpy: 1.24.3
  ✓ numba: 0.58.0
  ✓ cupy: not installed (GPU support disabled)
All checks passed!

JSON Output

epochly doctor --json

Output:

{
  "status": "ok",
  "version": "1.0.0",
  "python_version": "3.11.5",
  "configuration": {
    "enhancement_level": 2,
    "mode": "balanced",
    "max_workers": 8,
    "jit_enabled": true,
    "jit_backend": "numba",
    "gpu_enabled": false
  },
  "system": {
    "cpu_cores": 8,
    "memory_gb": 16.0,
    "gpu_available": true
  },
  "dependencies": {
    "numpy": "1.24.3",
    "numba": "0.58.0",
    "cupy": null
  },
  "recommendations": [
    "Consider enabling GPU acceleration",
    "Level 3 available for parallel workloads"
  ]
}

Configuration Best Practices

1. Start with Defaults

import epochly
# Let Epochly use defaults initially
# Don't configure unless you have a specific need
@epochly.optimize()
def my_function(data):
    return process(data)

2. Use Configuration Files for Projects

# Project-specific .epochly.toml
[core]
enhancement_level = 2
mode = "balanced"
[workers]
max_workers = 8

3. Use Environment Variables for Deployment

# docker-compose.yml
environment:
  - EPOCHLY_LEVEL=2
  - EPOCHLY_MAX_WORKERS=4
  - EPOCHLY_MODE=conservative

4. Override in Code When Needed

import epochly
import os
# Different config for different environments
if os.getenv('ENVIRONMENT') == 'production':
    epochly.configure(mode='conservative')
elif os.getenv('ENVIRONMENT') == 'development':
    epochly.configure(mode='aggressive', log_level='DEBUG')

5. Validate Configuration

import epochly
# Configure
epochly.configure(enhancement_level=2, max_workers=8)
# Validate
status = epochly.get_status()
assert status['enhancement_level'] == 2
assert status['max_workers'] == 8
print("Configuration validated successfully")

Configuration Examples

Configuration Methods

Environment Variables

Basic Configuration

Disable Epochly

JIT Configuration

GPU Configuration

Logging Configuration

Complete Environment Example

Runtime API

Basic Configuration

Full Configuration Options

Get Current Status

Enable/Disable Monitoring

Dynamic Reconfiguration

CLI Configuration

Show Current Configuration

Set Configuration

Get Specific Setting

Reset Configuration

Export Configuration

Import Configuration

Configuration File (epochly.toml)

Minimal Configuration File

Configuration File Location

Specify Custom Config File

Mode Presets

Using Mode Presets

Use Case Examples

Development Environment

Production Environment

CI/CD Pipeline

GPU Workloads

Memory-Constrained Environment

Validation

Verify Configuration

Verbose Validation

JSON Output

Configuration Best Practices

1. Start with Defaults

2. Use Configuration Files for Projects

3. Use Environment Variables for Deployment

4. Override in Code When Needed

5. Validate Configuration

Related Documentation