Skip to content

Cache Management

Utilities for controlling the symbol cache path, inspecting statistics, and managing cache state.

Overview

Yuzuha maintains three persistent SQLite databases:

Database File Content
CG basis cache .yuzuha/cgbasis.db (edges, alphas) → canonical basis array
X-symbol cache .yuzuha/xsymbol.db (spec_a, spec_b, contraction) → (x_array, spec_c)
R-symbol cache .yuzuha/rsymbol.db (spec, permutation) → (r_array, spec_permuted)

All three databases are created automatically on first use and are thread-safe.

Cache Path

The cache directory is resolved in the following priority order:

  1. Thread-local override (set by TestCacheContext) — highest priority
  2. Environment variable: YUZUHA_CACHE_PATH
  3. Default: .yuzuha/ in the current working directory

Setting the Cache Path

import yuzuha

# Set via Python
yuzuha.set_cache_path('/path/to/cache')

# Or via environment variable (before importing yuzuha)
# export YUZUHA_CACHE_PATH=/path/to/cache

API Reference

set_cache_path

set_cache_path 

set_cache_path(path: Optional[str]) -> None

Set the cache directory path programmatically.

Parameters:

Name Type Description Default
path str or None

Cache directory path. If None, uses default.

 required

reset_caches

reset_caches 

reset_caches() -> None

Reset global cache instances.

This is useful for testing to ensure clean state between tests.

clear_all_caches

clear_all_caches 

clear_all_caches() -> None

Clear all symbol caches (X-symbol and R-symbol).

This removes all cached entries from both databases but keeps the database files and schema intact.

Examples:

>>> import yuzuha
>>> from yuzuha.cache import clear_all_caches
>>> clear_all_caches()

get_cache_stats

get_cache_stats 

get_cache_stats() -> dict

Get statistics for all symbol caches.

Returns:

Type Description
dict

Dictionary with keys 'xsymbol' and 'rsymbol', each containing cache statistics (size, db_path, db_size_bytes).

Examples:

>>> import yuzuha
>>> from yuzuha.cache import get_cache_stats
>>> stats = get_cache_stats()
>>> print(f"X-symbol cache has {stats['xsymbol']['size']} entries")
>>> print(f"R-symbol cache has {stats['rsymbol']['size']} entries")

print_cache_stats 

print_cache_stats() -> None

Print a formatted summary of cache statistics.

This is a convenience function for quickly inspecting cache status.

Examples:

>>> import yuzuha
>>> from yuzuha.cache import print_cache_stats
>>> print_cache_stats()
X-symbol cache:
  Entries: 42
  Database: .yuzuha/xsymbol.db
  Size: 1.2 MB
R-symbol cache:
  Entries: 18
  Database: .yuzuha/rsymbol.db
  Size: 0.5 MB

TestCacheContext

TestCacheContext 

TestCacheContext()

Context manager for isolated cache testing.

Creates temporary cache directories for tests to ensure isolation.

Examples:

>>> with TestCacheContext():
...     # All cache operations use temporary directory
...     x_array, spec_c = compute_xsymbol(spec_a, spec_b, contraction)

Usage Examples

Inspecting Cache State

import yuzuha

# Print a human-readable summary
yuzuha.print_cache_stats()
# X-symbol cache:
#   Entries: 42
#   Database: .yuzuha/xsymbol.db
#   Size: 1.2 MB
# R-symbol cache:
#   Entries: 18
#   Database: .yuzuha/rsymbol.db
#   Size: 0.5 MB

# Or get the raw dict
stats = yuzuha.get_cache_stats()
print(stats['xsymbol']['size'])        # number of cached X-symbols
print(stats['rsymbol']['db_path'])     # path to R-symbol database

Clearing Caches

# Clear all symbol caches (keeps database files, removes entries)
yuzuha.clear_all_caches()

Isolated Cache for Testing

import yuzuha
from yuzuha import TestCacheContext

with TestCacheContext():
    # All cache operations use an isolated temporary directory
    x, spec_c = yuzuha.compute_xsymbol(spec_a, spec_b, contraction)
# Temporary cache is cleaned up automatically on exit

See Also

Notes

reset_caches() closes and destroys the in-memory cache objects so that the next call to compute_xsymbol or compute_rsymbol opens a fresh connection. It does not delete the database files. Use clear_all_caches() to remove cached entries while preserving the file and schema.