qlat_utils.lru_cache — Fixed-Capacity LRU Cache

Source: qlat-utils/qlat_utils/lru_cache.py

Note: Update this document when updating the source file.

Outline

1. Overview

2. API

3. Examples

---

Overview

The qlat_utils.lru_cache module provides LRUCache, a fixed-capacity Least Recently Used cache backed by collections.OrderedDict. All operations (lookup, insertion, update) run in O(1) time.

When the cache reaches its capacity, inserting a new item automatically evicts the least recently accessed entry. Accessing an item (via get or []) moves it to the most-recently-used position.

---

API

class LRUCache(capacity: int)

Parameter	Type	Description
capacity	int	Maximum number of entries the cache can hold

Attributes

Attribute	Type	Description
cache	OrderedDict	Internal storage
capacity	int	Maximum number of entries

get(key, default=None)

Return the value for key, or default if not found. Moves the key to the most-recently-used position on hit.

__getitem__(key)

Return the value for key. Raises KeyError if not found. Moves the key to the most-recently-used position.

__setitem__(key, value)

Insert or update key with value. Moves the key to the most-recently-used position. If the cache exceeds capacity, evicts the least recently used entry.

__contains__(key)

Return True if key is in the cache. Does not affect recency order.

clear()

Remove all entries from the cache.

---

Examples

Basic Usage

import qlat_utils as q

cache = q.LRUCache(capacity=3)

cache["a"] = 1
cache["b"] = 2
cache["c"] = 3

print(cache["a"])  # 1; "a" is now most recent

cache["d"] = 4     # evicts "b" (least recent)

print("b" in cache)  # False
print(cache.get("b"))  # None

Gauge Field Caching

import qlat_utils as q

# Cache up to 4 gauge configurations
gauge_cache = q.LRUCache(capacity=4)

for traj in range(10):
    gf = load_gauge_field(traj)  # hypothetical loader
    gauge_cache[traj] = gf
    # Old trajectories are evicted automatically

Checking Eviction Order

import qlat_utils as q

c = q.LRUCache(2)
c["x"] = 10
c["y"] = 20
_ = c["x"]       # touch "x" → "y" is now LRU
c["z"] = 30      # evicts "y"

print("y" in c)  # False
print(c["x"])    # 10
print(c["z"])    # 30