simaudit 0.1.0a1__py3-none-any.whl

simaudit/__init__.py

@@ -0,0 +1,9 @@
+"""Simulator-independent diagnostics with explicit uncertainty and coverage."""
+from .adapters import Adapter, Blowup, Unsupported
+from .checks import check_assignment, check_observation, check_order
+from .release import compare_releases
+from .report import Feature, Modification, Report, Result, Status
+
+__version__ = '0.1.0a1'
+__all__ = ['Adapter','Blowup','Unsupported','check_assignment','check_observation',
+           'check_order','compare_releases','Feature','Modification','Report','Result','Status']

simaudit/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

simaudit/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .base import Adapter, Blowup, Unsupported
+
+__all__ = ["Adapter", "Blowup", "Unsupported"]

simaudit/adapters/base.py

@@ -0,0 +1,68 @@
+"""Simulator-independent callable adapter; no optional simulator dependencies."""
+from dataclasses import dataclass, field
+import platform
+from copy import deepcopy
+import numpy as np
+from ..report import Feature, Modification
+
+
+class Unsupported(RuntimeError):
+    pass
+
+
+class Blowup(RuntimeError):
+    pass
+
+
+@dataclass
+class Adapter:
+    name: str
+    step_fn: object = None
+    native_step_fn: object = None
+    distance_fn: object = None
+    observe_fn: object = None
+    reference_observe_fn: object = None
+    assignment_factory: object = None
+    features: list[Feature] = field(default_factory=lambda: [
+        Feature("dynamics", "unsupported", "User has not supplied a feature inventory")])
+    modifications: list[Modification] = field(default_factory=list)
+    versions: dict[str, str] = field(default_factory=dict)
+    scope: str = "Only supplied states, actions and configurations"
+    limitations: list[str] = field(default_factory=list)
+    dtype: str = "float64"
+    noise_floor: float = 0.0
+    smooth: bool | None = None
+    declared_order: float | None = None
+    order_blockers: list[str] = field(default_factory=list)
+    assignment_metadata: dict = field(default_factory=dict)
+    dt: float = 0.01
+
+    def __post_init__(self):
+        if np.dtype(self.dtype).kind != 'f':
+            raise ValueError("Adapter dtype must be floating point")
+        if not np.isfinite(self.noise_floor) or self.noise_floor < 0:
+            raise ValueError("noise_floor must be finite and nonnegative")
+        if not np.isfinite(self.dt) or self.dt <= 0:
+            raise ValueError("dt must be positive and finite")
+        self.versions = {"python": platform.python_version(), "numpy": np.__version__, **self.versions}
+
+    @property
+    def capabilities(self):
+        return {name for name, fn in (("step", self.step_fn), ("native_step", self.native_step_fn),
+                ("observation", self.observe_fn), ("reference_observation", self.reference_observe_fn),
+                ("assignment", self.assignment_factory)) if callable(fn)}
+
+    def step(self, state, action, dt):
+        return np.array(self.step_fn(np.array(state, copy=True), deepcopy(action), dt), copy=True)
+
+    def native_step(self, state, action, dt):
+        return np.array(self.native_step_fn(np.array(state, copy=True), deepcopy(action), dt), copy=True)
+
+    def distance(self, a, b):
+        a, b = np.asarray(a), np.asarray(b)
+        if a.shape != b.shape:
+            raise ValueError("State shapes differ")
+        value = float(self.distance_fn(a, b) if self.distance_fn else np.linalg.norm(a.astype(float)-b.astype(float)))
+        if not np.isfinite(value) or value < 0:
+            raise Blowup("Nonfinite or negative state distance")
+        return value

simaudit/adapters/cartpole.py

@@ -0,0 +1,66 @@
+"""Optional scalar Gymnasium adapter. Assignment methodology: Gebrekidan (2026)."""
+import numpy as np
+from .base import Adapter, Unsupported
+from ..report import Feature, Modification
+
+PARAMS = ('masscart','masspole','length','gravity','force_mag','tau')
+
+
+def cartpole(parameters=None, *, consistent=True):
+    import gymnasium
+    from gymnasium.envs.classic_control.cartpole import CartPoleEnv
+    params = dict(parameters or {})
+    if set(params)-set(PARAMS): raise Unsupported('Unsupported CartPole parameter')
+    if any(not np.isfinite(v) or v <= 0 for v in params.values()):
+        raise ValueError('CartPole parameters must be positive and finite')
+
+    def new():
+        env = CartPoleEnv()
+        env.reset(seed=0)
+        for key,value in params.items(): setattr(env,key,value)
+        if consistent:
+            env.total_mass = env.masscart + env.masspole
+            env.polemass_length = env.masspole * env.length
+        return env
+
+    env = new()
+    defaults = CartPoleEnv()
+    modifications = [Modification(k, getattr(defaults,k),v,
+        'fresh consistent reference' if consistent else 'direct attribute assignment') for k,v in params.items()]
+    if consistent:
+        for k in ('total_mass','polemass_length'):
+            if getattr(defaults,k)!=getattr(env,k):
+                modifications.append(Modification(k,getattr(defaults,k),getattr(env,k),'rebuild dependent constant'))
+    defaults.close()
+
+    def run(e,s,u,h):
+        e.state = np.array(s,dtype=np.float64,copy=True)
+        e.steps_beyond_terminated = None
+        e.tau = h
+        e.step(int(u))
+        return np.array(e.state,copy=True)
+
+    def native(s,u,h):
+        fresh = new()
+        try: return run(fresh,s,u,h)
+        finally: fresh.close()
+
+    def factory(name,value):
+        if name not in PARAMS: raise Unsupported(f'Assignment parameter not supported: {name}')
+        values = {**params,name:value}
+        return cartpole(values,consistent=False), cartpole(values,consistent=True)
+
+    def distance(x,y):
+        delta = x-y
+        delta[2] = np.arctan2(np.sin(delta[2]),np.cos(delta[2]))
+        return np.linalg.norm(delta)
+
+    return Adapter('CartPole-v1',lambda s,u,h:run(env,s,u,h),native,distance,
+        assignment_factory=factory, assignment_metadata={'partial_update': 'length' in params and not consistent,
+            'basis': 'length is read directly, but polemass_length is cached; adapter-specific source inspection'}, dt=env.tau, smooth=True, declared_order=1,
+        features=[Feature('dynamics','tested','Scalar unwrapped CartPole internal float64 state',True),
+                  Feature('parameters','present_not_tested','Only the requested parameter is probed; other attributes remain untested',True),
+                  Feature('wrappers','present_not_tested','TimeLimit/rendering/reward/termination excluded',False)],
+        modifications=modifications, versions={'gymnasium':gymnasium.__version__},
+        scope='Scalar CartPole internal one-step dynamics with explicit constant-rebuild reference',
+        limitations=['Vector CartPole and static attribute discovery are not implemented.'])

simaudit/adapters/mujoco.py

