Cost estimator

estimate_cost(parent::ParentLattice{D}, sites::Sites{D};
              supercells::SupercellSelection,
              concentration = nothing,
              algorithm::Symbol = :auto,
              include_superperiodic::Bool = false) -> EnumerationCostEstimate

Predict the cost of enumerate(...) before running it. Useful as a manual size check (call it yourself to see what enumerate would allocate) and as the engine behind enumerate(...)'s built-in enumeration resource check (which calls it internally to decide whether to proceed).

Returns an EnumerationCostEstimate with the predicted structure count, peak-memory prediction, chosen algorithm, selection kind, partition count, and any advisory notes. See research.md §7.2.

Cost: same as count_inequivalent(...) — milliseconds even for hundreds of supercells. The Pólya count is the dominant term; per-algorithm memory is closed-form.

Examples

Sizing a request before running it is the function's primary purpose. The example below shows the gate firing: an unrestricted FCC binary enumeration at volume 20 is predicted to need ~138 MiB, far beyond the artificially-tiny memory_budget = 1 byte we pass in to trigger EnumerationTooLargeError.

julia> p = ParentLattice([0.0 0.5 0.5; 0.5 0.0 0.5; 0.5 0.5 0.0]);

julia> sites = Sites([Site([0.0, 0.0, 0.0], [0, 1])]);

julia> try
           enumerate(p, sites; supercells = VolumeRange(20:20), memory_budget = 1)
       catch e
           e isa EnumerationTooLargeError || rethrow()
           format_bytes(e.estimate.peak_memory_bytes)
       end
"137.56 MiB"

EnumerationCostEstimate

Resource-cost prediction returned by estimate_cost. The enumeration resource check inside enumerate(...) consults this struct to decide whether to proceed or throw EnumerationTooLargeError.

Fields:

• total_count::BigInt — predicted number of inequivalent structures, honoring the same include_superperiodic kwarg the user passed. Computed via the Pólya machinery.
• peak_memory_bytes::Int — worst-case peak memory for the chosen algorithm. For :exhaustive: max over HNFs of bitmap_bytes(k^n) + output_so_far. For :multinomial: max over (HNF, concentration) of bitmap_bytes(C_multinomial) + output_so_far. Output-buffer term is approximated by total_count × sizeof(EnumeratedStructure{D, Vector{Int8}}) — a safe upper bound at end-of-run.
• chosen_algorithm::Symbol — what :auto resolved to (or the explicit algorithm passed). One of :exhaustive, :multinomial, :multinomial_restricted, :recursive_stabilizer.
• selection_kind::Symbol — :volume_range, :radius_bound, or :explicit_hnfs. Lets error messages suggest an appropriately-shaped mitigation.
• partition_count::Int — number of distinct multiplicity vectors when a ConcentrationRange was supplied; 1 otherwise.
• notes::Vector{String} — advisory messages: which algorithm :auto picked, etc.

EnumerationTooLargeError(estimate::EnumerationCostEstimate, budget_bytes::Int)

Thrown by enumerate(...) when the predicted EnumerationCostEstimate's peak_memory_bytes exceeds the configured memory_budget. Carries the full estimate so the user can see exactly what would have been allocated, plus the budget that was tripped.

The gate is on_overflow = :error by default; expert users can pass :warn (warns but proceeds) or :ignore (silent pass-through), or set skip_resource_check = true to bypass the estimator entirely.

format_bytes(n::Integer) -> String

Format a byte count as a human-readable string with the largest unit ≥ 1. Uses binary (1024-based) units to match how memory budgets are typically reported. Two-decimal precision; rounds toward zero for the unit selection.

Examples

julia> format_bytes(0)
"0 B"

julia> format_bytes(1023)
"1023 B"

julia> format_bytes(1024)
"1.00 KiB"

julia> format_bytes(1024^2)
"1.00 MiB"

julia> format_bytes(1024^3)
"1.00 GiB"

julia> format_bytes(1024^4)
"1.00 TiB"