physics.agents
physics.agents
Agentic ML systems physics and memory accounting formulas (Volume III).
Functions
| Name | Description |
|---|---|
| calc_append_only_context | Count final and cumulative input tokens in an append-only trajectory. |
| calc_bounded_liability | Calculate the largest token bill allowed for one model call. |
| calc_break_even_acceptance | Find the acceptance rate equivalent to a component price cut. |
| calc_cleanup_critical_path | Calculate elapsed cleanup time under unlimited parallelism. |
| calc_cost_per_accepted | Calculate expected cost per accepted task. |
| calc_cost_per_rejection | Calculate checking cost per rejected record. |
| calc_drr_calls_per_round | Calculate the long-run call rate under deficit round-robin credit. |
| calc_expected_irreversible_loss | Calculate expected loss remaining after recovery. |
| calc_expected_max_std_normal | Integrate the expected maximum of independent standard normals. |
| calc_first_horizon_below | Find the first whole horizon below a success threshold. |
| calc_independent_success | Calculate the chance that at least one independent attempt passes. |
| calc_injection_exposure | Calculate exposure probability across independent untrusted reads. |
| calc_injection_read_budget | Find the largest read budget within an exposure limit. |
| calc_kv_cache_bytes_per_token | Calculate the key/value cache footprint per token. |
| calc_mixed_outcome_fraction | Calculate the probability that a group contains both outcomes. |
| calc_nucleus | Select and renormalize the top-p probability nucleus. |
| calc_pass_at_k_unbiased | Estimate the probability that a size-k sample contains a pass. |
| calc_pass_posterior | Calculate the defective share of passing candidates. |
| calc_pass_pow_k_unbiased | Estimate the chance that every run in a size-k sample passes. |
| calc_pruned_tree_nodes | Count proposed search nodes with and without independent pruning. |
| calc_repair_break_even | Find the repair success rate that breaks even with fallback. |
| calc_repair_first_expected_cost | Calculate expected cost when one repair precedes fallback. |
| calc_reused_prefix_prompt_tokens | Count newly prefetched tokens with full prefix reuse. |
| calc_setup_share | Calculate the setup share of serial call time. |
| calc_short_circuit_cost | Calculate the cost and survival share of ordered checks. |
| calc_split_straddle | Calculate the chance that repeated task runs straddle a split. |
| calc_step_error_for_target | Find the per-step error rate allowed by a task success target. |
| calc_tempered_softmax | Normalize temperature-scaled logits into sampling probabilities. |
| calc_unchecked_success | Calculate unchecked task success from per-step success. |
| calc_used_fraction | Calculate the consumed fraction of one budget dimension. |
| calc_work_for_setup_cap | Find useful work needed to cap the setup share. |
calc_append_only_context
physics.agents.calc_append_only_context(initial_tokens, tokens_per_turn, turns)Count final and cumulative input tokens in an append-only trajectory.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| initial_tokens | Quantity or int | Nonnegative tokens in the first request. | required |
| tokens_per_turn | Quantity or int | Nonnegative tokens appended between successive requests, using the same units as initial_tokens. | required |
| turns | int | Positive number of requests in the trajectory. | required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | Last-request token count and cumulative input-token count, retaining input units. |
Notes
Equation: last = s0 + delta (H - 1); total = H s0 + delta H (H - 1) / 2.
Assumptions: Every request resends the full earlier context; append size is constant.
Excludes: Prefix caching, compaction, request-window limits, and output-token billing.
References
Derivation: Sum the arithmetic progression s0, s0 + delta, …, s0 + (H - 1) delta.
Examples
>>> last, total = calc_append_only_context(10, 2, 3)
>>> (last, total) == (10 + 2 * 2, sum([10, 12, 14]))
Truecalc_bounded_liability
physics.agents.calc_bounded_liability(
input_tokens,
output_allowance,
input_price,
output_price,
)Calculate the largest token bill allowed for one model call.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| input_tokens | Quantity or int | Nonnegative number of input tokens to charge. | required |
| output_allowance | Quantity or int | Nonnegative maximum permitted output-token count. | required |
| input_price | Quantity or float | Undiscounted input price per token in the chosen currency. | required |
| output_price | Quantity or float | Output price per token in the same currency. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity or float | Maximum token bill under the stated rates and allowance. |
Notes
Equation: L = n_input p_input + K_output p_output.
Assumptions: Every input token is billed at its listed rate and output remains within its allowance.
Excludes: Tool charges, taxes, dynamic pricing, and guaranteed cache discounts.
References
Derivation: Add the input invoice and the largest permitted output invoice.
Examples
>>> calc_bounded_liability(10, 5, 2, 3) == 10 * 2 + 5 * 3
Truecalc_break_even_acceptance
physics.agents.calc_break_even_acceptance(acceptance_probability, cut, share)Find the acceptance rate equivalent to a component price cut.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| acceptance_probability | float | Current acceptance probability in [0, 1]. | required |
| cut | float | Fractional reduction of the selected cost component in [0, 1]. | required |
| share | float | Selected component share of total attempt cost in [0, 1]; cut * share must be below 1. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Required acceptance probability; a value above 1 means the target is unattainable. |
Notes
Equation: p_new = p_accept / (1 - cut * share).
Assumptions: The price cut changes cost but not acceptance; raising acceptance leaves attempt cost unchanged.
Excludes: Interactions between quality and price, and clipping an unattainable target to 1.
References
Derivation: Equate C / p_new with C (1 - cut share) / p_accept and cancel C.
Examples
>>> calc_break_even_acceptance(0.5, cut=0.5, share=0.5) == 0.5 / 0.75
Truecalc_cleanup_critical_path
physics.agents.calc_cleanup_critical_path(durations, depends_on)Calculate elapsed cleanup time under unlimited parallelism.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| durations | mapping | Nonempty operation-to-duration mapping with nonnegative values in compatible units. | required |
| depends_on | mapping | Operation-to-prerequisite iterable mapping; every prerequisite must occur in durations and the graph must be acyclic. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity or float | Longest-path elapsed time, retaining the duration unit. |
Notes
Equation: finish(v) = duration(v) + max_{u in parents(v)} finish(u); elapsed = max_v finish(v).
Assumptions: Unlimited parallel execution of ready operations; prerequisite settlement is mandatory.
Excludes: Resource contention, scheduling overhead, retries, and cyclic dependency resolution.
References
Derivation: A topological earliest-finish recurrence yields the critical path; serial rollback instead sums all durations.
Examples
>>> calc_cleanup_critical_path({'a': 2, 'b': 3, 'c': 1}, {'c': ['a', 'b']}) == max(2, 3) + 1
Truecalc_cost_per_accepted
physics.agents.calc_cost_per_accepted(attempt_cost, acceptance_probability)Calculate expected cost per accepted task.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| attempt_cost | Quantity or float | Expected cost of one attempt; retain the chosen unit, such as seconds or dollars. | required |
| acceptance_probability | float | Independent per-attempt acceptance probability in (0, 1]. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity or float | Expected cost per accepted task, in the attempt-cost unit. |
Notes
Equation: C_accepted = C_attempt / p_accept.
Assumptions: Attempts repeat until acceptance with fixed expected cost and success probability.
Excludes: Retry limits, dependencies between attempts, and changes in cost after failure.
References
Derivation: A geometric number of attempts has mean 1 / p_accept.
Examples
>>> from mlsysim.core.units import ureg
>>> calc_cost_per_accepted(2 * ureg.second, 0.5) == 4 * ureg.second
Truecalc_cost_per_rejection
physics.agents.calc_cost_per_rejection(check_cost, pass_probability)Calculate checking cost per rejected record.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| check_cost | Quantity or float | Nonnegative per-record checking cost in any additive resource unit. | required |
| pass_probability | float | Check pass probability in [0, 1); rejection must have positive probability. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity or float | Expected checking cost per rejected record, in check_cost units. |
Notes
Equation: C_rejection = C_check / (1 - p_pass).
Assumptions: Identically distributed records and fixed per-record check cost.
Excludes: Dependence between checks and selectivity changes after earlier checks.
References
Derivation: A geometric number of checked records is required for each rejection; adjacent independent checks favor lower cost per rejection.
Examples
>>> calc_cost_per_rejection(2, 0.5) == 4
Truecalc_drr_calls_per_round
physics.agents.calc_drr_calls_per_round(weight, quantum, charge)Calculate the long-run call rate under deficit round-robin credit.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| weight | float | Nonnegative dimensionless class weight. | required |
| quantum | float | Nonnegative credit allocated per round, in charge units. | required |
| charge | float | Positive credit consumed by one call, in the same units as quantum. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Long-run average admitted calls per scheduling round. |
Notes
Equation: calls_per_round = weight * quantum / charge.
Assumptions: A continuously backlogged class, fixed per-call charge, and unspent credit carried across rounds.
Excludes: Transient integer admissions, variable call sizes, and latency guarantees.
References
Derivation: Conservation of scheduler credit equates long-run credit earned and credit spent; this is weighted deficit-round-robin accounting.
Shreedhar and Varghese (1995), “Efficient Fair Queuing Using Deficit Round Robin.” https://doi.org/10.1145/217382.217453 (bibliography key: shreedhar1995efficient).
Examples
>>> calc_drr_calls_per_round(2, 3, 4) == 2 * 3 / 4
Truecalc_expected_irreversible_loss
physics.agents.calc_expected_irreversible_loss(
defect_probability,
consequence,
recoverable_fraction,
)Calculate expected loss remaining after recovery.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| defect_probability | float | Probability of a consequential defect in [0, 1]. | required |
| consequence | Quantity or float | Nonnegative loss conditional on defect, in the chosen cost unit. | required |
| recoverable_fraction | float | Fraction of consequence avoided by recovery, in [0, 1]. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity or float | Expected residual loss, in the consequence unit. |
Notes
Equation: L = P_defect * consequence * (1 - r).
Assumptions: One defect event and a specified mean recoverable share; an upstream check can supply r = detection * rollback fidelity.
Excludes: Tail-risk bounds, repeated defects, and proof of recovery effectiveness.
References
Derivation: Multiply the event probability by the unrecoverable portion of its conditional loss.
Examples
>>> calc_expected_irreversible_loss(0.5, 8, 0.25) == 0.5 * 8 * 0.75
Truecalc_expected_max_std_normal
physics.agents.calc_expected_max_std_normal(n, lo=-10.0, hi=10.0, steps=40000)Integrate the expected maximum of independent standard normals.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | int | Positive number of independent standard-normal draws. | required |
| lo | float | Lower integration limit in standard deviations; default -10. | -10.0 |
| hi | float | Upper integration limit greater than lo; default 10. | 10.0 |
| steps | int | Positive trapezoid count; default 40000. | 40000 |
Returns
| Name | Type | Description |
|---|---|---|
| float | Approximate expected maximum, in units of the normal standard deviation. |
Notes
Equation: E[max] = integral x n phi(x) Phi(x) ** (n - 1) dx over [lo, hi].
Assumptions: Independent standard-normal score errors and a finite uniform integration grid.
Excludes: Tail mass outside the bounds, quadrature error, correlated errors, and unequal candidate means.
References
Derivation: The maximum CDF is Phi(x) ** n; differentiating gives n phi(x) Phi(x) ** (n - 1).
Examples
>>> abs(calc_expected_max_std_normal(1, steps=1000)) < 1e-10
Truecalc_first_horizon_below
physics.agents.calc_first_horizon_below(step_success, threshold)Find the first whole horizon below a success threshold.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| step_success | float | Per-step success probability strictly between 0 and 1. | required |
| threshold | float | Task success threshold strictly between 0 and 1. | required |
Returns
| Name | Type | Description |
|---|---|---|
| int | First positive whole-step horizon with task success below threshold. |
Notes
Equation: n = floor(log(threshold) / log(step_success)) + 1.
Assumptions: Identical independent step success and an exact strict inequality.
Excludes: Correlations and numerical ambiguity when logarithms lie near an integer.
References
Derivation: Solve p ** n < threshold for n; log(p) is negative, so n must exceed the log ratio.
Examples
>>> n = calc_first_horizon_below(0.5, 0.3)
>>> 0.5 ** n < 0.3 <= 0.5 ** (n - 1)
Truecalc_independent_success
physics.agents.calc_independent_success(acceptance_probability, attempts)Calculate the chance that at least one independent attempt passes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| acceptance_probability | float | Acceptance probability of each attempt in [0, 1]. | required |
| attempts | int | Nonnegative count of independent attempts. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Probability of at least one accepted attempt. |
Notes
Equation: P_any = 1 - (1 - p_accept) ** k.
Assumptions: Identical independent attempts.
Excludes: Shared failure causes, search adaptation, and dependence among attempts.
References
Derivation: Subtract the probability that every attempt fails from one.
Examples
>>> calc_independent_success(0.5, 2) == 1 - 0.5 ** 2
Truecalc_injection_exposure
physics.agents.calc_injection_exposure(payload_fraction, reads)Calculate exposure probability across independent untrusted reads.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| payload_fraction | float | Fraction of independently read items carrying a payload, in [0, 1]. | required |
| reads | float | Nonnegative number of reads; whole counts describe discrete items. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Probability of encountering at least one payload, not probability of compromise. |
Notes
Equation: P_exposure = 1 - (1 - q) ** n.
Assumptions: Identically distributed independent reads; q may include a specified screening miss fraction.
Excludes: Attack success conditional on exposure, correlated items, and adaptive attackers.
References
Derivation: Exposure is the complement of all n reads being payload-free.
Examples
>>> calc_injection_exposure(0.5, 2) == 1 - 0.5 ** 2
Truecalc_injection_read_budget
physics.agents.calc_injection_read_budget(payload_fraction, target_exposure)Find the largest read budget within an exposure limit.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| payload_fraction | float | Per-read payload probability strictly between 0 and 1. | required |
| target_exposure | float | Maximum exposure probability in [0, 1). | required |
Returns
| Name | Type | Description |
|---|---|---|
| int | Largest whole read count satisfying the modeled exposure limit. |
Notes
Equation: n_max = floor(log(1 - target) / log(1 - q)).
Assumptions: Independent identically distributed payload presence on each read.
Excludes: Correlated exposure, compromise probability, and floating-point errors near integer boundaries.
References
Derivation: Invert 1 - (1 - q) ** n <= target and take the integer floor.
Examples
>>> n = calc_injection_read_budget(0.5, 0.6)
>>> calc_injection_exposure(0.5, n) <= 0.6 < calc_injection_exposure(0.5, n + 1)
Truecalc_kv_cache_bytes_per_token
physics.agents.calc_kv_cache_bytes_per_token(
model=None,
*,
n_layers=None,
n_kv_heads=None,
head_dim=None,
bytes_per_elem=2,
)Calculate the key/value cache footprint per token.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| model | TransformerWorkload or AgentArchitecture | Architecture supplying layers, KV heads, and head width; explicit counts override it. Agent architectures are unwrapped through reference_model. | None |
| n_layers | int | Positive layer count; required when model is absent. | None |
| n_kv_heads | int | Positive key/value head count; required when model is absent. | None |
| head_dim | int | Positive elements per head; by default hidden_dim // heads, or head_dim when available, otherwise 128. | None |
| bytes_per_elem | Quantity or int | Bytes per stored cache element; default 2 represents FP16/BF16 storage. | 2 |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity | Bytes stored for one sequence token across all layers. |
Notes
Equation: m_token = 2 L H_kv d_head b, where b is bytes per element.
Assumptions: One key tensor and one value tensor share the stated shape and precision.
Excludes: Allocator metadata, padding, fragmentation, and compressed latent-attention caches.
References
Derivation: Count L H_kv d_head elements separately in keys and values, then multiply by element width.
Examples
>>> from mlsysim.core.units import ureg
>>> result = calc_kv_cache_bytes_per_token(n_layers=2, n_kv_heads=3, head_dim=4)
>>> result == 2 * 2 * 3 * 4 * 2 * ureg.byte
Truecalc_mixed_outcome_fraction
physics.agents.calc_mixed_outcome_fraction(pass_probability, attempts)Calculate the probability that a group contains both outcomes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pass_probability | float | Per-attempt success probability in [0, 1]. | required |
| attempts | int | Positive number of attempts. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Probability of observing both a success and a failure. |
Notes
Equation: P_mixed = 1 - (1 - p) ** k - p ** k.
Assumptions: Independent attempts with identical pass probability.
Excludes: Correlated attempts, reward magnitudes, and usefulness of the resulting training signal.
References
Derivation: Exclude the disjoint all-failure and all-success groups from the full outcome space.
Examples
>>> calc_mixed_outcome_fraction(0.5, 2) == 0.5
Truecalc_nucleus
physics.agents.calc_nucleus(probabilities, top_p)Select and renormalize the top-p probability nucleus.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| probabilities | iterable of float | Nonnegative normalized token probabilities with positive total mass. | required |
| top_p | float | Target retained mass in (0, 1]. | required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | Retained count, original retained mass, and normalized probabilities sorted from largest to smallest. |
Notes
Equation: Keep the smallest prefix k with sum_{i=1}^k p_sorted_i >= top_p; return p_i / retained_mass.
Assumptions: The input is a probability distribution and highest-probability tokens are retained first.
Excludes: Token identities, tie-breaking identities, temperature scaling, and quality guarantees.
References
Derivation: A descending cumulative sum finds the shortest prefix reaching the threshold; division renormalizes it.
Examples
>>> kept, mass, probs = calc_nucleus([0.5, 0.25, 0.25], 0.5)
>>> (kept, mass, probs) == (1, 0.5, [1.0])
Truecalc_pass_at_k_unbiased
physics.agents.calc_pass_at_k_unbiased(samples, passing, k)Estimate the probability that a size-k sample contains a pass.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| samples | int | Positive count n of graded samples. | required |
| passing | int | Passing sample count c in [0, n]. | required |
| k | int | Subset size in [1, n]. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Unbiased estimate of the probability at least one of k draws passes. |
Notes
Equation: pass_at_k = 1 - C(n - c, k) / C(n, k), or 1 if n - c < k.
Assumptions: Exchangeable independent draws from a fixed task distribution.
Excludes: Dependence among samples, uncertainty intervals, and changing graders.
References
Derivation: Count all-failing subsets among all size-k subsets and subtract their fraction from one; this is the combinatorial estimator described by Chen et al. (2021).
Chen et al. (2021), “Evaluating Large Language Models Trained on Code.” https://arxiv.org/abs/2107.03374 (bibliography key: chen2021evaluating).
Examples
>>> calc_pass_at_k_unbiased(4, 2, 1) == 0.5
Truecalc_pass_posterior
physics.agents.calc_pass_posterior(
defect_rate,
false_accept_rate,
valid_accept_rate,
)Calculate the defective share of passing candidates.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| defect_rate | float | Prior defective fraction in [0, 1]. | required |
| false_accept_rate | float | Probability of passing conditional on defect, in [0, 1]. | required |
| valid_accept_rate | float | Probability of passing conditional on validity, in [0, 1]; total pass probability must be positive. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Defective share among passing candidates. |
Notes
Equation: P(defect | pass) = q f / (q f + (1 - q) v).
Assumptions: Binary validity and fixed conditional checker rates.
Excludes: Distribution shift, uncertainty in checker estimates, and zero-pass populations.
References
Derivation: Bayes rule divides the joint defect-and-pass probability by total pass probability.
Examples
>>> calc_pass_posterior(0.5, 0.25, 0.75) == 0.25
Truecalc_pass_pow_k_unbiased
physics.agents.calc_pass_pow_k_unbiased(samples, passing, k)Estimate the chance that every run in a size-k sample passes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| samples | int | Positive count n of graded runs. | required |
| passing | int | Passing run count c in [0, n]. | required |
| k | int | Subset size in [1, n]. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Unbiased estimate of the probability that all k draws pass. |
Notes
Equation: pass_pow_k = C(c, k) / C(n, k), or 0 if c < k.
Assumptions: Exchangeable independent draws from a fixed task distribution.
Excludes: Sample dependence, grader uncertainty, and confidence intervals.
References
Derivation: Count all-passing subsets among all size-k subsets; its expectation under independent draws is p ** k.
Yao et al. (2024), “tau-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains.” https://arxiv.org/abs/2406.12045 (bibliography key: yao2024taubench).
Examples
>>> calc_pass_pow_k_unbiased(4, 2, 1) == 0.5
Truecalc_pruned_tree_nodes
physics.agents.calc_pruned_tree_nodes(branching, rejection_rate, depth)Count proposed search nodes with and without independent pruning.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| branching | int | Nonnegative child count proposed per retained node. | required |
| rejection_rate | float | Independent rejection probability in [0, 1]. | required |
| depth | int | Nonnegative number of child levels, excluding the root. | required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | Unpruned node count and expected proposed node count with pruning; neither includes the root. |
Notes
Equation: unpruned = sum_d b ** d; pruned = sum_d b [b (1 - r)] ** (d - 1).
Assumptions: Constant branching, independent rejection, and no expansion of rejected nodes.
Excludes: Checker execution cost, adaptive branching, and variance in realized tree size.
References
Derivation: At each level the expected retained-parent count grows by b (1 - r), then each parent proposes b children.
Examples
>>> full, pruned = calc_pruned_tree_nodes(2, 0.0, 3)
>>> full == pruned
Truecalc_repair_break_even
physics.agents.calc_repair_break_even(repair_cost, fallback_cost)Find the repair success rate that breaks even with fallback.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| repair_cost | Quantity or float | Nonnegative cost of one repair attempt. | required |
| fallback_cost | Quantity or float | Positive fallback cost in the same units as repair_cost. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Repair success probability at equal expected cost; above one means repair cannot win on this axis. |
Notes
Equation: p_star = C_repair / C_fallback.
Assumptions: A failed repair leaves the fallback available at unchanged cost.
Excludes: Irreversible damage, repair repetitions, and joint optimization across unlike units.
References
Derivation: Equate C_repair + (1 - p) C_fallback with C_fallback, then solve for p.
Examples
>>> from mlsysim.core.units import ureg
>>> calc_repair_break_even(1 * ureg.second, 4 * ureg.second) == 0.25
Truecalc_repair_first_expected_cost
physics.agents.calc_repair_first_expected_cost(
repair_cost,
fallback_cost,
success_probability,
)Calculate expected cost when one repair precedes fallback.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| repair_cost | Quantity or float | Nonnegative cost paid for the single repair attempt. | required |
| fallback_cost | Quantity or float | Nonnegative fallback cost in units compatible with repair_cost. | required |
| success_probability | float | Repair success probability in [0, 1]. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity or float | Expected total cost, in the shared input-cost unit. |
Notes
Equation: E[C] = C_repair + (1 - p) C_fallback.
Assumptions: Every attempt pays repair cost; only repair failure incurs fallback.
Excludes: Repeated repairs, changed fallback cost, and consequences outside the chosen cost dimension.
References
Derivation: Weight the successful and unsuccessful branches by p and 1 - p.
Examples
>>> calc_repair_first_expected_cost(1, 4, 0.5) == 1 + 0.5 * 4
Truecalc_reused_prefix_prompt_tokens
physics.agents.calc_reused_prefix_prompt_tokens(turns, first_prompt, appended)Count newly prefetched tokens with full prefix reuse.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| turns | int | Positive number of requests. | required |
| first_prompt | int | Nonnegative input-token count of the cold first request. | required |
| appended | int | Nonnegative fresh tokens appended on each later request. | required |
Returns
| Name | Type | Description |
|---|---|---|
| int | Total newly prefetched prompt tokens across requests. |
Notes
Equation: S_fresh = S0 + (H - 1) D.
Assumptions: All earlier prefix KV state remains compatible and available at every subsequent call.
Excludes: Cache eviction, prefix edits, lookup overhead, and generated output tokens.
References
Derivation: Charge the initial prompt once and only the appended suffix on each remaining request.
Examples
>>> calc_reused_prefix_prompt_tokens(3, 10, 2) == 10 + 2 * 2
Truecalc_short_circuit_cost
physics.agents.calc_short_circuit_cost(pass_probabilities, check_costs)Calculate the cost and survival share of ordered checks.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pass_probabilities | sequence of float | Pass probabilities in [0, 1], ordered by execution. | required |
| check_costs | sequence of Quantity or float | Nonempty nonnegative finite costs in compatible units, with the same length as pass_probabilities. | required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | Expected checking cost in the shared cost unit and dimensionless all-pass probability. |
Notes
Equation: E[C] = sum_i c_i product_{j<i} p_j; P_pass = product_i p_i.
Assumptions: Each check has fixed conditional pass probability given earlier passes; independent checks may use their marginal probabilities.
Excludes: Reordering optimization and input-dependent costs. Inputs must contain the same nonzero number of checks.
References
Derivation: A check incurs cost only on the fraction of records reaching it, found by multiplying preceding conditional pass rates.
Examples
>>> cost, passing = calc_short_circuit_cost([0.5, 0.5], [2, 4])
>>> (cost, passing) == (2 + 0.5 * 4, 0.5 * 0.5)
Truecalc_split_straddle
physics.agents.calc_split_straddle(train_fraction, attempts)Calculate the chance that repeated task runs straddle a split.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| train_fraction | float | Independent probability that each run enters training, in [0, 1]. | required |
| attempts | int | Positive number of runs of the same task. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Probability that the task appears on both sides of the run-level split. |
Notes
Equation: P_straddle = 1 - f ** k - (1 - f) ** k.
Assumptions: Runs are split independently; task identity is shared across the runs.
Excludes: Task-grouped splitting, stratification, and estimates of downstream evaluation bias.
References
Derivation: The disjoint alternatives to straddling are all-training and all-held-out assignments.
Examples
>>> calc_split_straddle(0.5, 2) == 1 - 0.5 ** 2 - 0.5 ** 2
Truecalc_step_error_for_target
physics.agents.calc_step_error_for_target(target_success, horizon)Find the per-step error rate allowed by a task success target.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| target_success | float | Target task success probability in [0, 1]. | required |
| horizon | float | Positive number of unchecked steps. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Dimensionless maximum per-step error under the independent-step model. |
Notes
Equation: epsilon = 1 - target_success ** (1 / horizon).
Assumptions: Each step has an identical, independent error probability.
Excludes: Error dependence, checking, recovery, and finite-precision root error.
References
Derivation: Invert target = (1 - epsilon) ** H; for small epsilon, H epsilon approximates -ln(target).
Examples
>>> error = calc_step_error_for_target(0.5 ** 3, 3)
>>> error == 0.5
Truecalc_tempered_softmax
physics.agents.calc_tempered_softmax(logits, temperature=1.0)Normalize temperature-scaled logits into sampling probabilities.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| logits | iterable of float | Nonempty sequence of dimensionless scores whose scaled exponentials are representable. | required |
| temperature | float | Positive dimensionless softmax temperature; default 1 leaves the scores unchanged. | 1.0 |
Returns
| Name | Type | Description |
|---|---|---|
| list of float | Probabilities in input order, normalized to sum to one. |
Notes
Equation: p_i = exp(z_i / T) / sum_j exp(z_j / T).
Assumptions: Finite exponentials with a positive normalizer; this implementation exponentiates directly.
Excludes: Log-sum-exp stabilization, top-p truncation, and predictions of output quality.
References
Derivation: Normalize the positive exponential weights by their sum.
Examples
>>> calc_tempered_softmax([0.0, 0.0]) == [0.5, 0.5]
Truecalc_unchecked_success
physics.agents.calc_unchecked_success(step_success, horizon)Calculate unchecked task success from per-step success.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| step_success | float | Independent per-step success probability in [0, 1]. | required |
| horizon | float | Nonnegative number of steps; whole counts describe discrete tasks. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Dimensionless probability that every step succeeds. |
Notes
Equation: P_task = p_step ** H.
Assumptions: The same success probability applies independently to each unchecked step.
Excludes: Correlated errors, checks, recovery, and changing difficulty.
References
Derivation: The intersection probability of independent step successes is their product.
Examples
>>> calc_unchecked_success(0.5, 3) == 0.5 ** 3
Truecalc_used_fraction
physics.agents.calc_used_fraction(used, allowance)Calculate the consumed fraction of one budget dimension.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| used | Quantity or float | Nonnegative consumed amount. | required |
| allowance | Quantity or float | Positive budget in units compatible with used. | required |
Returns
| Name | Type | Description |
|---|---|---|
| float | Dimensionless consumed fraction; may exceed one when over budget. |
Notes
Equation: rho = used / allowance.
Assumptions: The two inputs refer to the same additive budget dimension.
Excludes: Budget renewal, refunds, and enforcing an admission policy.
References
Derivation: Normalize the consumed amount by its allowance.
Examples
>>> from mlsysim.core.units import ureg
>>> calc_used_fraction(2 * ureg.second, 4 * ureg.second) == 0.5
Truecalc_work_for_setup_cap
physics.agents.calc_work_for_setup_cap(setup, cap)Find useful work needed to cap the setup share.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| setup | Quantity or float | Nonnegative setup duration or cost. | required |
| cap | float | Maximum allowed setup share in (0, 1]. | required |
Returns
| Name | Type | Description |
|---|---|---|
| Quantity or float | Minimum useful work, in the same units as setup. |
Notes
Equation: W_min = T_setup (1 - phi) / phi.
Assumptions: Setup and work add in the same accounting dimension.
Excludes: Overlap, discrete work-item rounding, and changing setup cost.
References
Derivation: Solve T_setup / (T_setup + W) <= phi for W.
Examples
>>> from mlsysim.core.units import ureg
>>> calc_work_for_setup_cap(1 * ureg.second, 0.25) == 3 * ureg.second
True