study-config

Configuration Reference

Full reference for all ExperimentConfig fields. All fields except model are optional and have sensible defaults.

Config identity and hashing. Each experiment carries three config hashes: the declared hash digests the fields you wrote in the YAML config (user intent); the resolved hash digests the config after the engine applies its own defaults and normalisation (what the run actually uses); and the observed hash digests the config as the live library reports it after construction (the resolved and observed hashes project the same values at present). The declared hash and the resolved/observed hashes form two separate hash families that never intersect. The mode_section is the active serving mode's slice of that identity - in server mode the traffic spec (minus the post-hoc SLO bounds), the warmup protocol, and the inter-level cooldown; in offline mode the warmup block - so a rate or warmup sweep produces distinct hashes while two runs differing only in SLO bounds deduplicate together.

Sections:

• Top-Level Fields
• Baseline (baseline:)
• Offline Mode (offline:)
• Offline Warmup (offline.warmup:)
• Server Mode (server:)
• Server Warmup (server.warmup:)
• Server Traffic (server.traffic:)
• Server Traffic SLO (server.traffic.slo:)
• Transformers Engine (transformers:)
• Transformers Engine Params (transformers.engine_params:)
• Transformers Sampling Params (transformers.sampling_params:)
• Transformers Execution Knobs (transformers.llem_execution:)
• vLLM Engine (vllm:)
• vLLM Engine Params (vllm.engine_params:)
• vLLM Sampling Params (vllm.sampling_params:)
• TensorRT-LLM Engine (tensorrt:)
• TensorRT-LLM Engine Params (tensorrt.engine_params:)
• TensorRT-LLM Sampling Params (tensorrt.sampling_params:)

Top-Level Fields

Field	Type	Default	Description
task	TaskConfig	(see section)	Task configuration: model, dataset, workload shape
engine	Engine	(see section)	Inference engine
serving_mode	'offline'	'server'	(required)
measurement	MeasurementConfig	(see section)	Measurement methodology: baseline, energy sampling (mode-invariant)
sampling_preset	'deterministic'	'standard'	'creative'
transformers	TransformersSection	None	null
vllm	Config	None	null
tensorrt	Config	None	null
server	ServerSection	None	null
offline	OfflineSection	None	null
passthrough_kwargs	dict	None	null

Baseline (baseline:)

Field	Type	Default	Description
enabled	boolean	true	Enable baseline power measurement
duration_seconds	number	30.0	Baseline measurement duration in seconds
strategy	'cached'	'validated'	'fresh'
cache_ttl_seconds	number	7200.0	How long a cached baseline remains valid before re-measurement, in seconds. Only used with strategy='cached' or 'validated'.
validation_interval	integer	5	Re-validate baseline every N experiments. Only used with strategy='validated'.
drift_threshold	number	0.1	Power drift threshold (fraction) to trigger re-measurement. Only used with strategy='validated'.

Offline Mode (offline:)

Field	Type	Default	Description
warmup	WarmupConfig	(see section)	Offline warmup phase configuration (prompt-loop convergence + thermal floor).

Offline Warmup (offline.warmup:)

Field	Type	Default	Description
enabled	boolean	true	Enable warmup phase
n_prompts	integer	5	Number of full-length warmup prompts in fixed mode
thermal_floor_seconds	number	60.0	Minimum seconds to wait after warmup before measuring (thermal stabilisation). Minimum 30s enforced.
convergence_detection	boolean	false	Enable CV-based adaptive convergence (governed by min_prompts, max_prompts, cv_threshold, window_size)
cv_threshold	number	0.05	CV target for convergence (only used when convergence_detection=True)
max_prompts	integer	20	Maximum warmup prompts when CV mode is on (safety cap)
window_size	integer	3	Sliding window size for CV calculation (3 balances responsiveness and stability)
min_prompts	integer	5	Minimum prompts before checking convergence (warm start)

Server Mode (server:)