@@ -0,0 +1,108 @@
+"""Optional native adapters. No model features are silently disabled."""
+import hashlib
+import numpy as np
+from .base import Adapter, Blowup
+from ..report import Feature
+
+
+def mujoco_xml(xml):
+    import mujoco as mj
+    model = mj.MjModel.from_xml_string(xml)
+    data = mj.MjData(model)
+    presence = {
+        'contacts':bool(np.any(model.geom_contype) or np.any(model.geom_conaffinity)),
+        'joint_limits':bool(np.any(model.jnt_limited)), 'actuators':bool(model.nu),
+        'damping':bool(np.any(model.dof_damping)), 'friction':bool(np.any(model.dof_frictionloss)),
+        'fluid':bool(model.opt.viscosity or model.opt.density), 'tendons':bool(model.ntendon),
+        'equality_constraints':bool(model.neq), 'plugins':bool(model.nplugin),
+        'flex':bool(model.nflex), 'mocap':bool(model.nmocap),
+        'callbacks':any(getattr(mj,'get_mjcb_'+name,lambda:None)() is not None
+                        for name in ('control','passive','sensor','act_dyn','act_gain','act_bias')),
+    }
+    blockers = [k for k,v in presence.items() if v]
+    features = [Feature(k,'unsupported' if v else 'present_not_tested',
+                        'Present: unsupported by autonomous smooth adapter' if v else 'Absent in compiled model',v)
+                for k,v in presence.items()]
+    features += [Feature('gravity','tested','Retained as compiled',True),
+                 Feature('springs','tested','Retained as compiled',bool(np.any(model.jnt_stiffness)))]
+    initial_dt = float(model.opt.timestep)
+
+    def run(target,s,u,h):
+        if blockers:
+            from .base import Unsupported
+            raise Unsupported('Restricted native replay cannot represent: '+', '.join(blockers))
+        if s.shape != (model.nq+model.nv,): raise ValueError('Expected qpos followed by qvel')
+        if np.any(np.asarray(u)!=0): raise ValueError('Autonomous adapter accepts only zero action')
+        old = model.opt.timestep
+        try:
+            model.opt.timestep = h
+            mj.mj_resetData(model,target)
+            target.qpos[:] = s[:model.nq]
+            target.qvel[:] = s[model.nq:]
+            mj.mj_forward(model,target)
+            mj.mj_step(model,target)
+            if np.any(target.warning.number) or not np.isfinite(target.time) or abs(target.time-h)>1e-12:
+                raise Blowup('MuJoCo warning or automatic reset during native step')
+            return np.concatenate([target.qpos,target.qvel])
+        finally:
+            model.opt.timestep = old
+
+    def distance(x,y):
+        tangent = np.empty(model.nv)
+        mj.mj_differentiatePos(model,tangent,1.0,y[:model.nq],x[:model.nq])
+        return np.linalg.norm(np.concatenate([tangent,x[model.nq:]-y[model.nq:]]))
+
+    declared = {int(mj.mjtIntegrator.mjINT_EULER):1, int(mj.mjtIntegrator.mjINT_RK4):4}.get(int(model.opt.integrator))
+    if declared is None: blockers.append('unvalidated integrator family')
+    return Adapter('MuJoCo XML',lambda s,u,h:run(data,s,u,h),
+        lambda s,u,h:run(mj.MjData(model),s,u,h),distance,
+        features=features, versions={'mujoco':mj.__version__,'model_sha256':hashlib.sha256(xml.encode()).hexdigest()},
+        scope='Native engine step of supplied smooth autonomous XML; qpos/qvel only',
+        limitations=['Only autonomous rigid models without listed unsupported features are supported.',
+                     'No claim about frame-skip trajectories, contacts, constraints, or control callbacks.'],
+        smooth=not blockers,order_blockers=blockers,declared_order=declared,dt=initial_dt)
+
+
+def reacher():
+    import gymnasium as gym
+    import mujoco as mj
+    env = gym.make('Reacher-v5').unwrapped
+    env.reset(seed=0)
+    model = env.model
+    dt = float(env.dt)
+    # Each probe begins from the same complete data snapshot, then specifies qpos/qvel.
+    snapshot = mj.MjData(model)
+    mj.mj_copyData(snapshot,model,env.data)
+
+    def run(s,u,h,refresh=False):
+        if h != dt: raise ValueError('Reacher adapter uses its native frame-skip interval')
+        if s.shape != (model.nq+model.nv,): raise ValueError('Expected qpos followed by qvel')
+        mj.mj_copyData(env.data,model,snapshot)
+        env.set_state(s[:model.nq],s[model.nq:])
+        observation,*_ = env.step(np.asarray(u,dtype=float))
+        if np.any(env.data.warning.number): raise Blowup('MuJoCo warning during Reacher step')
+        state = np.concatenate([env.data.qpos.copy(),env.data.qvel.copy()])
+        if refresh:
+            mj.mj_forward(model,env.data)
+            observation = env._get_obs()
+        return state,np.array(observation,copy=True)
+
+    def native(s,u,h):
+        other = gym.make('Reacher-v5').unwrapped
+        try:
+            other.reset(seed=0)
+            mj.mj_copyData(other.data,other.model,snapshot)
+            other.set_state(s[:model.nq],s[model.nq:])
+            other.step(np.asarray(u,dtype=float))
+            return np.concatenate([other.data.qpos.copy(),other.data.qvel.copy()])
+        finally: other.close()
+
+    return Adapter('Reacher-v5',lambda s,u,h:run(s,u,h)[0],native,
+        observe_fn=lambda s,u,h:run(s,u,h)[1], reference_observe_fn=lambda s,u,h:run(s,u,h,True)[1],
+        features=[Feature('observations','tested','Shipped observation versus mj_forward recomputation',True),
+                  Feature('actuators','present_not_tested','Retained native control; actuation correctness untested',True),
+                  Feature('dynamics','present_not_tested','Native replay checked; physics correctness untested',True),
+                  Feature('wrappers','present_not_tested','Unwrapped; TimeLimit excluded',False)],
+        versions={'gymnasium':gym.__version__,'mujoco':mj.__version__},dt=dt,
+        limitations=['Reference reuses the shipped observation formula; this checks cache consistency only.',
+                     'Fixed reset snapshot; no arbitrary user callbacks or wrappers are represented.'])

simaudit/checks.py

