recency_proportional_resolution_curbed_algo

Eagerly utilize fixed stratum storage capacity size_curb to minimize recency-proportional MRCA uncertainty.

The curbed recency-proportional resolution policy ensures that retained stratum count respects a user-specified size cap. Recency-proportional MRCA resolution is provided at finest-possible granularity given space constraint with graceful degradation of granularity occuring as deposition history grows.

This policy works by splicing together successively-sparser recency_proportional_resolution_algo parameterizations then — after the stratum retention count upper bound of the sparsest recency_proportional_resolution_algo exceeds storage capacity — a permanently fixed parameterization of the geometric_seq_nth root algorithm.

While

num_depositions < 2 ** (size_curb // 3) // 2,

recency_proportional_resolution_algo policies apply with resolution

size_curb // ceil(log2(num_depisitons)) - 1.

For

num_depisitons > 2 ** (size_curb // 3) // 2,

a geometric_sequence_nth_root_algorithm policy with degree

(size_curb - 2) // 6

and interspersal 2 applies. To ensure availability of ranks required by the geometric_sequence_nth_root_algorithm, the transition between algorithms occurs exactly before recency-proportional resolution 1 would apply.

Because strata retained by each policy supersets strata retained by all subsequent retention policies, uncertainty bounds for all policies apply within their respective domains. (I.e., all strata expected by each policy are available when that policy activates.)

Although the geometric sequence nth root algorithm also guarantees constant space complexity with recency-proportional MRCA uncertainty, the curbed recency- proportional algorithm makes fuller (i.e., more aggressive) use of available space during early depositions.

The curbed recency-proportional algorithm also compares favorably to the tapered geometric sequence nth root algorithm during early depositions. Although the tapered nth root algorithm makes the fullest (i.e., most aggressive) use of available space — upper bound capacity is always perfectly utilized — the used space is less effective at minimizing worst-case recency- proportional resolution than the curbed algorithm. (I.e., the tapered nth root algorithm provides patchier, less systematic coverage.)

Notes

Only size caps of eight strata and above are guaranteed respected. (Initialization of smaller size caps will warn.)

See Also

recency_proportional_resolution_algo:

Provides log space complexity and recency-proportional strata spacing.

geom_seq_nth_root_algo:

Provides constant space complexity and MRCA rank estimate uncertainty bounded under s * (1 - n^(-1/k)) where n is the number of strata deposited and s is the true number of ranks deposited since the MRCA.

geom_seq_nth_root_tapered_algo:

Perfectly space-filling variant of geom_seq_nth_root_algo.

Classes

CalcMrcaUncertaintyAbsExact	Functor to provide member function implementation in Policy class.
CalcMrcaUncertaintyAbsUpperBound	alias of CalcMrcaUncertaintyAbsUpperBoundWorstCase
CalcMrcaUncertaintyAbsUpperBoundAtPessimalRank
CalcMrcaUncertaintyAbsUpperBoundPessimalRank	Functor to provide member function implementation in Policy class.
CalcMrcaUncertaintyRelExact	alias of CalcMrcaUncertaintyRelExactFromAbs
CalcMrcaUncertaintyRelUpperBound	alias of CalcMrcaUncertaintyRelUpperBoundWorstCase
CalcMrcaUncertaintyRelUpperBoundAtPessimalRank
CalcMrcaUncertaintyRelUpperBoundPessimalRank	Functor to provide member function implementation in Policy class.
CalcNumStrataRetainedExact	Functor to provide member function implementation in Policy class.
CalcNumStrataRetainedUpperBound	Functor to provide member function implementation in Policy class.
CalcRankAtColumnIndex	Functor to provide member function implementation in Policy class.
GenDropRanks	Functor to implement the recency-proportional resolution stratum retention policy, for use with HereditaryStratigraphicColumn.
IterRetainedRanks	Functor to provide member function implementation in Policy class.
Policy	alias of Policy
PolicySpec	Contains all policy parameters, if any.

class CalcMrcaUncertaintyAbsExact

Functor to provide member function implementation in Policy class.

__call__(policy: PolicyCouplerBase, first_num_strata_deposited: int, second_num_strata_deposited: int, actual_rank_of_mrca: int) → int

Exactly how much uncertainty to estimate rank of MRCA?

__init__(policy_spec: PolicySpec | None) → None

CalcMrcaUncertaintyAbsUpperBound

alias of CalcMrcaUncertaintyAbsUpperBoundWorstCase

class CalcMrcaUncertaintyAbsUpperBoundAtPessimalRank

__call__(policy: PolicyCouplerBase, first_num_strata_deposited: int, second_num_strata_deposited: int) → int

Calculate absolute MRCA uncertainty at pessimal rank.

__init__(policy_spec: Any | None = None) → None

class CalcMrcaUncertaintyAbsUpperBoundPessimalRank

Functor to provide member function implementation in Policy class.

__call__(policy: PolicyCouplerBase, first_num_strata_deposited: int | None, second_num_strata_deposited: int | None) → int

Calculate rank for which upper bound on absolute MRCA uncertainty is pessimized.

__init__(policy_spec: PolicySpec | None) → None

CalcMrcaUncertaintyRelExact

alias of CalcMrcaUncertaintyRelExactFromAbs

CalcMrcaUncertaintyRelUpperBound

alias of CalcMrcaUncertaintyRelUpperBoundWorstCase

class CalcMrcaUncertaintyRelUpperBoundAtPessimalRank

__call__(policy: PolicyCouplerBase, first_num_strata_deposited: int, second_num_strata_deposited: int) → float

Calculate relative MRCA uncertainty at pessimal rank.

__init__(policy_spec: Any | None = None) → None

class CalcMrcaUncertaintyRelUpperBoundPessimalRank

Functor to provide member function implementation in Policy class.

__call__(policy: PolicyCouplerBase, first_num_strata_deposited: int, second_num_strata_deposited: int) → int

Calculate rank for which upper bound on relative MRCA uncertainty is pessimized.

__init__(policy_spec: PolicySpec | None) → None

class CalcNumStrataRetainedExact

Functor to provide member function implementation in Policy class.

__call__(policy: PolicyCouplerBase, num_strata_deposited: int) → int

Exactly how many strata are retained after n deposited?

__init__(policy_spec: PolicySpec | None) → None

class CalcNumStrataRetainedUpperBound

Functor to provide member function implementation in Policy class.

__call__(policy: PolicyCouplerBase, num_strata_deposited: int) → int

At most, how many strata are retained after n deposited? Inclusive.

__init__(policy_spec: PolicySpec | None = None) → None

class CalcRankAtColumnIndex

Functor to provide member function implementation in Policy class.

__call__(policy: PolicyCouplerBase, index: int, num_strata_deposited: int | None) → int

After n strata have been deposited, what will the rank of the stratum at column index k be?

Enables a HereditaryStratigraphicColumn using this predicate to optimize away storage of rank annotations on strata. Takes into the account the possibility for in-progress stratum depositions that haven’t been reflected in num_strata_deposited.

__init__(policy_spec: PolicySpec | None) → None

class GenDropRanks

Functor to implement the recency-proportional resolution stratum retention policy, for use with HereditaryStratigraphicColumn.

This functor enacts the recency-proportional resolution policy by specifying the set of strata ranks that should be purged from a hereditary stratigraphic column when the nth stratum is deposited.

__call__(policy: PolicyCouplerBase, num_stratum_depositions_completed: int, retained_ranks: Iterable[int] | None) → Iterator[int]

Decide which strata within the stratagraphic column should be purged.

Every time a new stratum is deposited, this method is called to determine which strata should be purged. All strata at ranks yielded from this functor are immediately purged from the column, meaning that for a stratum to persist it must not be yielded by this functor each and every time a new stratum is deposited.

Parameters

policy: Policy

Policy this functor enacts.

num_stratum_depositions_completedint

The number of strata that have already been deposited, not including the latest stratum being deposited which prompted the current purge operation.

retained_ranksiterator over int

An iterator over ranks of strata currently retained within the hereditary stratigraphic column. Not used in this functor.

Returns

iterator over int

The ranks of strata that should be purged from the hereditary stratigraphic column at this deposition step.

See Also

recency_proportional_resolution_curbed_algo:

For details on the rationale, implementation, and guarantees of the recency-proportional resolution stratum retention policy.

__init__(policy_spec: PolicySpec | None) → None

class IterRetainedRanks

Functor to provide member function implementation in Policy class.

__call__(policy: PolicyCouplerBase, num_strata_deposited: int) → Iterator[int]

Iterate over retained strata ranks at num_strata_deposited in ascending order.

__init__(policy_spec: PolicySpec | None) → None

Policy

alias of Policy

class PolicySpec

Contains all policy parameters, if any.

static GetAlgoIdentifier() → str

Get programatic name for underlying retention algorithm.

static GetAlgoTitle() → str

Get human-readable name for underlying retention algorithm.

GetEvalCtor() → str

GetSizeCurb() → int

__init__(size_curb: int) → None

Construct the policy spec.

Parameters

size_curbint, optional

Fixed, hard-limited stratum storage capacity to make best use of.

Inclusive. Only size caps of eight strata and above are guaranteed respected. (Initialization of smaller size caps will warn.)

__repr__() → str

Return repr(self).

__str__() → str

Return str(self).