|
|
|
@@ -0,0 +1,307 @@
|
|
|
|
|
# Gameplay Math and Numeric Semantics
|
|
|
|
|
|
|
|
|
|
Domain: VM numeric execution and mathematical intrinsics
|
|
|
|
|
Function: normative
|
|
|
|
|
|
|
|
|
|
Didactic companion: [Portable math requires a runtime-owned numeric contract](../../../discussion/lessons/DSC-0053-gameplay-math-and-numeric-semantics/LSN-0062-portable-math-requires-a-runtime-owned-numeric-contract.md).
|
|
|
|
|
|
|
|
|
|
## Ownership and reproducibility
|
|
|
|
|
|
|
|
|
|
The VM owns numeric semantics, implementations, exact intrinsic signatures,
|
|
|
|
|
constants and virtual cycle costs. With the same cartridge, numeric contract
|
|
|
|
|
and inputs, supported runtime builds MUST produce identical result bits,
|
|
|
|
|
faults and cycles. Mathematical error bounds measure deviation from the ideal
|
|
|
|
|
function; they are never a tolerance between hosts.
|
|
|
|
|
|
|
|
|
|
Float is finite IEEE 754 binary64. Its physical f64 carrier transports bits;
|
|
|
|
|
guest arithmetic MUST use the canonical software backend. ADD/SUB/MUL/DIV,
|
|
|
|
|
conversion to Float and sqrt round correctly to the nearest representable
|
|
|
|
|
value, ties to even. Preserve gradual underflow, subnormals and signed zeros.
|
|
|
|
|
Underflow to subnormal or signed zero is valid; finite overflow faults.
|
|
|
|
|
No fast-math, reassociation or implicit multiply-add fusion is allowed.
|
|
|
|
|
|
|
|
|
|
The reference uses fpmath exactly 0.1.1 with soft-float and the dependency
|
|
|
|
|
resolution in Cargo.lock. The VM adapter supplies the selected rounding,
|
|
|
|
|
domains, signed zeros, conversions and fault mapping. Private algorithm
|
|
|
|
|
temporaries are not guest instructions; published vector steps below are
|
|
|
|
|
canonical binary64 operations.
|
|
|
|
|
|
|
|
|
|
Existing integer wrapping and arithmetic-opcode promotions remain unchanged:
|
|
|
|
|
Int32/Int64 ADD/SUB/MUL/NEG wrap; MIN/-1 returns MIN; MIN%-1 returns zero.
|
|
|
|
|
Integer division truncates toward zero and remainder has the dividend sign:
|
|
|
|
|
-7/3=-2 and -7%3=-1. Integer division/modulo by zero faults.
|
|
|
|
|
Mixed Float opcode operands convert integers through the software conversion
|
|
|
|
|
before computing. This does not authorize coercion at Registry or intrinsic
|
|
|
|
|
boundaries. Numeric Float comparisons use software conversion/comparison;
|
|
|
|
|
+0 and -0 compare equal.
|
|
|
|
|
|
|
|
|
|
Native acceleration is optional and MUST preserve exact bits, faults and
|
|
|
|
|
cycles per operation/host. A runtime recognizing old vec2 IDs is not thereby
|
|
|
|
|
qualified for this numeric contract.
|
|
|
|
|
|
|
|
|
|
## Public surface and exact catalog
|
|
|
|
|
|
|
|
|
|
The intended consumer surface uses math for Int32/Int64 overloads and mathf
|
|
|
|
|
for Float functions. Names identify namespaces, not guest types or receivers.
|
|
|
|
|
A frontend resolves overloads at compile time to an exact identity.
|
|
|
|
|
Mixed intrinsic carriers require explicit conversion.
|
|
|
|
|
|
|
|
|
|
[INTRINSICS.csv](../../vm-arch/INTRINSICS.csv) is generated from runtime
|
|
|
|
|
metadata: ID, owner/name/version, ordered ABI layout, parameter names,
|
|
|
|
|
total call cost and determinism/guest-allocation flags.
|
|
|
|
|
[BUILTIN_CONSTANTS.csv](../../vm-arch/BUILTIN_CONSTANTS.csv) publishes constant
|
|
|
|
|
slots and Float bits. Consumers MUST use these artifacts rather than duplicate
|
|
|
|
|
ID/cost maps. Math functions are pure and allocate no guest objects; runtime
|
|
|
|
|
result/scratch reservations remain possible.
|
|
|
|
|
|
|
|
|
|
All scalar entries below have version 1. vec2.dot/length retain version 1
|
|
|
|
|
and existing IDs with the behavior and costs specified here.
|
|
|
|
|
|
|
|
|
|
| ID | Exact identity | Ordered signature | Call cycles |
|
|
|
|
|
| --- | --- | --- | ---: |
|
|
|
|
|
| 0x3000 | math.i32.min | (a:Int32,b:Int32)->Int32 | 2 |
|
|
|
|
|
| 0x3001 | math.i32.max | (a:Int32,b:Int32)->Int32 | 2 |
|
|
|
|
|
| 0x3002 | math.i32.clamp | (value:Int32,min:Int32,max:Int32)->Int32 | 4 |
|
|
|
|
|
| 0x3003 | math.i32.abs | (value:Int32)->Int32 | 2 |
|
|
|
|
|
| 0x3004 | math.i64.min | (a:Int64,b:Int64)->Int64 | 2 |
|
|
|
|
|
| 0x3005 | math.i64.max | (a:Int64,b:Int64)->Int64 | 2 |
|
|
|
|
|
| 0x3006 | math.i64.clamp | (value:Int64,min:Int64,max:Int64)->Int64 | 4 |
|
|
|
|
|
| 0x3007 | math.i64.abs | (value:Int64)->Int64 | 2 |
|
|
|
|
|
| 0x3008 | mathf.min | (a:Float,b:Float)->Float | 2 |
|
|
|
|
|
| 0x3009 | mathf.max | (a:Float,b:Float)->Float | 2 |
|
|
|
|
|
| 0x300A | mathf.clamp | (value:Float,min:Float,max:Float)->Float | 4 |
|
|
|
|
|
| 0x300B | mathf.abs | (value:Float)->Float | 2 |
|
|
|
|
|
| 0x300C | mathf.floor | (value:Float)->Float | 4 |
|
|
|
|
|
| 0x300D | mathf.ceil | (value:Float)->Float | 4 |
|
|
|
|
|
| 0x300E | mathf.trunc | (value:Float)->Float | 4 |
|
|
|
|
|
| 0x300F | mathf.round | (value:Float)->Float | 4 |
|
|
|
|
|
| 0x3010 | mathf.sqrt | (value:Float)->Float | 16 |
|
|
|
|
|
| 0x3011 | mathf.sin | (angle:Float)->Float | 32 |
|
|
|
|
|
| 0x3012 | mathf.cos | (angle:Float)->Float | 32 |
|
|
|
|
|
| 0x3013 | mathf.atan2 | (y:Float,x:Float)->Float | 48 |
|
|
|
|
|
| 0x3014 | math.i32.to_i64 | (value:Int32)->Int64 | 2 |
|
|
|
|
|
| 0x3015 | math.i64.to_i32 | (value:Int64)->Int32 | 2 |
|
|
|
|
|
| 0x3016 | math.i32.to_float | (value:Int32)->Float | 2 |
|
|
|
|
|
| 0x3017 | math.i64.to_float | (value:Int64)->Float | 2 |
|
|
|
|
|
| 0x3018 | mathf.to_i32 | (value:Float)->Int32 | 2 |
|
|
|
|
|
| 0x3019 | mathf.to_i64 | (value:Float)->Int64 | 2 |
|
|
|
|
|
| 0x1000 | vec2.dot | (ax:Float,ay:Float,bx:Float,by:Float)->Float | 10 |
|
|
|
|
|
| 0x1001 | vec2.length | (x:Float,y:Float)->Float | 40 |
|
|
|
|
|
|
|
|
|
|
There are no identity conversions. Public conversions follow the source
|
|
|
|
|
carrier: math.to_float(Int32/Int64), math.to_i64(Int32), math.to_i32(Int64),
|
|
|
|
|
mathf.to_i32(Float), mathf.to_i64(Float).
|
|
|
|
|
|
|
|
|
|
## Limits, rounding and conversions
|
|
|
|
|
|
|
|
|
|
min/max return the numerical limit. Equal nonzero inputs have identical bits.
|
|
|
|
|
Equal-sign zeros retain their sign; opposite zeros return -0 for min and +0
|
|
|
|
|
for max, in either argument order. Float abs clears the sign bit; integer
|
|
|
|
|
abs(MIN) faults NUMERIC_RANGE.
|
|
|
|
|
|
|
|
|
|
clamp validates all arguments, requires min<=max numerically, then evaluates
|
|
|
|
|
min(max(value,min),max) under these zero rules. Opposite zero limits are
|
|
|
|
|
numerically equal and valid. Invalid limits fault NUMERIC_DOMAIN; do not
|
|
|
|
|
silently swap or correct them.
|
|
|
|
|
|
|
|
|
|
floor, ceil, trunc and round return Float. For -2.7, the first three yield
|
|
|
|
|
-3, -2 and -2. round ties to even: 2.5->2, 3.5->4, -2.5->-2.
|
|
|
|
|
Preserve zero input signs; a nonzero input rounding to zero uses its sign.
|
|
|
|
|
|
|
|
|
|
Float-to-integer conversion checks finitude, truncates toward zero, then
|
|
|
|
|
checks the exact truncated value against [-2^31,2^31-1] or [-2^63,2^63-1].
|
|
|
|
|
MUST NOT saturate or use Float(Int64 MAX) as an inclusive upper bound.
|
|
|
|
|
Int64-to-Int32 requires range. Int32-to-Int64 is exact.
|
|
|
|
|
Integer-to-Float uses nearest/ties-to-even; Int64 precision can be lost.
|
|
|
|
|
Float -0 converts to integer zero.
|
|
|
|
|
|
|
|
|
|
| Expression | Result or fault |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| mathf.to_i32(3.9) / mathf.to_i32(-3.9) | 3 / -3 |
|
|
|
|
|
| mathf.to_i32(-2147483648.9) | Int32 MIN; the truncated value fits |
|
|
|
|
|
| mathf.to_i32(2147483648.0) | NUMERIC_RANGE |
|
|
|
|
|
| mathf.to_i64(-2^63 as Float) | Int64 MIN |
|
|
|
|
|
| mathf.to_i64(+2^63 as Float) | NUMERIC_RANGE |
|
|
|
|
|
| math.to_float(Int64 MAX) | Float bits 0x43E0000000000000, equal to +2^63 |
|
|
|
|
|
| Convert that Float back to Int64 | NUMERIC_RANGE |
|
|
|
|
|
| math.to_float(Int64 9007199254740993) | 9007199254740992, ties-to-even |
|
|
|
|
|
|
|
|
|
|
## Angles, constants and signed axes
|
|
|
|
|
|
|
|
|
|
Angles use radians. sin/cos accept every finite binary64 angle, including very
|
|
|
|
|
large arguments. Controlled argument reduction is part of the reference;
|
|
|
|
|
x%tau alone is insufficient. Functions act on the supplied binary64 value;
|
|
|
|
|
sin(pi) is not snapped to zero because binary64 pi approximates π.
|
|
|
|
|
|
|
|
|
|
| Constant | Binary64 bits |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| mathf.pi | 0x400921FB54442D18 |
|
|
|
|
|
| mathf.tau | 0x401921FB54442D18 |
|
|
|
|
|
| Internal pi/2 for atan2 axes | 0x3FF921FB54442D18 |
|
|
|
|
|
|
|
|
|
|
pi/tau load through existing constant instructions and their ordinary cost.
|
|
|
|
|
They are not intrinsic calls or host-computed literals.
|
|
|
|
|
sqrt(-0)=-0, abs(-0)=+0, sin(+/-0)=+/-0 and cos(+/-0)=1.
|
|
|
|
|
sqrt of a finite negative nonzero value faults NUMERIC_DOMAIN.
|
|
|
|
|
|
|
|
|
|
atan2 takes y first, x second. All four signed-zero combinations with
|
|
|
|
|
x=y=0 fault NUMERIC_DOMAIN. Other axes are fixed:
|
|
|
|
|
|
|
|
|
|
| Inputs | Result |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| atan2(+0,x>0) / atan2(-0,x>0) | +0 / -0 |
|
|
|
|
|
| atan2(+0,x<0) / atan2(-0,x<0) | +pi / -pi |
|
|
|
|
|
| atan2(y>0,+/-0) | +pi/2 |
|
|
|
|
|
| atan2(y<0,+/-0) | -pi/2 |
|
|
|
|
|
|
|
|
|
|
## Vector sequences
|
|
|
|
|
|
|
|
|
|
Validate every carrier and then every Float input before calculating.
|
|
|
|
|
dot executes p1=ax*bx, p2=ay*by, result=p1+p2. Every step rounds to binary64
|
|
|
|
|
and checks range. Intermediate overflow faults even if the ideal final
|
|
|
|
|
expression could cancel. No FMA or wider accumulator is allowed.
|
|
|
|
|
|
|
|
|
|
length executes this canonical scaled sequence:
|
|
|
|
|
|
|
|
|
|
ax = abs(x); ay = abs(y)
|
|
|
|
|
m = max(ax, ay); n = min(ax, ay)
|
|
|
|
|
if m == 0: return +0
|
|
|
|
|
r = n / m
|
|
|
|
|
q = r * r
|
|
|
|
|
s = 1 + q
|
|
|
|
|
t = sqrt(s)
|
|
|
|
|
return m * t
|
|
|
|
|
|
|
|
|
|
Each step rounds independently; underflow in r/q is permitted. Final overflow
|
|
|
|
|
faults NUMERIC_RANGE. This specifies a sequence, not one rounding of ideal
|
|
|
|
|
hypot. Both branches cost 40 cycles.
|
|
|
|
|
|
|
|
|
|
| Example | Result or fault |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| length(1e200,0) | 1e200 without squaring 1e200 |
|
|
|
|
|
| length(binary64 bits 0x0000000000000001,0) | bits 0x0000000000000001 |
|
|
|
|
|
| length(-0,-0) | +0 |
|
|
|
|
|
| length(MAX_FINITE,MAX_FINITE) | NUMERIC_RANGE |
|
|
|
|
|
| dot(MAX_FINITE,MAX_FINITE,2,-2) | NUMERIC_RANGE at the first multiplication |
|
|
|
|
|
| min(-0,+0) / max(-0,+0) | -0 / +0 |
|
|
|
|
|
| clamp(-0,+0,1) | +0 |
|
|
|
|
|
| clamp(0,2,1) / atan2(0,0) / abs(Int32 MIN) | NUMERIC_DOMAIN / NUMERIC_DOMAIN / NUMERIC_RANGE |
|
|
|
|
|
|
|
|
|
|
## Faults, admission and virtual cycles
|
|
|
|
|
|
|
|
|
|
| Fault | ID | Meaning |
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
| TRAP_NUMERIC_DOMAIN | 0x00000012 | Finite arguments outside the mathematical domain |
|
|
|
|
|
| TRAP_NUMERIC_RANGE | 0x00000013 | Finite input whose result/destination cannot be represented |
|
|
|
|
|
| TRAP_NON_FINITE | 0x00000014 | NaN or infinite input |
|
|
|
|
|
| TRAP_DIV_ZERO | 0x0000000A | Numerical zero divisor, including either signed Float zero |
|
|
|
|
|
|
|
|
|
|
Use existing TrapInfo interruption and available PC/opcode/source span.
|
|
|
|
|
Messages identify operation and argument when applicable. Do not panic Rust,
|
|
|
|
|
coerce invalid inputs to zero or add guest-catchable exceptions.
|
|
|
|
|
Precedence is structure/height/types, all nonfinite inputs in parameter order,
|
|
|
|
|
domain/divisor zero, then range/result. NaN/0 faults NON_FINITE; 1/0 DIV_ZERO.
|
|
|
|
|
Native signature import checks all declared layouts before finitude and
|
|
|
|
|
refuses invalid values before publishing guest slots. Public native stack
|
|
|
|
|
import push returns VmFault::Trap(NON_FINITE) for a nonfinite Float and
|
|
|
|
|
VmFault::ResourceLimit for quota refusal. Current HostReturn producers do not
|
|
|
|
|
expose a Float result writer.
|
|
|
|
|
|
|
|
|
|
Loading checks declared instruction ranges, including unreachable code:
|
|
|
|
|
|
|
|
|
|
- Unknown/unsupported intrinsic: LOAD_INVALID_CODE/NativeId, function/PC and
|
|
|
|
|
referenced_id. Runtime TRAP_INVALID_INTRINSIC is a defensive invariant check;
|
|
|
|
|
an unknown identity has no mathematical attempt cost.
|
|
|
|
|
- NaN/infinite constant: LOAD_INVALID_FORMAT/NonFiniteValue with section,
|
|
|
|
|
file offset and constant index.
|
|
|
|
|
- NaN/infinite PushF64: LOAD_INVALID_CODE/NonFiniteValue with function/PC and
|
|
|
|
|
available offset context.
|
|
|
|
|
- Structural decoding/tag/truncation errors retain their categories and
|
|
|
|
|
precede classifying the corresponding numerical payload.
|
|
|
|
|
|
|
|
|
|
No PBX version/encoding change is introduced.
|
|
|
|
|
|
|
|
|
|
Known mathematical calls admitted by positive budget charge their full cost
|
|
|
|
|
once before validation, scratch reservations and execution, including
|
|
|
|
|
type/domain/range/nonfinite/resource failures. No generic extra INTRINSIC
|
|
|
|
|
cycle or refund. Zero budget does not begin or charge a call; positive budget
|
|
|
|
|
admits the complete call and can overshoot. Private steps add no guest costs.
|
|
|
|
|
Argument-producing instructions are charged separately. Unrelated
|
|
|
|
|
input/color intrinsic costs/accounting and arithmetic opcode costs/accounting
|
|
|
|
|
remain unchanged.
|
|
|
|
|
|
|
|
|
|
## Consumer examples and emission
|
|
|
|
|
|
|
|
|
|
These examples document the runtime contract for frontend implementers.
|
|
|
|
|
Frontend integration is pending: namespace/free-function projection is not
|
|
|
|
|
an already-delivered PBS parser/lowering feature. No Math guest type,
|
|
|
|
|
receiver, syscall or duplicate numeric backend is required.
|
|
|
|
|
|
|
|
|
|
| Typed source expression | Required identity/emission | Call cycles |
|
|
|
|
|
| --- | --- | ---: |
|
|
|
|
|
| math.min(a,b), both Int32 | Push a,b; INTRINSIC 0x3000 | 2 |
|
|
|
|
|
| math.clamp(value,min,max), all Int64 | Push value,min,max; INTRINSIC 0x3006 | 4 |
|
|
|
|
|
| math.to_float(counter), Int64 | Push counter; INTRINSIC 0x3017 | 2 |
|
|
|
|
|
| mathf.to_i32(position), Float | Push position; INTRINSIC 0x3018 | 2 |
|
|
|
|
|
| mathf.atan2(y,x), both Float | Push y,x in that order; INTRINSIC 0x3013 | 48 |
|
|
|
|
|
| mathf.sin(0.0), Float literal | Load +0; INTRINSIC 0x3011; preserve call | 32 |
|
|
|
|
|
| mathf.pi | Existing constant load, canonical bits; no intrinsic | ordinary load cost |
|
|
|
|
|
| math.min(a,b), Int32 and Int64 | Require explicit conversion; no exact mixed signature | no call until resolved |
|
|
|
|
|
|
|
|
|
|
For a Float literal position -3.9, explicit conversion can emit:
|
|
|
|
|
|
|
|
|
|
PUSH_F64 f64:0xC00F333333333333
|
|
|
|
|
INTRINSIC 0x3018
|
|
|
|
|
|
|
|
|
|
It returns Int32 -3. The constant load costs 2 and the call costs 2.
|
|
|
|
|
For direction (y=1,x=0), preserving argument order:
|
|
|
|
|
|
|
|
|
|
PUSH_F64 f64:0x3FF0000000000000
|
|
|
|
|
PUSH_F64 f64:0x0000000000000000
|
|
|
|
|
INTRINSIC 0x3013
|
|
|
|
|
|
|
|
|
|
It returns bits 0x3FF921FB54442D18; the two loads plus call cost 52.
|
|
|
|
|
pi can use PUSH_F64 f64:0x400921FB54442D18 or the constant pool.
|
|
|
|
|
Mathematical executable expressions MUST retain calls even with literal
|
|
|
|
|
arguments in the initial consumer contract. Future folding requires exact
|
|
|
|
|
result/fault/cycle equivalence, not host libm evaluation.
|
|
|
|
|
|
|
|
|
|
## Qualification and evidence
|
|
|
|
|
|
|
|
|
|
Fundamentals and sqrt require correct rounding; limits/rounding functions
|
|
|
|
|
require the exact semantic result. sin/cos/atan2 require absolute error
|
|
|
|
|
strictly below 1 ULP of the ideal result of exact binary64 inputs. For normal
|
|
|
|
|
ideal results, ULP=2^(floor(log2(abs(result)))-52); for subnormal/zero it is
|
|
|
|
|
2^-1074. Exact special cases also preserve documented bits/signs. Vector
|
|
|
|
|
accuracy follows the prescribed sequence.
|
|
|
|
|
|
|
|
|
|
Qualification uses independent MPFR with exact binary64 import, directed
|
|
|
|
|
bounds and adaptive precision. Emulate exponent limits and gradual underflow
|
|
|
|
|
for reference rounding. MPFR is tooling, never cartridge execution.
|
|
|
|
|
Combine critical/random/extreme fixtures with reference source/upstream
|
|
|
|
|
audits; sampling alone is not proof over all binary64. Record compiler,
|
|
|
|
|
target/profile/features, lockfile/backend revision and catalog snapshot.
|
|
|
|
|
Reference changes require requalification, without pinning the entire
|
|
|
|
|
workspace's stable toolchain.
|
|
|
|
|
|
|
|
|
|
Local evidence covers available macOS/aarch64 debug/release. Reproduce the
|
|
|
|
|
same portable corpus on macOS/x86_64 and Linux/x86_64 headless when execution
|
|
|
|
|
infrastructure becomes available; compare exact bits/faults/cycles in both
|
|
|
|
|
profiles. Cross-architecture runs remain pending. Cross-compilation is build
|
|
|
|
|
evidence only. Hardware acquisition, frontend integration and new
|
|
|
|
|
graphical/audio hosts are not prerequisites for local qualification.
|
|
|
|
|
Benchmark real execution separately; never interpret virtual costs as CPU
|
|
|
|
|
timings or relax numeric guarantees to improve performance.
|
|
|
|
|
|
|
|
|
|
Generate/check catalogs:
|
|
|
|
|
|
|
|
|
|
cargo run -p prometeu-vm --example export_numeric_catalog
|
|
|
|
|
cargo run -p prometeu-vm --example export_numeric_catalog -- constants
|
|
|
|
|
|
|
|
|
|
The independent harness is scripts/qualify-numeric.py and the bit probe is
|
|
|
|
|
the numeric_probe example. Portable fixed fixtures reside in
|
|
|
|
|
crates/console/prometeu-vm/tests/fixtures/numeric-conformance.tsv.
|
|
|
|
|
|
|
|
|
|
The versioned [local qualification record](../../vm-arch/NUMERIC_QUALIFICATION.md)
|
|
|
|
|
reports the executed configuration, source audit, observed precision and
|
|
|
|
|
timings, reproducible commands and pending host comparisons.
|