Files
aevolution/tests/cellular_kinematics_tests.cpp
dingoandClaude Opus 5.5 ab5df35c3f
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m24s
Foundation / postgres-tools (push) Successful in 27s
Foundation / server-image (push) Successful in 4m5s
Foundation / image (push) Successful in 4m17s
feat(biology): liquid-relative cellular kinematics and the Git tuning file
Phase 1 of the region and movement plan. Adds the shared integer motion step:
Q10 velocity relative to the liquid, a 16-bit heading with a rate-limited turn,
funded forward/reverse thrust (unfunded thrust coasts), braking, separate forward
and lateral drag that decays to exactly zero, local flow, and a sub-micrometre
carry with no rounding drift. A golden trajectory digest matches across g++-14,
clang-19 and MSVC, so the server and client predictor agree exactly.

Adds deploy/kubernetes/region/dev/tuning/cellular.tuning with every v0 trial value
and a strict parser (unknown, missing, duplicate, out-of-range and inconsistent
values are refused) plus founder handling derived from it. Refreshes the DEV
session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 16:30:51 -04:00

279 lines
11 KiB
C++

#include "evo/biology/cellular_kinematics.hpp"
#include <cstdint>
#include <cstdio>
#include <cstdlib>
#include <source_location>
#include <stdexcept>
#include <string>
namespace {
using namespace evo::biology;
void check(bool value, std::source_location at = std::source_location::current()) {
if (!value)
throw std::runtime_error("cellular kinematics line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
constexpr CellularArea area{60'000, 60'000};
constexpr CellularPosition middle{30'000, 30'000};
constexpr std::uint32_t extent = 20;
constexpr evo::accounting::Picojoules plenty{1'000'000'000};
constexpr std::int32_t um_per_s = 1'024; // Q10 velocity of 1 um/s.
// v0 founder handling: 400 um/s^2 thrust, k = 2 /s drag, one turn per second.
CellularHandling founder() {
return {.thrust_q10 = 400 * um_per_s / 20,
.reverse_thrust_q10 = 400 * um_per_s / 20,
.forward_drag_ppm = 95'163,
.lateral_drag_ppm = 95'163,
.turn = 3'277,
.thrust_cost = {1'000},
.reverse_cost = {1'000}};
}
CellularKinematicsResult step(CellularPosition position, const CellularMotionState& state,
CellularPropulsion propulsion, const CellularHandling& handling,
CellularFlowSample flow = {},
evo::accounting::Picojoules energy = plenty) {
const auto result =
step_cellular_kinematics(area, position, extent, state, propulsion, handling, flow, energy);
check(result.has_value());
return *result;
}
std::int64_t heading_error(std::uint16_t a, std::uint16_t b) {
const auto difference = static_cast<std::int16_t>(static_cast<std::uint16_t>(a - b));
return std::abs(static_cast<std::int64_t>(difference));
}
void trigonometry() {
CHECK(cellular_cos_q14(0) == 16'384 && cellular_sin_q14(0) == 0);
CHECK(cellular_sin_q14(16'384) == 16'384 && cellular_cos_q14(16'384) == 0);
CHECK(cellular_cos_q14(32'768) == -16'384 && cellular_sin_q14(32'768) == 0);
CHECK(cellular_sin_q14(49'152) == -16'384);
CHECK(cellular_sin_q14(8'192) == 11'585 && cellular_cos_q14(8'192) == 11'585);
for (std::uint32_t h = 1; h < cellular_heading_turn; ++h) {
const auto heading = static_cast<std::uint16_t>(h);
const std::int64_t s = cellular_sin_q14(heading), c = cellular_cos_q14(heading);
CHECK(std::abs(s * s + c * c - std::int64_t{16'384} * 16'384) <= std::int64_t{4} * 16'384);
CHECK(cellular_sin_q14(static_cast<std::uint16_t>(cellular_heading_turn - h)) == -s);
}
}
void headings() {
CHECK(cellular_heading_of(0, 0) == 0);
CHECK(heading_error(cellular_heading_of(1, 0), 0) <= 1);
CHECK(heading_error(cellular_heading_of(0, 1), 16'384) <= 1);
CHECK(heading_error(cellular_heading_of(-1, 0), 32'768) <= 1);
CHECK(heading_error(cellular_heading_of(0, -1), 49'152) <= 1);
CHECK(heading_error(cellular_heading_of(1'000, 1'000), 8'192) <= 1);
for (std::uint32_t h = 0; h < cellular_heading_turn; h += 7) {
const auto heading = static_cast<std::uint16_t>(h);
CHECK(
heading_error(cellular_heading_of(cellular_cos_q14(heading), cellular_sin_q14(heading)),
heading) <= 3);
}
}
void acceleration_reaches_steady_speed() {
CellularMotionState state{};
auto position = middle;
std::int32_t previous{};
for (int tick = 0; tick < 120; ++tick) {
const auto next = step(position, state, {{1'000, 0}, false}, founder());
CHECK(next.thrust == CellularThrustStatus::applied && next.cost.value == 1'000);
CHECK(next.state.velocity_x_q10 >= previous && next.state.velocity_y_q10 == 0);
previous = next.state.velocity_x_q10;
position = next.position;
state = next.state;
}
// Thrust then drag settle near 190 um/s for the v0 founder.
CHECK(state.velocity_x_q10 > 189 * um_per_s && state.velocity_x_q10 < 191 * um_per_s);
CHECK(position.x_um > middle.x_um + 1'000);
}
CellularMotionState moving_east(std::int32_t speed_um_s) {
return {.velocity_x_q10 = speed_um_s * um_per_s};
}
void coasting_stops_exactly() {
auto state = moving_east(200);
auto position = middle;
int ticks{};
while (state.velocity_x_q10 != 0) {
const auto next = step(position, state, {}, founder());
CHECK(next.thrust == CellularThrustStatus::idle && next.cost.value == 0);
CHECK(next.state.velocity_x_q10 < state.velocity_x_q10 && next.state.velocity_x_q10 >= 0);
position = next.position;
state = next.state;
CHECK(++ticks < 400);
}
// About 100 um of coasting from 200 um/s with a 0.5 s time constant.
CHECK(position.x_um > middle.x_um + 80 && position.x_um < middle.x_um + 110);
}
void braking_stops_sooner_without_reversing() {
auto state = moving_east(200);
int ticks{};
while (state.velocity_x_q10 != 0) {
const auto next = step(middle, state, {{}, true}, founder());
CHECK(next.state.velocity_x_q10 >= 0 && next.thrust == CellularThrustStatus::applied);
state = next.state;
CHECK(++ticks < 20);
}
const auto stopped = step(middle, state, {{}, true}, founder());
CHECK(stopped.thrust == CellularThrustStatus::idle && stopped.cost.value == 0);
}
void reversing_uses_reverse_thrust() {
auto state = moving_east(150);
auto position = middle;
for (int tick = 0; tick < 30; ++tick) {
const auto next = step(position, state, {{-1'000, 0}, false}, founder());
position = next.position;
state = next.state;
}
CHECK(state.velocity_x_q10 < 0);
// The heading turned toward the command as well.
CHECK(heading_error(state.heading, 32'768) <= 1);
}
void turning_is_rate_limited() {
const auto turned = step(middle, {}, {{0, 1'000}, false}, founder());
CHECK(turned.state.heading == 3'277);
// Perpendicular remains mostly sideways: thrust follows the body axis.
CHECK(turned.state.velocity_x_q10 > turned.state.velocity_y_q10);
}
void flow_drift_is_exact() {
CellularMotionState state{};
auto position = middle;
for (int tick = 0; tick < 20; ++tick) {
const auto next = step(position, state, {}, founder(), {100 * um_per_s, 0});
position = next.position;
state = next.state;
}
CHECK(position == CellularPosition{middle.x_um + 100, middle.y_um});
CHECK(state == CellularMotionState{});
// Against a current faster than the founder's swimming, progress is negative.
state = moving_east(190);
const auto upstream = step(middle, state, {{1'000, 0}, false}, founder(), {-300 * um_per_s, 0});
CHECK(upstream.position.x_um < middle.x_um);
}
void fractional_travel_carries() {
auto handling = founder();
handling.forward_drag_ppm = handling.lateral_drag_ppm = 0;
auto state = moving_east(7);
auto position = middle;
for (int tick = 0; tick < 20; ++tick) {
const auto next = step(position, state, {}, handling);
position = next.position;
state = next.state;
}
CHECK(position.x_um == middle.x_um + 7 && state.remainder_x == 0);
// Slow negative drift carries too.
state = {.velocity_y_q10 = -um_per_s / 2};
position = middle;
for (int tick = 0; tick < 40; ++tick) {
const auto next = step(position, state, {}, handling);
position = next.position;
state = next.state;
}
CHECK(position.y_um == middle.y_um - 1 && state.remainder_y == 0);
}
void unfunded_thrust_coasts() {
const auto state = moving_east(100);
const auto coast = step(middle, state, {}, founder());
const auto broke = step(middle, state, {{1'000, 0}, false}, founder(), {}, {999});
CHECK(broke.thrust == CellularThrustStatus::unfunded && broke.cost.value == 0);
CHECK(broke.state == coast.state && broke.position == coast.position);
const auto half = step(middle, {}, {{500, 0}, false}, founder());
CHECK(half.cost.value == 500 && half.state.velocity_x_q10 > 0);
}
void edges_stop_motion() {
const CellularPosition edge{area.width_um - extent, 100};
const auto blocked = step(edge, moving_east(150), {{1'000, 0}, false}, founder());
CHECK(blocked.position == edge && blocked.state.velocity_x_q10 == 0);
CHECK(blocked.state.remainder_x == 0 && blocked.path_um == 0);
}
void lateral_drag_is_separate() {
auto handling = founder();
handling.forward_drag_ppm = 0;
handling.lateral_drag_ppm = 500'000;
const auto sideways = step(middle, {.velocity_y_q10 = 100 * um_per_s}, {}, handling);
CHECK(std::abs(sideways.state.velocity_y_q10 - 50 * um_per_s) <= 2);
const auto forward = step(middle, moving_east(100), {}, handling);
CHECK(std::abs(forward.state.velocity_x_q10 - 100 * um_per_s) <= 2);
}
void invalid_inputs() {
CHECK(!step_cellular_kinematics({0, 10}, {}, 1, {}, {}, founder(), {}, plenty));
CHECK(
!step_cellular_kinematics(area, {area.width_um, 0}, extent, {}, {}, founder(), {}, plenty));
CHECK(!step_cellular_kinematics(area, middle, extent, {}, {{1'000, 1'000}, false}, founder(),
{}, plenty));
CHECK(!step_cellular_kinematics(area, middle, extent,
{.remainder_x = std::int64_t{1'024} * 1'000'000}, {}, founder(),
{}, plenty));
auto bad = founder();
bad.forward_drag_ppm = 1'000'000;
CHECK(!step_cellular_kinematics(area, middle, extent, {}, {}, bad, {}, plenty));
CHECK(!step_cellular_kinematics(area, middle, extent, {}, {}, founder(),
{cellular_velocity_limit_q10 + 1, 0}, plenty));
}
// Golden trajectory: any change to this value changes shared server/client motion.
void golden_trajectory() {
CellularMotionState state{};
auto position = middle;
std::uint64_t digest = 1'469'598'103'934'665'603ULL;
const auto mix = [&digest](std::uint64_t value) {
digest = (digest ^ value) * 1'099'511'628'211ULL;
};
for (int tick = 0; tick < 200; ++tick) {
const CellularIntent intent{static_cast<std::int16_t>((tick % 50) * 20 - 500),
static_cast<std::int16_t>(tick < 100 ? 600 : -600)};
const CellularFlowSample flow{(tick % 7) * 9'000 - 20'000, 15'000};
const auto next = step(position, state, {intent, tick % 37 == 0}, founder(), flow);
position = next.position;
state = next.state;
mix(position.x_um);
mix(position.y_um);
mix(static_cast<std::uint32_t>(state.velocity_x_q10));
mix(static_cast<std::uint32_t>(state.velocity_y_q10));
mix(state.heading);
}
std::printf("golden trajectory digest %llu\n", static_cast<unsigned long long>(digest));
CHECK(digest == 8'485'405'051'858'728'694ULL);
}
} // namespace
int main() {
try {
trigonometry();
headings();
acceleration_reaches_steady_speed();
coasting_stops_exactly();
braking_stops_sooner_without_reversing();
reversing_uses_reverse_thrust();
turning_is_rate_limited();
flow_drift_is_exact();
fractional_travel_carries();
unfunded_thrust_coasts();
edges_stop_motion();
lateral_drag_is_separate();
invalid_inputs();
golden_trajectory();
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;
}
std::puts("cellular kinematics contracts passed");
return 0;
}