@@ -0,0 +1,220 @@
+"""Independent scoped checks. Method attribution: see CITATION.cff and THIRD_PARTY.md."""
+from dataclasses import asdict
+import math
+import numpy as np
+from .report import Feature, Modification, Result, Status
+from .adapters import Blowup, Unsupported
+
+LIMITS = {
+    'assignment': ['Only explicitly supplied parameters and probes are assessed.',
+                   'The fresh factory defines the parameter contract; direct mutation may not be a supported simulator API.'],
+    'order': ['Convergence does not establish correct equations or accurate trajectories.',
+              'Non-smooth, noisy, stiff and unresolved regimes cannot be diagnosed by these slopes.',
+              'Only the supplied interval and starts are assessed; no energy or model-fault classification.'],
+    'observation': ['Only the supplied reference observation map and probes are assessed.',
+                    'A shared error in simulator and reference can be invisible.'],
+    'release': ['A changed first step is a compatibility difference, not proof of a simulator defect.',
+                'Reward, termination, reset, spaces, RNG and rendering are not compared.',
+                'Later separation does not identify chaos; unexecuted releases remain untested.'],
+}
+
+
+def result(a, check, status, reason, evidence=None, fault=None, modifications=()):
+    coverage = [Feature(**asdict(f)) for f in a.features]
+    if not coverage:
+        coverage = [Feature('dynamics', 'unsupported', 'No feature inventory supplied')]
+    return Result(check, status, reason, a.scope, LIMITS.get(check, []) + a.limitations + [
+        'Adapter inventory and reference correctness remain caller responsibilities.'], coverage,
+        [*a.modifications, *modifications], a.versions, evidence or {}, fault)
+
+
+def probes(states, actions):
+    states = [np.asarray(s) for s in states]
+    actions = list(actions)
+    if not states or len(states) != len(actions):
+        raise ValueError('Supply a nonempty state/action pair list with matching lengths')
+    if any(not np.all(np.isfinite(s)) for s in states):
+        raise ValueError('Input states must be finite')
+    return states, actions
+
+
+def tolerance(value):
+    if not np.isfinite(value) or value < 0:
+        raise ValueError('Tolerance must be finite and nonnegative')
+    return float(value)
+
+
+def self_test(a, states, actions, dts, atol=1e-12):
+    """Compare native steps, replay after interleaving, and two-step continuation."""
+    for state, action in zip(states, actions):
+        for dt in dts:
+            x = a.step(state, action, dt)
+            native = a.native_step(state, action, dt)
+            if not np.all(np.isfinite(x)) or not np.all(np.isfinite(native)):
+                raise Blowup('Nonfinite output during adapter self-test')
+            replay_floor, _ = precision(a, [x, native], atol)
+            if a.distance(x, native) > replay_floor:
+                return False, 'native-step equivalence failed'
+            # A different input/continuation must not contaminate a replay.
+            y = a.step(x, action, dt)
+            replay = a.step(state, action, dt)
+            native_y = a.native_step(native, action, dt)
+            continuation_floor, _ = precision(a, [y, native_y], atol)
+            if a.distance(x, replay) > replay_floor or a.distance(y, native_y) > continuation_floor:
+                return False, 'state restoration or continuation equivalence failed'
+    return True, 'native-step equivalence and interleaved replay passed'
+
+
+def guard(a, check, states, actions, dts, needed=()):
+    missing = {'step', 'native_step', *needed} - a.capabilities
+    if missing:
+        return result(a, check, Status.SKIPPED, 'Missing capabilities: ' + ', '.join(sorted(missing)))
+    try:
+        ok, reason = self_test(a, states, actions, dts)
+    except Blowup as exc:
+        return result(a, check, Status.BLOWUP, str(exc))
+    except Unsupported as exc:
+        return result(a, check, Status.SKIPPED, str(exc))
+    if not ok and a.noise_floor > 0:
+        return result(a, check, Status.ABSTAIN, 'Declared noise prevents verifying deterministic native equivalence/restoration; downstream check blocked')
+    if not ok:
+        return result(a, check, Status.FAIL, reason + '; downstream check blocked', fault='adapter')
+    return None
+
+
+def precision(a, arrays, atol):
+    eps = max([float(np.finfo(a.dtype).eps)] + [float(np.finfo(x.dtype).eps) for x in arrays if x.dtype.kind == 'f'])
+    scale = 1 + max(float(np.linalg.norm(x)) for x in arrays)
+    return max(atol, a.noise_floor, 50 * eps * scale), eps
+
+
+def check_assignment(a, parameter, value, states, actions, *, atol=1e-12):
+    states, actions = probes(states, actions)
+    atol = tolerance(atol)
+    blocked = guard(a, 'assignment', states, actions, [a.dt], ['assignment'])
+    if blocked: return blocked
+    try:
+        assigned, fresh = a.assignment_factory(parameter, value)
+    except Unsupported as exc:
+        return result(a, 'assignment', Status.SKIPPED, str(exc))
+    for candidate in (assigned, fresh):
+        blocked = guard(candidate, 'assignment', states, actions, [candidate.dt])
+        if blocked: return blocked
+    if not assigned.modifications or not fresh.modifications:
+        return result(a, 'assignment', Status.FAIL, 'Assignment factory omitted modification records', fault='adapter')
+    rows = []
+    try:
+        for s, u in zip(states, actions):
+            b, d, f = [adapter.step(s, u, adapter.dt) for adapter in (a, assigned, fresh)]
+            floor, eps = precision(a, [b, d, f], atol)
+            rows.append(dict(state=s.tolist(), action=np.asarray(u).tolist(), baseline=b.tolist(),
+                             assigned=d.tolist(), fresh=f.tolist(), floor=floor,
+                             baseline_assigned=a.distance(b,d), baseline_fresh=a.distance(b,f),
+                             assigned_fresh=a.distance(d,f), low_precision=eps > 1e-10))
+    except Blowup as exc:
+        return result(a, 'assignment', Status.BLOWUP, str(exc))
+    effective = [r for r in rows if r['baseline_fresh'] > r['floor']]
+    mismatch = any(r['assigned_fresh'] > r['floor'] for r in rows)
+    no_op = all(r['baseline_assigned'] <= r['floor'] for r in rows)
+    if mismatch:
+        kind = 'no_op' if no_op else 'stale'
+        if not no_op and assigned.assignment_metadata.get('partial_update'):
+            kind = 'partly_stale'
+        status, reason = Status.FAIL, f'{parameter}: {kind} relative to supplied fresh-reference contract'
+    elif not effective or any(r['low_precision'] for r in rows) or a.noise_floor:
+        kind, status, reason = 'unresolved', Status.ABSTAIN, 'Insufficient parameter excitation or precision/noise blocks a consistency verdict'
+    else:
+        kind, status, reason = 'consistent', Status.PASS, f'{parameter}: assignment matches the fresh reference on supplied probes'
+    return result(a, 'assignment', status, reason, dict(parameter=parameter, value=value, classification=kind,
+                  atol=atol, adapter_assignment_metadata=assigned.assignment_metadata, self_test='passed in baseline, assigned and fresh configurations', probes=rows),
+                  kind if mismatch else None, [*assigned.modifications, *fresh.modifications])
+
+
+def check_order(a, states, actions, *, interval=None, atol=1e-12, order_tolerance=0.5, slope_tolerance=0.5):
+    states, actions = probes(states, actions)
+    atol, order_tolerance, slope_tolerance = map(tolerance, (atol, order_tolerance, slope_tolerance))
+    h = a.dt if interval is None else float(interval)
+    if not np.isfinite(h) or h <= 0: raise ValueError('Interval must be positive and finite')
+    if a.declared_order is None:
+        return result(a, 'order', Status.SKIPPED, 'Missing declared_order')
+    if not np.isfinite(a.declared_order) or a.declared_order <= 0:
+        raise ValueError('declared_order must be positive and finite')
+    modifications = [Modification('timestep', a.dt, h/m, f'Fixed-interval refinement: {m} substeps')
+                     for m in (1,2,4,8) if h/m != a.dt]
+    unknown = [f.name for f in a.features if f.status=='unsupported' and f.present is not False]
+    if a.smooth is not True or a.order_blockers or unknown:
+        return result(a, 'order', Status.PARTIAL, 'Smoothness not established or unsupported features: ' +
+                      ', '.join(a.order_blockers + unknown or ['smooth']), modifications=modifications)
+    blocked = guard(a, 'order', states, actions, [h/m for m in (1,2,4,8)])
+    if blocked:
+        blocked.modifications.extend(modifications)
+        return blocked
+    rows = []
+    try:
+        for s, u in zip(states, actions):
+            endpoints = []
+            for m in (1,2,4,8):
+                x = s.copy()
+                for _ in range(m):
+                    x = a.step(x, u, h/m)
+                    if not np.all(np.isfinite(x)): raise Blowup('Nonfinite refinement trajectory')
+                endpoints.append(x)
+            floor, eps = precision(a, endpoints, atol)
+            d = [a.distance(x,y) for x,y in zip(endpoints, endpoints[1:])]
+            p = [math.log2(d[i]/d[i+1]) for i in (0,1)] if min(d)>floor else [None,None]
+            if eps > 1e-10 or a.noise_floor or p[0] is None:
+                label = 'ABSTAIN'
+            elif abs(p[0]-p[1]) > slope_tolerance:
+                label = 'ABSTAIN'
+            elif p[1] < a.declared_order-order_tolerance:
+                label = 'FAIL'
+            elif p[1] > a.declared_order+order_tolerance:
+                label = 'ABSTAIN'
+            else:
+                label = 'PASS'
+            rows.append(dict(state=s.tolist(), action=np.asarray(u).tolist(), endpoints=[e.tolist() for e in endpoints],
+                             differences=d, floor=floor, slopes=p, status=label))
+    except Unsupported as exc:
+        return result(a, 'order', Status.PARTIAL, str(exc), {'probes': rows}, modifications=modifications)
+    except Blowup as exc:
+        return result(a, 'order', Status.BLOWUP, str(exc), {'probes': rows}, modifications=modifications)
+    labels = {r['status'] for r in rows}
+    status = Status.FAIL if 'FAIL' in labels else Status.PASS if labels=={'PASS'} else Status.ABSTAIN
+    reason = {Status.FAIL:'Resolved order below declaration on one or more supplied probes',
+              Status.PASS:'Stable slopes consistent with declared order on all supplied probes',
+              Status.ABSTAIN:'Order unresolved: precision/noise floor, unstable slopes, or order outside assessment band'}[status]
+    return result(a, 'order', status, reason, dict(interval=h, declared_order=a.declared_order,
+        atol=atol, order_tolerance=order_tolerance, slope_tolerance=slope_tolerance,
+        self_test='passed at all four timesteps', probes=rows), 'integrator_order' if status==Status.FAIL else None, modifications)
+
+
+def check_observation(a, states, actions, *, atol=1e-12):
+    states, actions = probes(states, actions)
+    atol = tolerance(atol)
+    blocked = guard(a, 'observation', states, actions, [a.dt], ['observation','reference_observation'])
+    if blocked: return blocked
+    rows = []
+    try:
+        for s,u in zip(states,actions):
+            observed = np.asarray(a.observe_fn(s.copy(),u,a.dt))
+            reference = np.asarray(a.reference_observe_fn(s.copy(),u,a.dt))
+            if observed.shape != reference.shape: raise ValueError('Observation shapes differ')
+            if not np.all(np.isfinite(observed)) or not np.all(np.isfinite(reference)):
+                raise Blowup('Nonfinite observation')
+            eps = max([float(np.finfo(a.dtype).eps)] + [float(np.finfo(x.dtype).eps) for x in (observed,reference) if x.dtype.kind=='f'])
+            floor = max(atol, a.noise_floor, 8*eps*(1+float(np.max(np.abs(reference)))))
+            error = float(np.max(np.abs(observed.astype(float)-reference.astype(float))))
+            rows.append(dict(state=s.tolist(), action=np.asarray(u).tolist(), observed=observed.tolist(),
+                             reference=reference.tolist(), error=error, floor=floor, low_precision=eps>1e-10))
+    except Unsupported as exc:
+        return result(a, 'observation', Status.SKIPPED, str(exc), {'probes':rows})
+    except Blowup as exc:
+        return result(a, 'observation', Status.BLOWUP, str(exc), {'probes':rows})
+    fail = any(r['error']>r['floor'] for r in rows)
+    uncertain = any(r['low_precision'] for r in rows) or a.noise_floor > 0
+    status = Status.FAIL if fail else Status.ABSTAIN if uncertain else Status.PASS
+    return result(a, 'observation', status,
+        'Observation differs from reference above floor' if fail else
+        'Precision/noise blocks a consistency verdict; above-floor faults can still be flagged' if uncertain else
+        'Observation agrees with reference on supplied probes',
+        dict(atol=atol, self_test='passed', probes=rows), 'observation' if fail else None)

