Database¶

Pre-population of the canonical basis cache for common spin configurations.

startup_database ¶

startup_database(logger: Optional[Logger] = None, log_level: int = logging.INFO) -> None

Pre-compute and cache CG bases for commonly used spin configurations.

This function computes and caches: 1. 3rd order bases: one spin is 1/2 or 1, other two spins up to spin-3 2. 4th order bases: two spins are 1/2, other two spins up to spin-3

The database is automatically populated when bases are computed for the first time. Subsequent calls will use the cached values.

Parameters:

Name	Type	Description	Default
`logger`	`Logger`	Logger instance to use. If None, creates a default stream logger.	`None`
`log_level`	`int`	Logging level to use for the default logger. Default is logging.INFO.	`INFO`

Examples:

>>> import yuzuha
>>> yuzuha.startup_database()

>>> # With custom logger
>>> import logging
>>> logger = logging.getLogger('my_app')
>>> yuzuha.startup_database(logger=logger)

Description¶

startup_database() pre-computes and caches the canonical CG bases for a standard set of spin configurations that are commonly encountered in tensor network applications:

3rd-order bases: One spin in \(\{1/2, 1\}\), two spins in \(\{1/2, 1, 3/2, 2, 5/2, 3\}\) — all 3! orderings of each triplet
4th-order bases: Two spins fixed at \(1/2\), two spins in \(\{1/2, 1, 3/2, 2, 5/2, 3\}\) — all \(\binom{4}{2} = 6\) positions for the two fixed spins

Calling this function at application startup avoids cache-miss latency during the first computation of each configuration.

Usage¶

import yuzuha

# Basic usage — pre-populate with default logging
yuzuha.startup_database()

# With a custom logger
import logging
logger = logging.getLogger('my_app')
yuzuha.startup_database(logger=logger)

# Suppress output
yuzuha.startup_database(log_level=logging.WARNING)

Progress Logging¶

By default, startup_database logs progress at INFO level through the yuzuha.database logger. Log messages include:

Number of configurations to process
Current progress (every 10 configs)
Configurations skipped due to triangle inequality violations
Final count of successes and failures

When to Call¶

startup_database() is optional — the cache is populated automatically on first use. Call it explicitly if you want:

Predictable latency from the start of a computation
Logged progress for long-running pre-computation

Database Location¶

The canonical basis cache is managed by the Rust layer and stored in a SQLite database alongside the other Yuzuha caches. The location is controlled by:

Thread-local test override (for test isolation)
YUZUHA_CACHE_PATH environment variable
Default: .yuzuha/ in the current working directory

Notes¶

Triangle inequality violations are silently skipped — configurations where no valid internal spin coupling exists (e.g. three spins where no triplet satisfies the triangle inequality) are logged at DEBUG level and omitted from the count.

Configurations already in the database are not recomputed; subsequent calls to startup_database are idempotent.