Examples: Basic

Epochly Examples: Basic: Configuration Examples

Practical configuration examples: environment variables, programmatic setup, per-function overrides, and config files.

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

GPU Configuration

# Enable GPU acceleration
export EPOCHLY_GPU_ENABLED=true
# Set memory limit (MB)
export EPOCHLY_MEMORY_LIMIT=4096

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_LOG_LEVEL=WARNING

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,
    # JIT settings
    jit_enabled=True,
    # GPU settings
    gpu_enabled=False,
    memory_limit=4096,
    # Logging settings
    log_level='INFO',
    # Other settings
    auto_optimize=True,
    profile_enabled=False,
    telemetry=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
# Use monitoring context
with epochly.monitoring_context():
    # Run your code
    result = compute_heavy_task()
# Get metrics
metrics = epochly.get_metrics()
print(f"Total time: {metrics.get('total_time', 0):.3f}s")
print(f"Function calls: {metrics.get('total_calls', 0)}")

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
  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

Export Configuration

# Export to file
epochly config export > my-config.toml
# Export as JSON
epochly config export --format json > epochly-config.json

Import Configuration

# Import from file
epochly config import my-config.toml
# Import from file (overrides current settings)
epochly config import my-config.toml

Configuration File (epochly.toml)

Create an epochly.toml file in your project directory:

# epochly.toml - Full configuration example
[epochly]
# Enhancement level (0-4)
enhancement_level = 2
# Optimization mode (off, monitor, conservative, balanced, aggressive)
mode = "balanced"
# Maximum number of workers (1-256)
max_workers = 8
# Enable anonymous telemetry
telemetry = true
# Enable debug output
debug = false
[epochly.jit]
# JIT backend selection
backend = "auto"
# Enable JIT cache
cache_enabled = true
# Hot path threshold (calls before compilation)
hot_path_threshold = 100
[epochly.memory]
# Memory pool type
pool_type = "adaptive"
# Shared memory size
shared_memory_size = "16MB"
[epochly.monitoring]
# Enable performance monitoring
enabled = true
# Export format
export_format = "json"
[epochly.gpu]
# Enable GPU acceleration
enabled = false
# GPU memory limit
memory_limit = "4GB"
# Workload threshold for GPU offload
workload_threshold = 10000

Minimal Configuration File

# .epochly.toml - Minimal configuration
[epochly]
enhancement_level = 2
mode = "balanced"
max_workers = 8

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 environment variable to specify custom config file
export EPOCHLY_CONFIG_FILE=/path/to/custom.toml
python script.py

# In Python, configure via API
import epochly
epochly.configure(enhancement_level=2, mode='balanced')

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,
    log_level='DEBUG'
)

# 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,
    jit_enabled=True,
    log_level='WARNING'
)

# production.toml
[epochly]
mode = "conservative"
max_workers = 4

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,
    memory_limit=8192,
    max_workers=4  # Limit CPU workers when using GPU
)

# Via environment
export EPOCHLY_LEVEL=4
export EPOCHLY_GPU_ENABLED=true
export EPOCHLY_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
)

# memory-constrained.toml
[epochly]
enhancement_level = 1
max_workers = 2
[epochly.jit]
enabled = false

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
Configuration file: ./epochly.toml
  [epochly]
    enhancement_level = 2
    mode = "balanced"
    max_workers = 8
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": "0.4.x",
  "python_version": "3.12.x",
  "configuration": {
    "enhancement_level": 2,
    "mode": "balanced",
    "max_workers": 8,
    "jit_enabled": true,
    "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
[epochly]
enhancement_level = 2
mode = "balanced"
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 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