physics.quantities

physics.quantities

Quantity-first formula helpers for LEGO cells — return Pint quantities, never strings.

Functions

Name	Description
carbon_from_energy	Convert energy consumption to emissions mass.
compute_time	Calculate duration from operation count and sustained rate.
energy_from_power	Integrate constant power over a duration.
memory_from_params	Convert parameter count and storage width to weight bytes.
token_throughput	Calculate average token rate over an interval.
transfer_time	Calculate streaming duration from payload and bandwidth.

carbon_from_energy

physics.quantities.carbon_from_energy(energy, carbon_intensity)

Convert energy consumption to emissions mass.

Parameters

Name	Type	Description	Default
energy	Quantity	Nonnegative energy; converted internally to kWh.	required
carbon_intensity	Quantity	Nonnegative mass per unit energy, such as g/kWh; caller specifies whether mass denotes CO2 or CO2e.	required

Returns

Name	Type	Description
	Quantity	Emissions mass in kilograms.

Notes

Equation: m = E CI.

Assumptions: One intensity represents the entire energy-consumption interval.

Excludes: Embodied emissions, temporal grid variation, and overhead outside the supplied energy.

References

Derivation: Carbon intensity is emissions mass divided by energy. Multiplying consumed energy by the corresponding intensity cancels the energy unit and leaves emissions mass.

Examples

>>> from mlsysim.core.units import Q_
>>> carbon_from_energy(Q_(2, "kWh"), Q_(500, "g/kWh")) == Q_(1, "kg")
True

compute_time

physics.quantities.compute_time(work, throughput)

Calculate duration from operation count and sustained rate.

Parameters

Name	Type	Description	Default
work	Quantity	Nonnegative operation count, with units compatible with throughput.	required
throughput	Quantity	Positive sustained rate of those operations per unit time.	required

Returns

Name	Type	Description
	Quantity	Computation duration in seconds.

Notes

Equation: t = work / throughput.

Assumptions: The supplied rate applies throughout the workload.

Excludes: Memory limits, launch overhead, and changes in utilization.

References

Derivation: Sustained throughput is completed operation count per unit time. Dividing the required count by this rate cancels the operation unit and leaves elapsed time.

Examples

>>> from mlsysim.core.units import Q_
>>> compute_time(Q_(4, "flop"), Q_(2, "flop/s")) == Q_(2, "s")
True

energy_from_power

physics.quantities.energy_from_power(power, duration)

Integrate constant power over a duration.

Parameters

Name	Type	Description	Default
power	Quantity	Nonnegative constant power in watt-compatible units.	required
duration	Quantity	Nonnegative elapsed time.	required

Returns

Name	Type	Description
	Quantity	Energy in joules.

Notes

Equation: E = P t.

Assumptions: Power is constant, or represents the correct time-average for the interval.

Excludes: Time-varying power integration and facility overhead not already in power.

References

Derivation: Integrate constant power P over time: E = integral(P dt) = P t.

Examples

>>> from mlsysim.core.units import Q_
>>> energy_from_power(Q_(2, "W"), Q_(3, "s")) == Q_(6, "J")
True

memory_from_params

physics.quantities.memory_from_params(parameters, bytes_per_param)

Convert parameter count and storage width to weight bytes.

Parameters

Name	Type	Description	Default
parameters	Quantity	Nonnegative parameter count in param-compatible units.	required
bytes_per_param	Quantity	Nonnegative storage width in byte/param units.	required

Returns

Name	Type	Description
	Quantity	Weight storage in bytes.

Notes

Equation: M = P b.

Assumptions: Every parameter has the same supplied storage width.

Excludes: Activations, gradients, optimizer state, KV cache, metadata, and alignment.

References

Derivation: Each stored parameter occupies the supplied byte width. Multiplying the parameter count by bytes per parameter cancels the parameter unit and leaves stored bytes.

Examples

>>> from mlsysim.core.units import Q_
>>> memory_from_params(Q_(3, "param"), Q_(2, "byte/param")) == Q_(6, "byte")
True

token_throughput

physics.quantities.token_throughput(tokens, duration)

Calculate average token rate over an interval.

Parameters

Name	Type	Description	Default
tokens	Quantity	Nonnegative token count in count-compatible units.	required
duration	Quantity	Positive elapsed time.	required

Returns

Name	Type	Description
	Quantity	Average rate in count/second.

Notes

Equation: r = N_tokens / t.

Assumptions: The count and interval describe the same work; the caller defines prompt or output tokens.

Excludes: Instantaneous rate, latency quantiles, and separation of prefill from decode.

References

Derivation: Average throughput is the count of completed items divided by their observation interval. Using token count and elapsed time gives tokens per second.

Examples

>>> from mlsysim.core.units import Q_
>>> token_throughput(Q_(6, "count"), Q_(2, "s")) == Q_(3, "count/s")
True

transfer_time

physics.quantities.transfer_time(payload, bandwidth)

Calculate streaming duration from payload and bandwidth.

Parameters

Name	Type	Description	Default
payload	Quantity	Nonnegative payload in byte-compatible units.	required
bandwidth	Quantity	Positive sustained byte rate, such as GB/s.	required

Returns

Name	Type	Description
	Quantity	Streaming duration in seconds.

Notes

Equation: t = payload / bandwidth.

Assumptions: The supplied bandwidth is constant and available to this transfer.

Excludes: Per-message latency, protocol headers, queueing, and contention.

References

Derivation: Sustained bandwidth is transferred bytes per unit time. Dividing payload bytes by this rate cancels the byte unit and leaves transfer duration.

Examples

>>> from mlsysim.core.units import Q_
>>> transfer_time(Q_(4, "GB"), Q_(2, "GB/s")) == Q_(2, "s")
True