CLI and Python Reference¶

Command summary¶

cnuas-timing predict PROFILE COMPONENT [work options]
cnuas-timing simulate PROFILE PIPELINE [simulation options]
cnuas-timing calibrate COMPONENT TARGET OBSERVATIONS
cnuas-timing validate CALIBRATION OBSERVATIONS
cnuas-timing qemu-args [--shift N]

Every successful data command writes JSON to standard output. Validation and input errors are written to standard error and return exit code 2.

`predict`¶

cnuas-timing predict PROFILE COMPONENT \
  [--instructions N] [--cycles N] [--bytes N] \
  [--packets N] [--operations N]

All work options default to zero. Use only dimensions supported by the selected component.

Output fields:

Field	Meaning
`component`	Profile component key
`duration_ns`	Calibrated or analytic service time
`evidence`	`analytic` or `calibrated`
`target`	Named calibration target or null
`uncertainty_pct`	Declared uncertainty or null

`simulate`¶

cnuas-timing simulate PROFILE PIPELINE \
  [--jobs N] [--arrival-interval-ns N] [--trace]

Option	Default	Meaning
`--jobs`	1	Number of identical jobs
`--arrival-interval-ns`	0	Time between job submissions
`--trace`	off	Include every scheduled event

The result's evidence array lists every evidence class used by the selected pipeline.

Trace event fields:

Field	Meaning
`job`	Zero-based job index
`stage`	Pipeline stage name
`component`	Profile component
`lane`	Selected zero-based lane
`submitted_ps`	Arrival at this stage
`start_ps`	Service start after queueing
`end_ps`	Service completion

`calibrate`¶

cnuas-timing calibrate COMPONENT TARGET OBSERVATIONS

TARGET is a required string. Quote it when it contains spaces. The command does not modify a profile; it emits a calibration document.

`validate`¶

cnuas-timing validate CALIBRATION HELD_OUT_OBSERVATIONS

The calibration file must match the JSON emitted by calibrate.

`qemu-args`¶

cnuas-timing qemu-args --shift 0

Accepted shifts are 0 through 10. Virtual nanoseconds per instruction are (2^N). The arguments require TCG and intentionally disable wall-clock alignment and sleeping.

This command does not configure device timing, launch QEMU, capture an instruction count, or enable record/replay for external inputs.

Python API¶

Core types¶

from cnuas_timing import (
    ComponentProfile,
    PipelineStage,
    TimingProfile,
    VirtualTimeline,
    Work,
    simulate,
)

Create and run a profile directly:

component = ComponentProfile(
    name="link",
    fixed_latency_ns=50,
    bandwidth_gbps=100,
    lanes=2,
    resource_mode="serial",
)
profile = TimingProfile(
    name="example",
    version="1",
    components={"link": component},
)
stages = [
    PipelineStage("transfer", "link", Work(bytes=4096)),
]
result = simulate(profile, stages, jobs=100, arrival_interval_ns=500)

print(result.mean_latency_ns)
print(result.p95_latency_ns)
print(result.throughput_per_second)

Profile I/O¶

from cnuas_timing import dump_profile, load_profile

profile = load_profile("profile.json")
dump_profile(profile, "normalized-profile.json")

Serialization sorts component names and writes stable formatted JSON.

Calibration API¶

from cnuas_timing import Observation, fit, validate

training = [
    Observation(predicted_ns=1000, measured_ns=1170, label="4 KiB"),
    Observation(predicted_ns=2000, measured_ns=2270, label="8 KiB"),
]
calibration = fit("link", "named target", training)

report = validate(
    calibration,
    [Observation(predicted_ns=1500, measured_ns=1725, label="6 KiB")],
)

Exception behaviour¶

The Python API raises ValueError for invalid values and KeyError for an unknown component. It does not turn invalid work or malformed profiles into zero-cost events.