Field	Type	Default	Description
traffic	TrafficConfig	(see section)	Online-serving traffic specification (rate, arrival, window, concurrency, slo).
warmup	ServerWarmupConfig	(see section)	Server warmup protocol (convergence-composite gate by default, fixed-duration opt-out). A declared measurement-protocol knob, so it joins the config identity in both hash families (projected into the mode_section).
cooldown_seconds	number	0.0	Inter-level cooldown in seconds: idle pause the window manager applies AFTER a rate level closes and BEFORE the next level in a rate sweep. Default 0 (no pause). A declared measurement-protocol knob, so it joins the config identity in both hash families (it is projected into the resolved/observed mode_section).

Server Warmup (server.warmup:)

Field	Type	Default	Description
mode	'composite'	'fixed'	composite
timeout_seconds	number	900.0	Composite-mode failsafe: hard upper bound on convergence gating. At the timeout the harness proceeds and stamps convergence: timed_out in the result (never hangs, never silently passes). Ignored in fixed mode.
duration_seconds	number	300.0	Fixed-mode warmup duration in seconds (the floor rule default). 60s is a citable convenience floor, not a thermal-equilibrium claim; 0 skips warmup traffic entirely. Ignored in composite mode.

Server Traffic (server.traffic:)

Field	Type	Default	Description
rate	number	(required)	Request arrival rate in requests per second (scalar). A rate sweep is written as a study-level list axis (server.traffic.rate: [2, 10]) and expanded to independent per-window configs before hashing.
arrival	'poisson'	'gamma'	poisson
burstiness	number	None	null
window_seconds	number	None	null
window_requests	integer	None	null
ramp_exclusion_seconds	number	30.0	Pre-stable ramp excluded from the measured span, in seconds (an absolute duration; the default is grounded in the minimum-window-duration study). The measured span STARTS this many seconds after load begins and is excluded PROSPECTIVELY (never trimmed retroactively). 0 disables ramp exclusion. A measurement-methodology knob, so it joins the config identity like the other traffic fields (only slo is excluded).
concurrency_cap	integer	None	null
slo	SloConfig	None	null
seed	integer	None	null

Server Traffic SLO (server.traffic.slo:)

Field	Type	Default	Description
ttft_ms	number	None	null
tpot_ms	number	None	null
percentile	number	0.99	Tail quantile both ttft_ms and tpot_ms are evaluated at (shared). Default 0.99.

Transformers Engine (transformers:)

Field	Type	Default	Description
engine_params	EngineParams	None	null
sampling_params	SamplingParams	None	null
llem_execution	TransformersLlemExecution	None	null

Transformers Engine Params (transformers.engine_params:)

Field	Type	Default	Description
dtype	any	None	null
attn_implementation	any	None	null
load_in_4bit	any	None	null
load_in_8bit	any	None	null
bnb_4bit_compute_dtype	any	None	null
bnb_4bit_quant_type	any	None	null
bnb_4bit_use_double_quant	any	None	null
use_cache	boolean	None	null
cache_implementation	string	None	null
num_beams	integer	None	null
early_stopping	boolean	string	None
length_penalty	number	None	null
no_repeat_ngram_size	integer	None	null
prompt_lookup_num_tokens	integer	None	null
device_map	any	None	null
max_memory	any	None	null
low_cpu_mem_usage	any	None	null
tp_plan	any	None	null
tp_size	any	None	null

Transformers Sampling Params (transformers.sampling_params:)

Field	Type	Default	Description
temperature	number	None	null
do_sample	boolean	None	null
top_k	integer	None	null
top_p	number	None	null
repetition_penalty	number	None	null
min_p	number	None	null
min_new_tokens	integer	None	null

Transformers Execution Knobs (transformers.llem_execution:)

