Modeling API
Logistic curve fitting and ITL latency distribution modeling.
LogisticModel
mlenergy_data.modeling.logistic.LogisticModel
dataclass
Four-parameter logistic: y = b0 + L * sigmoid(k * (x - x0)).
x is typically log2(batch_size).
Attributes:
| Name | Type | Description |
|---|---|---|
L |
float
|
Amplitude (upper asymptote minus lower asymptote). |
x0 |
float
|
Midpoint of the sigmoid on the x-axis. |
k |
float
|
Steepness of the sigmoid curve. |
b0 |
float
|
Baseline offset (lower asymptote). |
eval_x(x)
Evaluate at continuous x (typically log2(batch_size)).
deriv_wrt_x(x)
Derivative dy/dx at continuous x.
eval(batch)
Evaluate at an integer batch size (converted to log2).
fit(x, y)
classmethod
Fit four-parameter logistic using coarse grid search + least-squares.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
ndarray
|
Independent variable (typically log2(batch_size)). |
required |
y
|
ndarray
|
Dependent variable (e.g., power, latency, throughput). |
required |
Returns:
| Type | Description |
|---|---|
LogisticModel
|
Fitted LogisticModel instance. |
to_dict()
Serialize parameters to a dict.
from_dict(d)
classmethod
Deserialize parameters from a dict (or dict-like, e.g. pandas Series).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
d
|
dict[str, Any] | Any
|
Dict with keys |
required |
ITLMixtureModel
mlenergy_data.modeling.latency.ITLMixtureModel
dataclass
Two-component ITL mixture where each component is log-normal plus offset.
Attributes:
| Name | Type | Description |
|---|---|---|
loc |
float
|
Location shift applied to all samples. |
pi_steady |
float
|
Mixture weight for the steady (low-latency) component. |
sigma_steady |
float
|
Log-normal sigma for the steady component. |
scale_steady |
float
|
Log-normal scale for the steady component. |
pi_stall |
float
|
Mixture weight for the stall (high-latency) component. |
sigma_stall |
float
|
Log-normal sigma for the stall component. |
scale_stall |
float
|
Log-normal scale for the stall component. |
mean_var()
Compute analytical mean and variance of the two-component mixture.
Returns:
| Type | Description |
|---|---|
tuple[float, float]
|
Tuple of (mean, variance) in seconds. |
sample_one(rng)
Draw a single ITL sample from the mixture.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rng
|
Generator
|
NumPy random generator. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Sampled ITL value in seconds. |
sample_avg(*, n_replicas, rng, exact_threshold=30)
Sample the average ITL across n_replicas replicas.
For n <= exact_threshold: draw n individual samples and average. For n > exact_threshold: use CLT approximation (normal from mean/var).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_replicas
|
int
|
Number of replicas to average over. |
required |
rng
|
Generator
|
NumPy random generator. |
required |
exact_threshold
|
int
|
Below this count, use exact sampling. |
30
|
Returns:
| Type | Description |
|---|---|
float
|
Average ITL in seconds. NaN if n_replicas <= 0. |
fit(samples_s, *, max_samples=None, seed=0)
classmethod
Fit a two-component lognormal mixture from ITL samples.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
samples_s
|
ndarray
|
Raw ITL samples in seconds. |
required |
max_samples
|
int | None
|
If set, randomly subsample to this many values before fitting. |
None
|
seed
|
int
|
RNG seed for subsampling. |
0
|
Returns:
| Type | Description |
|---|---|
ITLMixtureModel
|
Fitted ITLMixtureModel instance. |
to_dict()
Serialize parameters to a dict.
from_dict(d)
classmethod
Deserialize parameters from a dict (or dict-like, e.g. pandas Series).
The dict keys may optionally use the itl_mix_ prefix (e.g., from
CSV files produced by the build pipeline).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
d
|
dict[str, Any] | Any
|
Dict with keys for all 7 mixture parameters. |
required |