simaudit/cli.py

@@ -0,0 +1,53 @@
+import argparse
+import json
+from pathlib import Path
+import sys
+from . import Report, check_assignment, check_observation, check_order, compare_releases
+from .release import load_factory
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Scoped diagnostics for any simulator through a trusted module:function adapter factory')
+    parser.add_argument('--version',action='version',version='simaudit 0.1.0a1')
+    sub = parser.add_subparsers(dest='check',required=True)
+    for name in ('assignment','order','observation','release'):
+        cmd = sub.add_parser(name)
+        cmd.add_argument('--factory',required=True,help='Trusted Python module:function returning simaudit.Adapter')
+        cmd.add_argument('--probes',required=True,type=Path,help='JSON object with states and actions arrays')
+        cmd.add_argument('--json',type=Path,help='Write full report here')
+        cmd.add_argument('--strict',action='store_true')
+        cmd.add_argument('--atol',type=float,default=1e-13 if name=='release' else 1e-12)
+        if name=='assignment':
+            cmd.add_argument('--parameter',required=True)
+            cmd.add_argument('--value',type=float,required=True)
+        if name=='order': cmd.add_argument('--interval',type=float)
+        if name=='release':
+            cmd.add_argument('--factory-b',help='Explicit second factory for controlled variant comparisons')
+            cmd.add_argument('--python-a',required=True)
+            cmd.add_argument('--python-b',required=True)
+            cmd.add_argument('--steps',type=int,default=5)
+            cmd.add_argument('--timeout',type=float,default=60)
+    args = parser.parse_args(argv)
+    try:
+        data = json.loads(args.probes.read_text())
+        if set(data) != {'states','actions'}: raise ValueError('Probe file must contain exactly states and actions')
+        states,actions = data['states'],data['actions']
+        if args.check=='release':
+            r = compare_releases(args.factory,args.python_a,args.python_b,states,actions,
+                                 steps=args.steps,atol=args.atol,timeout=args.timeout,factory_b=args.factory_b)
+        else:
+            a = load_factory(args.factory)
+            if args.check=='assignment': r = check_assignment(a,args.parameter,args.value,states,actions,atol=args.atol)
+            elif args.check=='order': r = check_order(a,states,actions,interval=args.interval,atol=args.atol)
+            else: r = check_observation(a,states,actions,atol=args.atol)
+        report = Report([r])
+        if args.json: report.write(args.json)
+        print(report.summary())
+        return report.exit_code(args.strict)
+    except (ValueError, TypeError, OSError, ImportError, AttributeError) as exc:
+        print(f'simaudit: configuration error: {exc}',file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

simaudit/pytest_plugin.py

@@ -0,0 +1,43 @@
+"""Optional pytest fixture preserving all six diagnostic statuses."""
+import pytest
+from .report import Report, Status
+
+
+def pytest_addoption(parser):
+    group = parser.getgroup('simaudit')
+    group.addoption('--simaudit-strict',action='store_true',help='Fail session on any non-pass audit result')
+    group.addoption('--simaudit-json',help='Write collected audit results to JSON (serial pytest only)')
+
+
+def pytest_configure(config):
+    config._simaudit_results = []
+    if config.getoption('--simaudit-json') and getattr(config.option,'numprocesses',0):
+        raise pytest.UsageError('--simaudit-json currently requires serial pytest')
+
+
+@pytest.fixture
+def simaudit_check(request):
+    def check(result):
+        # Validate now, before appending to the session report.
+        Report.loads(Report([result]).dumps())
+        request.config._simaudit_results.append(result)
+        request.node.user_properties.append(('simaudit_status',result.status.value))
+        message = Report([result]).summary()
+        if result.status == Status.FAIL: pytest.fail(message,pytrace=False)
+        if result.status != Status.PASS: pytest.skip(message)
+        return result
+    return check
+
+
+def pytest_sessionfinish(session,exitstatus):
+    report = Report(session.config._simaudit_results)
+    path = session.config.getoption('--simaudit-json')
+    if path: report.write(path)
+    if report.results and session.config.getoption('--simaudit-strict') and report.exit_code(True) and exitstatus==0:
+        session.exitstatus = 1
+
+
+def pytest_terminal_summary(terminalreporter,exitstatus,config):
+    if config._simaudit_results:
+        terminalreporter.section('simaudit (original diagnostic statuses)')
+        terminalreporter.write_line(Report(config._simaudit_results).summary())

simaudit/release.py

@@ -0,0 +1,107 @@
+"""Run user factories in separate interpreters with identical inputs, without installing anything."""
+import hashlib
+import importlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import numpy as np
+from .adapters import Adapter
+from .checks import guard, probes, result, tolerance
+from .report import Feature, Report, Status
+
+
+def load_factory(spec):
+    module, separator, name = spec.partition(':')
+    if not separator or not module or not name:
+        raise ValueError('Factory must be module:function (a trusted local Python callable)')
+    return getattr(importlib.import_module(module),name)()
+
+
+def collect(adapter, states, actions, steps=1):
+    states, actions = probes(states,actions)
+    if type(steps) is not int or steps < 1: raise ValueError('steps must be a positive integer')
+    blocked = guard(adapter,'release',states,actions,[adapter.dt])
+    if blocked: return Report([blocked])
+    trajectories = []
+    from .adapters import Blowup
+    try:
+        for s,u in zip(states,actions):
+            path = []
+            for _ in range(steps):
+                s = adapter.step(s,u,adapter.dt)
+                if not np.all(np.isfinite(s)): raise Blowup('Nonfinite release trajectory')
+                path.append(s.tolist())
+            trajectories.append(path)
+    except Blowup as exc:
+        return Report([result(adapter,'release',Status.BLOWUP,str(exc))])
+    return Report([result(adapter,'release',Status.PASS,'Worker replay self-test passed; trajectory collection completed',
+        {'trajectories':trajectories,'dt':adapter.dt,'dtype':adapter.dtype,'noise_floor':adapter.noise_floor})])
+
+
+def compare_releases(factory, python_a, python_b, states, actions, *, steps=5, atol=1e-13, timeout=60, factory_b=None):
+    states, actions = probes(states,actions)
+    atol = tolerance(atol)
+    payload = dict(factory=factory,states=[s.tolist() for s in states],
+                   actions=[np.asarray(u).tolist() for u in actions],steps=steps)
+    encoded = json.dumps(payload,allow_nan=False)
+    adapter = Adapter('isolated releases',features=[Feature('dynamics','tested','Paired worker first steps',True)],
+        scope='Same supplied inputs and factory executed in two explicitly supplied interpreters')
+    workers = []
+    env = dict(os.environ)
+    # Expose ONLY this package to the workers. Putting the caller's site-packages
+    # on PYTHONPATH would shadow each interpreter's own numpy/simulator versions.
+    isolated = tempfile.TemporaryDirectory(prefix='simaudit-worker-')
+    package_dir = Path(__file__).resolve().parent
+    shutil.copytree(package_dir, Path(isolated.name) / 'simaudit',
+                    ignore=shutil.ignore_patterns('__pycache__', '*.pyc'))
+    inherited = env.get('PYTHONPATH')
+    env['PYTHONPATH'] = isolated.name + (os.pathsep + inherited if inherited else '')
+    try:
+        return _run_workers(adapter, payload, encoded, factory, factory_b, python_a, python_b,
+                            atol, timeout, env, workers)
+    finally:
+        isolated.cleanup()
+
+
+def _run_workers(adapter, payload, encoded, factory, factory_b, python_a, python_b, atol, timeout, env, workers):
+    for executable, worker_factory in ((python_a,factory),(python_b,factory_b or factory)):
+        worker_input = json.dumps({**payload, "factory":worker_factory},allow_nan=False)
+        try:
+            run = subprocess.run([str(executable),'-m','simaudit.worker'],input=worker_input,text=True,
+                                 capture_output=True,timeout=timeout,env=env)
+        except (OSError,subprocess.TimeoutExpired) as exc:
+            return result(adapter,'release',Status.SKIPPED,f'Worker unavailable or timed out: {executable}: {exc}',
+                          {'untested_interpreter':str(executable)})
+        if run.returncode:
+            return result(adapter,'release',Status.SKIPPED,f'Worker could not collect: {executable}',
+                          {'stderr':run.stderr[-4000:],'untested_interpreter':str(executable)})
+        worker = Report.loads(run.stdout).results[0]
+        workers.append(worker)
+        if worker.status != Status.PASS:
+            return result(adapter,'release',worker.status,'Worker did not pass: '+worker.reason,
+                          {'worker':json.loads(Report([worker]).dumps())})
+    left,right = workers
+    adapter.versions = {**{f'a:{k}':v for k,v in left.versions.items()},**{f'b:{k}':v for k,v in right.versions.items()}}
+    a,b = [np.asarray(w.evidence['trajectories']) for w in workers]
+    evidence = dict(input_sha256=hashlib.sha256(encoded.encode()).hexdigest(),inputs=payload,atol=atol,
+                    interpreters=[str(python_a),str(python_b)], factories=[factory,factory_b or factory], workers=[json.loads(Report([w]).dumps()) for w in workers])
+    if a.shape!=b.shape or left.evidence['dt']!=right.evidence['dt']:
+        return result(adapter,'release',Status.PARTIAL,'Worker dimensions or timesteps differ; comparison invalid',evidence)
+    first = float(np.max(np.abs(a[:,0]-b[:,0])))
+    evidence['first_step_max_difference'] = first
+    evidence['later_max_difference'] = float(np.max(np.abs(a-b)))
+    low_precision = any(np.finfo(w.evidence['dtype']).eps>1e-10 or w.evidence['noise_floor']>0 for w in workers)
+    evidence['bitwise_identical_recorded_trajectories'] = a.tobytes()==b.tobytes()
+    noise_floor = max(atol, *(w.evidence['noise_floor'] for w in workers))
+    if low_precision:
+        noise_floor = max(noise_floor,*(8*np.finfo(w.evidence['dtype']).eps*(1+np.max(np.abs(a[:,0]))) for w in workers))
+    evidence['effective_floor'] = float(noise_floor)
+    if first > noise_floor:
+        return result(adapter,'release',Status.FAIL,'First-step compatibility change above supplied floor',evidence,'changed_dynamics')
+    if first or low_precision:
+        return result(adapter,'release',Status.ABSTAIN,'First-step difference at/below precision or noise floor',evidence)
+    return result(adapter,'release',Status.PASS,'Recorded first steps agree exactly on supplied probes',evidence)

simaudit/report.py

@@ -0,0 +1,151 @@
+"""Strict report envelope. Evidence is an intentionally open JSON object."""
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+import json
+from pathlib import Path
+
+
+class Status(str, Enum):
+    PASS = "PASS"
+    FAIL = "FAIL"
+    ABSTAIN = "ABSTAIN"
+    SKIPPED = "SKIPPED"
+    PARTIAL = "PARTIAL"
+    BLOWUP = "BLOWUP"
+
+
+COVERAGE = {"tested", "disabled_for_test", "present_not_tested", "unsupported"}
+FEATURES = {"dynamics", "parameters", "observations", "gravity", "springs", "contacts",
+            "joint_limits", "actuators", "damping", "friction", "fluid", "tendons",
+            "equality_constraints", "plugins", "wrappers", "flex", "mocap", "callbacks"}
+
+
+@dataclass
+class Feature:
+    name: str
+    status: str
+    note: str
+    present: bool | None = None
+
+    def __post_init__(self):
+        if not self.name or self.status not in COVERAGE or not self.note:
+            raise ValueError("Invalid feature inventory entry")
+        if self.present is not None and type(self.present) is not bool:
+            raise ValueError("Feature presence must be boolean or null")
+        if self.name not in FEATURES:
+            self.status = "unsupported"
+
+
+@dataclass
+class Modification:
+    name: str
+    before: object
+    after: object
+    reason: str
+
+    def __post_init__(self):
+        if not self.name or not self.reason:
+            raise ValueError("Modification needs a name and reason")
+
+
+@dataclass
+class Result:
+    check: str
+    status: Status
+    reason: str
+    scope: str
+    limitations: list[str]
+    coverage: list[Feature]
+    modifications: list[Modification] = field(default_factory=list)
+    versions: dict[str, str] = field(default_factory=dict)
+    evidence: dict = field(default_factory=dict)
+    fault_class: str | None = None
+
+    def __post_init__(self):
+        self.status = Status(self.status)
+        if not all(isinstance(v, str) and v for v in (self.check, self.reason, self.scope)):
+            raise ValueError("Results require check, reason and scope")
+        if not self.coverage or not all(isinstance(v, Feature) for v in self.coverage):
+            raise ValueError("Coverage is mandatory")
+        if not self.limitations or not all(isinstance(v, str) and v for v in self.limitations):
+            raise ValueError("Limitations are mandatory")
+        if not isinstance(self.evidence, dict) or not isinstance(self.versions, dict):
+            raise ValueError("Evidence and versions must be objects")
+        if not all(isinstance(k, str) and isinstance(v, str) for k, v in self.versions.items()):
+            raise ValueError("Versions must map names to strings")
+        if not all(isinstance(m, Modification) for m in self.modifications):
+            raise ValueError("Invalid modification ledger")
+        if self.fault_class is not None and not isinstance(self.fault_class, str):
+            raise ValueError("Invalid fault class")
+        json.dumps(asdict(self), allow_nan=False)
+
+
+@dataclass
+class Report:
+    results: list[Result]
+    schema_version: str = "1.0"
+
+    def __post_init__(self):
+        if self.schema_version != "1.0":
+            raise ValueError("Unsupported report schema version")
+        if not isinstance(self.results, list) or not all(isinstance(r, Result) for r in self.results):
+            raise ValueError("Invalid results")
+
+    @property
+    def counts(self):
+        return {s.value: sum(r.status == s for r in self.results) for s in Status}
+
+    def exit_code(self, strict=False):
+        return int(not self.results or any(r.status == Status.FAIL or
+                   (strict and r.status != Status.PASS) for r in self.results))
+
+    def dumps(self):
+        return json.dumps(asdict(self), indent=2, allow_nan=False) + "\n"
+
+    def write(self, path):
+        Path(path).write_text(self.dumps(), encoding="utf-8")
+
+    @classmethod
+    def loads(cls, text):
+        def pairs(items):
+            result = {}
+            for k, v in items:
+                if k in result:
+                    raise ValueError(f"Duplicate JSON key: {k}")
+                result[k] = v
+            return result
+        def constant(value):
+            raise ValueError(f"Nonfinite JSON number: {value}")
+        data = json.loads(text, object_pairs_hook=pairs, parse_constant=constant)
+        if not isinstance(data, dict) or set(data) != {"schema_version", "results"}:
+            raise ValueError("Invalid report fields")
+        if data['schema_version'] != '1.0' or not isinstance(data['results'], list):
+            raise ValueError("Unsupported report schema or results")
+        results = []
+        for row in data['results']:
+            if not isinstance(row, dict) or set(row) != set(Result.__dataclass_fields__):
+                raise ValueError("Invalid result fields")
+            row = dict(row)
+            for key, constructor in (("coverage", Feature), ("modifications", Modification)):
+                if not isinstance(row[key], list):
+                    raise ValueError(f"{key} must be a list")
+                entries = []
+                for entry in row[key]:
+                    if not isinstance(entry, dict) or set(entry) != set(constructor.__dataclass_fields__):
+                        raise ValueError(f"Invalid {key} fields")
+                    entries.append(constructor(**entry))
+                row[key] = entries
+            results.append(Result(**row))
+        return cls(results, data['schema_version'])
+
+    def summary(self):
+        lines = []
+        for r in self.results:
+            lines.append(f"{r.status.value} {r.check}: {r.reason} [{r.scope}]")
+            lines.extend(f"  Limit: {v}" for v in r.limitations)
+            lines.extend(f"  Coverage: {f.name}: {f.status} (present={f.present}): {f.note}" for f in r.coverage)
+            lines.extend(f"  Modified: {m.name}: {m.before} -> {m.after}: {m.reason}" for m in r.modifications)
+        lines.append("Counts: " + ", ".join(f"{k}={v}" for k, v in self.counts.items()))
+        if not self.results or any(r.status not in (Status.PASS, Status.FAIL) for r in self.results):
+            lines.append("WARNING: some requested behaviour was not assessed; this is not an all-clear.")
+        return "\n".join(lines)

simaudit/worker.py

@@ -0,0 +1,15 @@
+import json
+from contextlib import redirect_stdout
+import sys
+from .release import collect, load_factory
+
+
+def main():
+    request = json.load(sys.stdin)
+    with redirect_stdout(sys.stderr):
+        report = collect(load_factory(request['factory']),request['states'],request['actions'],request['steps'])
+    sys.stdout.write(report.dumps())
+
+
+if __name__ == '__main__':
+    main()

simaudit-0.1.0a1.data/data/share/simaudit/CITATION.cff

@@ -0,0 +1,37 @@
+cff-version: 1.2.0
+message: "Please cite the two method papers below when using simaudit. Paper authorship is recorded separately from software authorship."
+title: "simaudit: scoped diagnostics for simulators"
+type: software
+version: 0.1.0a1
+date-released: 2026-11-14
+repository-code: "https://github.com/TesfayZ/simaudit"
+keywords:
+  - reinforcement learning
+  - simulator validation
+  - MuJoCo
+  - Gymnasium
+  - numerical verification
+abstract: "Scoped, reproducible diagnostics for user-supplied simulators: parameter-assignment consistency, integrator-order convergence, release comparison and observation consistency, with explicit statements of what was not assessed."
+license: MIT
+authors:
+  - family-names: Gebrekidan
+    given-names: Tesfay Zemuy
+references:
+  - type: article
+    title: "Diagnosing Model and Discretisation Errors in Reinforcement Learning Simulators Using Invariants"
+    authors:
+      - family-names: Gebrekidan
+        given-names: Tesfay Zemuy
+    year: 2026
+    doi: 10.5281/zenodo.24114609
+    url: "https://zenodo.org/records/24114609"
+  - type: article
+    title: "Diagnosing Faults in Reinforcement Learning Simulators with Canonical Polynomial Invariants"
+    authors:
+      - family-names: Gebrekidan
+        given-names: Tesfay Zemuy
+      - family-names: Gebrerufael
+        given-names: Hadush Hailu
+    year: 2026
+    doi: 10.48550/arXiv.2609.13194
+    url: "https://arxiv.org/abs/2609.13194v2"

simaudit-0.1.0a1.data/data/share/simaudit/THIRD_PARTY.md

@@ -0,0 +1,32 @@
+# Method provenance and reuse
+
+The package uses two source papers, with their full authorship preserved:
+
+1. **Tesfay Zemuy Gebrekidan.** *Diagnosing Model and Discretisation Errors in
+   Reinforcement Learning Simulators Using Invariants* (2026).
+   [Zenodo record](https://zenodo.org/records/24114609).
+   Source repository: [`dafd`](https://github.com/TesfayZ/dafd). Assignment consistency, refinement diagnostics,
+   native integrator controls and precision/coverage limitations inform this package.
+2. **Tesfay Zemuy Gebrekidan and Hadush Hailu Gebrerufael.** *Diagnosing Faults in
+   Reinforcement Learning Simulators with Canonical Polynomial Invariants* (2026).
+   [arXiv:2609.13194v2](https://arxiv.org/abs/2609.13194v2).
+   Source repository: [`algebraicRLtest`](https://github.com/TesfayZ/algebraicRLtest). Paired release comparisons, positive
+   controls and observation consistency inform this package. Its algebraic
+   screening/localisation method is not implemented in this alpha.
+
+Both source repositories have MIT licences, copyright 2026 Tesfay Zemuy Gebrekidan.
+That software licence notice does not replace the papers' scholarly authorship.
+The MIT notice is retained in LICENSE. `validation/known_cases.py` adapts the
+minimal heavy-top geometry from `dafd/benchmark_quaternion_mechanism.py`; its
+collision masks are explicitly changed for the conservative test. The small
+checks are new adapter-based implementations of the documented methods. No
+research runner, paper prose, dataset, model or complete source module is vendored.
+Source file hashes inspected during development appear in evidence/reuse_sources.json.
+
+Runtime dependencies are imported, not bundled: NumPy (BSD-3-Clause), Gymnasium
+(MIT, optional), MuJoCo (Apache-2.0, optional), pytest (MIT, optional). A stable
+release still needs a full resolved dependency licence inventory, including
+transitive dependencies. This list does not claim that audit has been completed.
+
+Official interfaces consulted: [MuJoCo API](https://mujoco.readthedocs.io/en/stable/APIreference/APIfunctions.html)
+and [pytest plugin documentation](https://docs.pytest.org/en/stable/how-to/writing_plugins.html).

simaudit-0.1.0a1.data/data/share/simaudit/references.bib

@@ -0,0 +1,17 @@
+@misc{gebrekidan2026dafd,
+  author = {Gebrekidan, Tesfay Zemuy},
+  title = {Diagnosing Model and Discretisation Errors in Reinforcement Learning Simulators Using Invariants},
+  year = {2026},
+  doi = {10.5281/zenodo.24114609},
+  url = {https://zenodo.org/records/24114609}
+}
+@misc{gebrekidanGebrerufael2026canonical,
+  author = {Gebrekidan, Tesfay Zemuy and Gebrerufael, Hadush Hailu},
+  title = {Diagnosing Faults in Reinforcement Learning Simulators with Canonical Polynomial Invariants},
+  year = {2026},
+  eprint = {2609.13194},
+  archivePrefix = {arXiv},
+  primaryClass = {cs.LG},
+  doi = {10.48550/arXiv.2609.13194},
+  url = {https://arxiv.org/abs/2609.13194v2}
+}

simaudit-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: simaudit
+Version: 0.1.0a1
+Summary: Scoped, reproducible diagnostics for user-supplied simulators
+Author: Tesfay Zemuy Gebrekidan
+License-Expression: MIT
+Project-URL: Repository, https://github.com/TesfayZ/simaudit
+Project-URL: Issues, https://github.com/TesfayZ/simaudit/issues
+Project-URL: Documentation, https://github.com/TesfayZ/simaudit#readme
+Keywords: reinforcement-learning,simulator,verification,mujoco,gymnasium,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Framework :: Pytest
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: gymnasium
+Requires-Dist: gymnasium>=1.0; extra == "gymnasium"
+Provides-Extra: mujoco
+Requires-Dist: mujoco>=3.2; extra == "mujoco"
+Requires-Dist: gymnasium>=1.0; extra == "mujoco"
+Provides-Extra: pytest
+Requires-Dist: pytest>=8; extra == "pytest"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: gymnasium>=1.0; extra == "dev"
+Dynamic: license-file
+
+# simaudit
+
+Installable diagnostics for **your own simulator**, with explicit limits on what
+was assessed. Supply a small Python adapter; NumPy is the only core dependency.
+Gymnasium and MuJoCo are optional examples. Version **0.1.0a1** is an alpha,
+not a generally calibrated simulator-certification service.
+
+## Install
+
+```bash
+# Pre-release: pip skips alpha versions unless you ask for them.
+python -m pip install --pre simaudit
+# Optional adapters and pytest integration:
+python -m pip install --pre 'simaudit[gymnasium,mujoco,pytest]'
+# Or from a source checkout:
+python -m pip install .
+```
+
+Python 3.11 or newer (CI matrix 3.11-3.14; local validation on 3.14.6 and 3.12.3). Nothing downloads, runs experiments, or imports an optional
+simulator on package import. For development: `python -m pip install '.[dev]'`.
+
+## Test your own simulator
+
+```python
+import numpy as np
+from simaudit import Adapter, Feature, Report, check_order
+
+# Wrap your simulator so each call restores every dependency of its next step.
+def step(state, action, dt):
+    return state + dt * (state + action)
+
+def native_reference(state, action, dt):
+    return np.asarray([(1 + dt) * state[0] + dt * action])
+
+adapter = Adapter(
+    name="my simulator", step_fn=step, native_step_fn=native_reference,
+    features=[Feature("dynamics", "tested", "Smooth scalar ODE, no hidden state", True)],
+    smooth=True, declared_order=1, dt=0.2,
+)
+result = check_order(adapter, [[0.5], [1.0], [1.5]], [0, 0, 0])
+report = Report([result])
+print(report.summary())
+report.write("audit.json")
+```
+
+The native reference should call the original simulator without the adapter
+transformation being tested. A user-provided reference and inventory are trusted
+inputs, not automatically verified specifications. See [the adapter guide](docs/ADAPTERS.md)
+for mutable simulators, noise, arbitrary state metrics, assignment factories,
+observation maps and capability requirements.
+
+The CLI loads a trusted local `module:function` returning an adapter. From this
+directory, run the included NumPy-only example:
+
+```bash
+PYTHONPATH=examples simaudit order --factory custom_simulator:factory \
+  --probes examples/probes.json --strict --json audit.json
+```
+
+Python factories execute code with your Python process's privileges. Probe files
+contain only `states` and matching `actions`. The same interface works with your
+own importable adapter module. `python -m simaudit` is equivalent to `simaudit`.
+
+## Four independent checks
+
+| Check | Python API | Needs | What it reports |
+|---|---|---|---|
+| Parameter assignment | `check_assignment` | Replay, native reference, assignment factory | Baseline/direct/fresh comparison; no-op, stale, consistent or unresolved |
+| Numerical order | `check_order` | Replay, native reference, timestep, declared order, smoothness, distance | Stable refinement slopes, below-declaration order, or inability to diagnose |
+| Release/variant comparison | `compare_releases` | Factory and two supplied Python interpreters | First-step differences on identical inputs; later differences recorded separately |
+| Observation consistency | `check_observation` | Replay, native reference, observed and reference observation maps | Differences above the precision/noise floor |
+
+The package doesn't implement the papers' energy-fingerprint classifier,
+algebraic localisation, parameter identification or automatic equation diagnosis.
+A numerical-order pass cannot establish that equations are correct.
+
+## Results and limitations
+
+Every result contains **PASS, FAIL, ABSTAIN, SKIPPED, PARTIAL or BLOWUP**, a reason,
+scope, limitations, mandatory feature coverage, modifications, versions and raw
+probe measurements. Limitations and untested features are printed beside results.
+
+- Float32 or a declared noise floor blocks a healthy consistency verdict in
+  checks A, B and D. A and D can still flag discrepancies above their floors.
+- Missing capabilities return `SKIPPED`; unsupported smoothness/features give
+  `PARTIAL`; unresolved or unstable slopes give `ABSTAIN`.
+- Nonfinite trajectories or detected engine resets give `BLOWUP`.
+- A failed adapter replay/native-step self-test blocks downstream diagnosis.
+- `PASS` covers the supplied probes under the declared conditions only. A wrong
+  reference, shared implementation error or unreported hidden state can escape it.
+
+By default `FAIL` exits 1; other nonpasses print a warning and exit 0. `--strict`
+exits 1 on **any** nonpass. Configuration errors exit 2. Empty reports are never
+all-clear. [Report contract](docs/REPORTS.md).
+
+## Optional adapters and releases
+
+```bash
+simaudit assignment --factory simaudit.adapters.cartpole:cartpole \
+  --probes examples/cartpole-probes.json --parameter masscart --value 2 --json cartpole.json
+```
+
+This deliberately detects the paper's assignment discrepancy and exits 1. The
+fresh CartPole reference explicitly rebuilds dependent constants; it does not
+assert that Gymnasium promises arbitrary attribute mutation.
+
+`mujoco_xml(xml)` supplies native replay for smooth autonomous rigid models and
+rejects unsupported features. `reacher()` supplies a cache-consistency comparison
+against the shipped observation map after `mj_forward`. Both live in
+`simaudit.adapters.mujoco`; imports are lazy. Custom adapters are not subject to
+these built-in models' limitations but must declare their own.
+
+For a release pair, create two separate environments yourself, with NumPy and
+the simulator versions you want, then supply their Python paths:
+
+```bash
+simaudit release --factory simaudit.adapters.cartpole:cartpole \
+  --probes examples/cartpole-probes.json --python-a /path/a/bin/python \
+  --python-b /path/b/bin/python --strict --json releases.json
+```
+
+The worker runs the current package source in each interpreter. The package does
+not install or upgrade either environment. Your custom factory module must also
+be importable there. Missing versions remain untested. A changed first step means
+compatibility changed, not necessarily that either release is wrong.
+
+## pytest and verification
+
+Install the `pytest` extra to use the auto-discovered `simaudit_check` fixture:
+
+```python
+def test_simulator(simaudit_check):
+    simaudit_check(check_order(adapter, [[1.0]], [0]))
+```
+
+`FAIL` fails the test; other nonpasses skip with their original status and full
+reason. `pytest --simaudit-strict --simaudit-json results.json` fails the session
+on any nonpass and preserves the separate audit counts. Reporting is serial;
+pytest-xdist aggregation is not supported.
+
+Run software tests with `python -m pytest`. Build with
+`python -m build`. See [validation results](VALIDATION.md),
+[prospective paper-case protocol](validation/PROTOCOL.md), and
+[requirements and acceptance criteria](docs/REQUIREMENTS.md). These are small package tests
+and selected reproductions, not a general false-alarm guarantee.
+
+## Cite the two method papers
+
+1. **Tesfay Zemuy Gebrekidan** (2026). *Diagnosing Model and Discretisation Errors
+   in Reinforcement Learning Simulators Using Invariants*.
+   [Zenodo](https://zenodo.org/records/24114609).
+2. **Tesfay Zemuy Gebrekidan and Hadush Hailu Gebrerufael** (2026).
+   *Diagnosing Faults in Reinforcement Learning Simulators with Canonical
+   Polynomial Invariants*. [arXiv:2609.13194v2](https://arxiv.org/abs/2609.13194v2).
+
+[CITATION.cff](CITATION.cff), [BibTeX](references.bib), and
+[reuse and licence notices](THIRD_PARTY.md) preserve the attribution. MIT licensed.
+
+## What it has found so far
+
+From [VALIDATION.md](VALIDATION.md); each row is scoped to the supplied probes.
+
+| Case | Result |
+|---|---|
+| Gymnasium CartPole `masscart`/`masspole`/`length` assignment | FAIL (no-op / stale / partly stale) vs a freshly constructed reference; `gravity` PASS |
+| MuJoCo 3.16.0 and 3.17.0, RK4 heavy top on a ball joint | FAIL: 23/24 probes below declared order 4 (1/24 ABSTAIN), median slope 1.96 |
+| MuJoCo **4.0.1**, same model and probes | PASS 24/24, median slope 3.92 |
+| Same model with three hinges (control) | PASS in every tested engine |
+| Reacher post-step observation vs refreshed map | FAIL, largest discrepancy 2.4e-6 (3.16.0, 3.17.0 and 4.0.1) |
+
+MuJoCo 4.0.0 itself was not installed or tested; no result is inferred for it.
+
+## Roadmap
+
+Not implemented in 0.1.0a1, and not claimed anywhere in this package:
+
+- **0.2:** energy-refinement fingerprint (model-versus-discretisation label), a
+  decision table combining checks, and a one-parameter fit, each only with its
+  negative-control suite passing.
+- **0.3:** algebraic invariant screening behind an optional extra.
+- Other classic-control assignment adapters, vector environments, and shipped
+  Ant/Humanoid with contacts and actuation.
+
+## Documentation
+
+| File | Purpose |
+|---|---|
+| [docs/ADAPTERS.md](docs/ADAPTERS.md) | Writing an adapter and declaring its features |
+| [docs/REPORTS.md](docs/REPORTS.md) | Report schema, statuses and JSON round trip |
+| [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) | Acceptance criteria recorded before validation |
+| [VALIDATION.md](VALIDATION.md) | What was actually run, and the limits of those runs |
+| [validation/PROTOCOL.md](validation/PROTOCOL.md) | Paper-case protocol and scripts |
+| [evidence/README.md](evidence/README.md) | Archived result files and the hash receipt |
+| [CHANGELOG.md](CHANGELOG.md) | Release history |

simaudit-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,21 @@
+simaudit/__init__.py,sha256=72i1TW3JwB8nZQngmorSyqPkWs7DNHRvlJmZXM2JEso,510
+simaudit/__main__.py,sha256=ee5vE0xcUZM3fPmxicvcw-IJXkm6nOwxARREHBWpF8Q,47
+simaudit/checks.py,sha256=tJ2xOXeXknYaDjHAvWHXVDeVyjn8tWjXiXj8z3kobo8,12885
+simaudit/cli.py,sha256=cbLvgDMHoSfsQ449SbRhfnE2nWmOpfr_vPM7CkmQYuw,2880
+simaudit/pytest_plugin.py,sha256=ms_dBO4Zhq6qNUl-Huc_SFtqHHicmHVnPXBWZEGKCKs,1782
+simaudit/release.py,sha256=ldZ9Sud5pFkjfcBeZTK4Kzxi634DLUP87XE7BzWZzMc,6089
+simaudit/report.py,sha256=aQsiucHHURd987gBunbg0Gtx74W1rRP6PsoyOMn2DrE,6214
+simaudit/worker.py,sha256=WUBkt-12weqJGzjRP7j61X6-w3r4Nk8X6xUgfZh8kQo,382
+simaudit/adapters/__init__.py,sha256=SFI5Twz2WGyfIhvqg8152hgtpa7xsny9sEg-olr7fhg,95
+simaudit/adapters/base.py,sha256=fODSkr5UEyrAptJ8_vtrkS09B3-b2iqs0ZvZ3TTdUzs,2757
+simaudit/adapters/cartpole.py,sha256=1Dy6fMgQ4RJgH16VmMRzQxVldzt36CF2O2CtQgRddcs,3140
+simaudit/adapters/mujoco.py,sha256=jLt38BdpdkodfZcp228kybHBotUvaX13q8Ma-6i_MAY,5884
+simaudit-0.1.0a1.data/data/share/simaudit/CITATION.cff,sha256=nshC08u1HzbTEzzL8sxk_E-V875RMeysWNP8VQviX0Y,1438
+simaudit-0.1.0a1.data/data/share/simaudit/THIRD_PARTY.md,sha256=e9W7z0-ZMhYk7NxAG_HGnYYDsH7NDM4GDJgfLhY5cG8,2174
+simaudit-0.1.0a1.data/data/share/simaudit/references.bib,sha256=ToEgAMwAe0WVhB-DZ6xRR-SKk2WpzEEGu3LXKDn7Qko,670
+simaudit-0.1.0a1.dist-info/licenses/LICENSE,sha256=9iJOTYwCvmsf7jyd4zbJfz7wgnnnJDsMzvxyMlQJgdg,1080
+simaudit-0.1.0a1.dist-info/METADATA,sha256=G8J_WNLF0_Y5jhgr5ImfupSK1PB6Vu9bMP-bf_D11Ag,10768
+simaudit-0.1.0a1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+simaudit-0.1.0a1.dist-info/entry_points.txt,sha256=JdH2N1T89mxJsBo6GLRsuRhlpgrgvyzl5m3Bc-ATWpw,93
+simaudit-0.1.0a1.dist-info/top_level.txt,sha256=plyGr4pRC9fpDN4ehfAjOq5jGkne-D7RLhEBHhEmqqE,9
+simaudit-0.1.0a1.dist-info/RECORD,,

simaudit-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simaudit-0.1.0a1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+simaudit = simaudit.cli:main
+
+[pytest11]
+simaudit = simaudit.pytest_plugin

simaudit-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tesfay Zemuy Gebrekidan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simaudit-0.1.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+simaudit