Field	Type	Default	Description
batch_size	integer	None	null
torch_compile	boolean	None	null
torch_compile_mode	string	None	null
torch_compile_backend	string	None	null
allow_tf32	boolean	None	null
autocast_enabled	boolean	None	null
autocast_dtype	'float16'	'bfloat16'	None

vLLM Engine (vllm:)

Field	Type	Default	Description
engine_params	EngineParams	None	null
sampling_params	SamplingParams	None	null

vLLM Engine Params (vllm.engine_params:)

Field	Type	Default	Description
dtype	'auto'	'half'	'float16'
gpu_memory_utilization	number	None	0.9
cpu_offload_gb	number	None	0
block_size	integer	None	null
kv_cache_dtype	'auto'	'float16'	'bfloat16'
enforce_eager	boolean	None	false
enable_chunked_prefill	boolean	None	null
max_num_seqs	integer	None	null
max_num_batched_tokens	integer	None	null
max_model_len	integer	None	null
tensor_parallel_size	integer	None	1
pipeline_parallel_size	integer	None	1
distributed_executor_backend	any	None	null
enable_prefix_caching	boolean	None	null
quantization	any	None	null
speculative_config	SpeculativeConfig	None	null
offload_group_size	integer	None	0
offload_num_in_group	integer	None	1
offload_prefetch_step	integer	None	1
offload_params	any	None	[]
disable_custom_all_reduce	boolean	None	false
kv_cache_memory_bytes	integer	None	null
compilation_config	CompilationConfig	None	null
attention	any	None	null
beam_search	any	None	null

vLLM Sampling Params (vllm.sampling_params:)

Field	Type	Default	Description
temperature	number	None	1.0
top_k	integer	None	0
top_p	number	None	1.0
repetition_penalty	number	None	1.0
min_p	number	None	0.0
min_tokens	integer	None	0
presence_penalty	number	None	0.0
frequency_penalty	number	None	0.0
ignore_eos	boolean	None	false
n	integer	None	1

TensorRT-LLM Engine (tensorrt:)

Field	Type	Default	Description
engine_params	EngineParams	None	null
sampling_params	SamplingParams	None	null

TensorRT-LLM Engine Params (tensorrt.engine_params:)

Field	Type	Default	Description
max_batch_size	integer	None	null
tensor_parallel_size	integer	None	1
pipeline_parallel_size	integer	None	1
max_input_len	integer	None	null
max_seq_len	integer	None	null
max_num_tokens	integer	None	8192
dtype	string	None	auto
fast_build	boolean	None	false
backend	'pytorch'	'trt'	None
quant_config	any	None	null
kv_cache_config	any	None	null
scheduler_config	any	None	null

TensorRT-LLM Sampling Params (tensorrt.sampling_params:)

Field	Type	Default	Description
temperature	number	None	null
top_k	integer	None	null
top_p	number	None	null
repetition_penalty	number	None	null
min_p	number	None	null
min_tokens	integer	None	null
n	integer	None	1
ignore_eos	boolean	None	false

Sweep-Axis Range Shorthands

An independent sweep axis (sweep: entry mapping to a list of scalars) may be written as one of three compact range shorthands instead of an explicit list. Each expands to a plain list at load time, so the two forms are interchangeable.

Shorthand	Meaning	Example	Expands to
{min: a, max: b, num: n}	n evenly spaced values, endpoints inclusive	{min: 0, max: 8, num: 5}	[0, 2, 4, 6, 8]
{log: {min: a, max: b, num: n}}	n log-spaced values (min > 0), endpoints inclusive	{log: {min: 1, max: 100, num: 3}}	[1, 10, 100]
{pow2: {min: a, max: b}}	ascending powers of two within [a, b]	{pow2: {min: 4, max: 32}}	[4, 8, 16, 32]

Values stay integers when all bounds are integers and every produced value is integral; otherwise they are floats (rounded to kill binary-float noise). A mapping that matches none of these shapes is rejected at load time. To sweep a literal mapping value, set it in the base config or use a group entry (list of dicts).