Skip to content

Utils Module Overview

The causaliq_core.utils module provides utility classes, enhanced enumeration functionality, mathematical utilities, random number utilities, and system utilities for common programming patterns used across the CausalIQ ecosystem.

Core Components

Mathematical Functions

Number formatting and logarithm calculations including:

  • rndsf() - Round to significant figures with precise formatting
  • ln() - Logarithm with configurable base (2, 10, or 'e')

I/O Operations

File and path handling utilities:

  • is_valid_path() - Path validation and existence checking
  • write_dataframe() - Enhanced DataFrame writing with compression and formatting

Environment Detection

System environment detection with intelligent caching:

  • environment() - Hardware and software environment information
  • Cross-platform compatibility with automatic caching

Random Number Generation

Stable, reproducible random number sequences:

  • Cross-platform reproducible sequences
  • Stable random number generation for experiments
  • Random integer iterators
  • Experiment randomization enums

Timing Utilities

Performance measurement and timeout functionality:

  • Timing class for performance measurement
  • run_with_timeout() and @with_timeout for algorithm timeouts
  • Thread-safe execution with configurable timeouts

Enhanced Enumerations

EnumWithAttrs 

EnumWithAttrs(_: str, label: str)

Base class for enumerations with additional read-only attributes.

This class extends the standard Python Enum to support enums that carry additional attributes such as human-readable labels. Sub-classes can extend this pattern to include more attributes.

Example

class Status(EnumWithAttrs): ... PENDING = 'pending', 'Pending Review' ... APPROVED = 'approved', 'Approved for Use' ... REJECTED = 'rejected', 'Rejected - Needs Changes'

print(Status.PENDING) # 'pending' print(Status.PENDING.label) # 'Pending Review'

Note

Values should be set as tuples where the first element is the enum value and subsequent elements are the additional attributes. The base class provides a label attribute from the second tuple element.

Parameters:

  • _

    (str) –

    The enum value (already set in new)

  • label

    (str) –

    Human-readable label for this enum value

Methods:

  • __new__ –

    Create a new enum instance with additional attributes.

  • __str__ –

    Return the string representation of the enum value.

Attributes:

  • label (str) –

    Get the human-readable label for this enum value.

label property 

label: str

Get the human-readable label for this enum value.

Returns:

  • str –

    The label string for this enum value

__new__ 

__new__(*args: Any, **kwargs: Any) -> EnumWithAttrs

Create a new enum instance with additional attributes.

Parameters:

  • *args

    (Any, default: () ) –

    The enum value and additional attribute values

  • **kwargs

    (Any, default: {} ) –

    Additional keyword arguments (unused)

Returns:

  • EnumWithAttrs –

    New enum instance with the value set to the first argument

__str__ 

__str__() -> str

Return the string representation of the enum value.

Returns:

  • str –

    The enum's value as a string

Usage Pattern

The utils module is designed as a consolidated toolkit for common programming patterns:

# Mathematical operations
from causaliq_core.utils import rndsf, ln

# Environment detection  
from causaliq_core.utils import environment

# Enhanced enums
from causaliq_core.utils import EnumWithAttrs

# Timing and random numbers in submodules
from causaliq_core.utils.timing import Timing
from causaliq_core.utils.random import stable_random

Module Structure

  • Main Module (causaliq_core.utils): Core functions and enhanced enums
  • Random Submodule (causaliq_core.utils.random): Random number utilities
  • Timing Submodule (causaliq_core.utils.timing): Performance and timeout utilities

For detailed API documentation, see the specialized pages linked above.