feat(biology): liquid motion in the shared region tick
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m28s
Foundation / postgres-tools (push) Successful in 25s
Foundation / server-image (push) Successful in 4m3s
Foundation / image (push) Successful in 4m28s

Rules 12 lives carry a liquid input (motion state, handling, brake and the local
flow sample) and step through propose_liquid_cellular_step: maintenance first,
then one kinematic tick funded from what is left, so unfundable thrust coasts with
the current. A format-3 habitat requires liquid input on every life and older
habitats refuse it. Contact feeding sweeps each liquid cell's whole path so a fast
cell cannot pass over food; frozen cells keep their motion; corpse bubbles in a
format-3 habitat count one merged bubble and use the larger deposit limit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-21 16:56:37 -04:00
co-authored by Claude Opus 5.5
parent 40dc2b12ad
commit 190a66ad5e
8 changed files with 319 additions and 9 deletions
+5
View File
@@ -509,6 +509,11 @@ if(BUILD_TESTING)
evo_owned_target(evo-cellular-deposit-motion-tests)
add_test(NAME cellular-deposit-motion-contracts COMMAND evo-cellular-deposit-motion-tests)
set_tests_properties(cellular-deposit-motion-contracts PROPERTIES TIMEOUT 120)
add_executable(evo-cellular-liquid-step-tests tests/cellular_liquid_step_tests.cpp)
target_link_libraries(evo-cellular-liquid-step-tests PRIVATE evo::biology)
evo_owned_target(evo-cellular-liquid-step-tests)
add_test(NAME cellular-liquid-step-contracts COMMAND evo-cellular-liquid-step-tests)
set_tests_properties(cellular-liquid-step-contracts PROPERTIES TIMEOUT 60)
add_executable(evo-cellular-uptake-tests tests/cellular_uptake_tests.cpp)
target_link_libraries(evo-cellular-uptake-tests PRIVATE evo::biology)
evo_owned_target(evo-cellular-uptake-tests)
+6
View File
@@ -84,6 +84,12 @@ struct CellularPatchPerception {
// Whether a cell's square footprint touches a patch (format 1 square) or a deposit's disc.
[[nodiscard]] bool cellular_patch_contact(CellularPosition position, std::uint32_t extent_um,
const CellularPatch& patch) noexcept;
// Whether a footprint moving in a straight line from `from` to `to` touches the deposit at any
// point, sampled no further apart than half the smaller of the deposit's radius and the
// footprint, so a fast cell cannot pass over food.
[[nodiscard]] bool cellular_path_contact(CellularPosition from, CellularPosition to,
std::uint32_t extent_um,
const CellularPatch& patch) noexcept;
enum class CellularHabitatError : std::uint8_t {
invalid_config,
invalid_patch,
@@ -39,6 +39,9 @@ struct CellularLifeStepInput {
MetabolicBudget budget;
std::uint32_t membrane_um{}; // Genome membrane thickness; contests engulfment (rules 3).
std::uint64_t source{}; // Provenance for a detritus patch this life creates (rules 3).
// Rules 12: liquid motion, required exactly when the habitat is format 3. The movement
// intent becomes the propulsion command.
std::optional<CellularLiquidInput> liquid{};
auto operator<=>(const CellularLifeStepInput&) const = default;
};
enum class CellularEngulfStatus : std::uint8_t {
+20
View File
@@ -1,6 +1,7 @@
#pragma once
#include "evo/biology/cellular_habitat.hpp"
#include "evo/biology/cellular_kinematics.hpp"
#include <cstdint>
#include <optional>
@@ -48,12 +49,31 @@ struct CellularStepCandidate {
CellularMovementStatus movement_status{CellularMovementStatus::not_requested};
CellularIntakeStatus intake_status{CellularIntakeStatus::not_requested};
std::optional<CellularPatchUptakeProposal> intake;
// Rules 12 (liquid motion): the motion state after the tick and the path travelled.
CellularMotionState motion{};
std::uint64_t path_um{};
auto operator<=>(const CellularStepCandidate&) const = default;
};
// Rules 12: liquid-relative motion inputs for one life (Cellular_Region_Movement_Plan.md).
struct CellularLiquidInput {
CellularMotionState motion;
CellularHandling handling;
CellularFlowSample flow; // Sampled at the footprint centre by the caller.
bool brake{};
auto operator<=>(const CellularLiquidInput&) const = default;
};
[[nodiscard]] std::expected<CellularStepCandidate, CellularStepError>
propose_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosition position,
std::uint32_t extent_um, CellularStepIntent intent,
accounting::Inventory reserve, accounting::Inventory heat,
const MetabolicBudget& budget, const CellularHabitat& habitat) noexcept;
// Rules 12: maintenance first, then one kinematic tick funded from what is left; thrust it
// cannot fund is not applied and the cell coasts with the flow. No targeted intake: liquid
// regions feed by contact in the region step.
[[nodiscard]] std::expected<CellularStepCandidate, CellularStepError>
propose_liquid_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosition position,
std::uint32_t extent_um, CellularIntent movement,
const CellularLiquidInput& liquid, accounting::Inventory reserve,
accounting::Inventory heat, const MetabolicBudget& budget) noexcept;
} // namespace evo::biology
+22
View File
@@ -450,6 +450,28 @@ scatter_deposits(CellularHabitatConfig base, std::span<const CellularPatch> pool
return base;
}
bool cellular_path_contact(CellularPosition from, CellularPosition to, std::uint32_t extent_um,
const CellularPatch& patch) noexcept {
if (from == to)
return cellular_patch_contact(to, extent_um, patch);
const auto dx = static_cast<std::int64_t>(to.x_um) - static_cast<std::int64_t>(from.x_um);
const auto dy = static_cast<std::int64_t>(to.y_um) - static_cast<std::int64_t>(from.y_um);
const auto reach = std::max<std::int64_t>(
1, std::min<std::int64_t>(patch.radius_um == 0 ? cellular_patch_pitch_um : patch.radius_um,
extent_um) /
2);
const auto span = std::max(dx < 0 ? -dx : dx, dy < 0 ? -dy : dy);
const auto steps = std::clamp<std::int64_t>((span + reach - 1) / reach, 1, 256);
for (std::int64_t step = 0; step <= steps; ++step) {
const CellularPosition at{
static_cast<std::uint64_t>(static_cast<std::int64_t>(from.x_um) + dx * step / steps),
static_cast<std::uint64_t>(static_cast<std::int64_t>(from.y_um) + dy * step / steps)};
if (cellular_patch_contact(at, extent_um, patch))
return true;
}
return false;
}
bool cellular_patch_contact(CellularPosition position, std::uint32_t extent_um,
const CellularPatch& patch) noexcept {
if (patch.kind == CellularDepositKind::patch)
+27 -9
View File
@@ -66,11 +66,17 @@ propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
if (lives.size() > max_cellular_tick_lives)
return std::unexpected{CellularRegionStepError::too_many_lives};
const bool liquid = habitat.config().format == cellular_habitat_liquid_format;
const auto deposit_limit = liquid ? max_cellular_liquid_deposits : max_cellular_patches;
std::vector<const CellularLifeStepInput*> ordered;
ordered.reserve(lives.size());
for (const auto& life : lives) {
if (life.life_id == 0)
return std::unexpected{CellularRegionStepError::invalid_life_id};
// Rules 12: liquid motion in a format-3 habitat, for every life, and nowhere else.
if (life.liquid.has_value() != liquid ||
(liquid && (life.intent.intake_target || !rules.contact_feeding)))
return std::unexpected{CellularRegionStepError::invalid_intent};
if (life.intent.frozen &&
(life.intent.movement != CellularIntent{} || life.intent.intake_target ||
life.intent.engulf || life.intent.bud))
@@ -111,6 +117,8 @@ propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
frozen.position = life->position;
frozen.reserve_after = life->reserve;
frozen.heat_after = life->heat;
if (life->liquid)
frozen.motion = life->liquid->motion; // Anchored while frozen.
candidate.lives.push_back({life->life_id, frozen});
survivors.push_back(life);
continue;
@@ -121,8 +129,12 @@ propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
intent.intake_target.reset();
intent.engulf = false;
const auto step =
propose_cellular_step(begin_tick, area, life->position, life->extent_um, intent,
life->reserve, life->heat, life->budget, habitat);
life->liquid
? propose_liquid_cellular_step(begin_tick, area, life->position, life->extent_um,
intent.movement, *life->liquid, life->reserve,
life->heat, life->budget)
: propose_cellular_step(begin_tick, area, life->position, life->extent_um, intent,
life->reserve, life->heat, life->budget, habitat);
if (!step && step.error() == CellularStepError::insufficient_maintenance) {
CellularCorpseCandidate corpse{life->life_id, life->position, life->reserve};
for (std::size_t channel = 0; channel < corpse.inventory.matter.size(); ++channel) {
@@ -187,7 +199,11 @@ propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
std::optional<std::size_t> first;
for (std::size_t index = 0; index < patch_stock.size(); ++index) {
const auto& deposit = habitat.patches()[index];
if (!cellular_patch_contact(result.position, life->extent_um, deposit))
// Liquid motion sweeps its whole path, so a fast cell cannot skip food.
if (life->liquid
? !cellular_path_contact(life->position, result.position, life->extent_um,
deposit)
: !cellular_patch_contact(result.position, life->extent_um, deposit))
continue;
bool took = false;
for (std::size_t channel = 0; channel < limit.size(); ++channel) {
@@ -337,8 +353,7 @@ propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
continue;
accounting::Inventory single{};
channel_of(single, channel) = amount;
if (habitat.patches().size() + candidate.new_patches.size() >=
max_cellular_patches) {
if (habitat.patches().size() + candidate.new_patches.size() >= deposit_limit) {
overflow.push_back({deposit.life_id, deposit.source, deposit.position,
single, deposit.extent_um});
continue;
@@ -356,9 +371,12 @@ propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
address.x_um = address.x_um + 1 < area.width_um ? address.x_um + 1 : 0;
const auto at = std::ranges::lower_bound(candidate.new_patches, address, {},
&CellularPatch::address);
candidate.new_patches.insert(at, CellularPatch{address, deposit.source, single,
0, cellular_mote_radius_um,
CellularDepositKind::mote});
CellularPatch bubble{
address, deposit.source, single,
0, cellular_mote_radius_um, CellularDepositKind::mote};
if (liquid)
bubble.merged = 1;
candidate.new_patches.insert(at, bubble);
}
}
deposits = std::move(overflow); // A full habitat: the nearest deposit takes it.
@@ -377,7 +395,7 @@ propose_cellular_region_step(std::uint64_t begin_tick, CellularArea area,
return std::unexpected{CellularRegionStepError::overflow};
continue;
}
if (habitat.patches().size() + candidate.new_patches.size() < max_cellular_patches) {
if (habitat.patches().size() + candidate.new_patches.size() < deposit_limit) {
candidate.new_patches.insert(made, {address, deposit.source, deposit.inventory});
continue;
}
+57
View File
@@ -96,4 +96,61 @@ propose_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosit
candidate.intake = *intake;
return candidate;
}
std::expected<CellularStepCandidate, CellularStepError>
propose_liquid_cellular_step(std::uint64_t begin_tick, CellularArea area, CellularPosition position,
std::uint32_t extent_um, CellularIntent movement,
const CellularLiquidInput& liquid, accounting::Inventory reserve,
accounting::Inventory heat, const MetabolicBudget& budget) noexcept {
if (begin_tick == std::numeric_limits<std::uint64_t>::max())
return std::unexpected{CellularStepError::invalid_tick};
if (budget.rate_microseconds != rate_period_microseconds)
return std::unexpected{CellularStepError::unsupported_rate_period};
const auto maintenance = accounting::per_tick(
budget.maintenance.value, cellular_motion_tick_microseconds, accounting::Rounding::up);
if (!maintenance)
return std::unexpected{CellularStepError::overflow};
if (reserve.energy.value < *maintenance)
return std::unexpected{CellularStepError::insufficient_maintenance};
if (!credit_heat(heat, *maintenance))
return std::unexpected{CellularStepError::overflow};
reserve.energy.value -= *maintenance;
const auto motion =
step_cellular_kinematics(area, position, extent_um, liquid.motion, {movement, liquid.brake},
liquid.handling, liquid.flow, reserve.energy);
if (!motion)
return std::unexpected{CellularStepError::motion};
if (!credit_heat(heat, motion->cost.value))
return std::unexpected{CellularStepError::overflow};
reserve.energy.value -= motion->cost.value;
CellularStepCandidate candidate{};
candidate.begin_tick = begin_tick;
candidate.end_tick = begin_tick + 1;
candidate.position = motion->position;
candidate.reserve_after = reserve;
candidate.heat_after = heat;
candidate.maintenance_cost = {*maintenance};
candidate.movement_cost = motion->cost;
candidate.motion = motion->state;
candidate.path_um = motion->path_um;
switch (motion->thrust) {
case CellularThrustStatus::idle:
candidate.movement_status = CellularMovementStatus::not_requested;
break;
case CellularThrustStatus::unfunded:
candidate.movement_status = CellularMovementStatus::insufficient_reserve;
break;
case CellularThrustStatus::applied:
// Blocked only when an edge stopped it; a sub-micrometre start is still moving.
candidate.movement_status = motion->position == position &&
motion->state.velocity_x_q10 == 0 &&
motion->state.velocity_y_q10 == 0
? CellularMovementStatus::blocked
: CellularMovementStatus::moved;
break;
}
return candidate;
}
} // namespace evo::biology
+179
View File
@@ -0,0 +1,179 @@
#include "evo/biology/cellular_region_step.hpp"
#include <array>
#include <cstdio>
#include <memory>
#include <source_location>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
namespace {
using namespace evo::biology;
using evo::accounting::Inventory;
void check(bool value, std::source_location at = std::source_location::current()) {
if (!value)
throw std::runtime_error("cellular liquid step line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
constexpr CellularArea area{60'000, 60'000};
constexpr std::int32_t um_per_s = 1'024;
constexpr CellularRegionRules rules{.engulf_and_detritus = true, .contact_feeding = true};
MetabolicBudget budget() {
MetabolicBudget value{};
value.rate_microseconds = 1'000'000;
value.maintenance = {20}; // One picojoule per tick.
value.intake_limit = {{1'000'000}, {{{1'000'000}, {1'000'000}, {1'000'000}, {1'000'000}}}};
value.phenotype.total_mass = 1'000;
return value;
}
CellularHandling handling() {
return {.thrust_q10 = 20'480,
.reverse_thrust_q10 = 20'480,
.forward_drag_ppm = 95'163,
.lateral_drag_ppm = 95'163,
.turn = 3'277,
.thrust_cost = {10},
.reverse_cost = {10}};
}
CellularPatch bubble(std::uint32_t id, std::uint32_t x, std::uint32_t y) {
CellularPatch patch{
{x, y}, 1, {{50}, {}}, id, cellular_mote_radius_um, CellularDepositKind::mote};
patch.merged = 1;
return patch;
}
std::unique_ptr<CellularHabitat> liquid_habitat(std::vector<CellularPatch> patches = {}) {
std::uint32_t next = 1;
for (const auto& patch : patches)
next = std::max(next, patch.id + 1);
auto made = CellularHabitat::create(
{100, 1, 9, 60'000, 60'000, std::move(patches), cellular_habitat_liquid_format, next});
check(made.has_value());
return std::move(*made);
}
CellularLifeStepInput life(std::uint64_t id, CellularPosition position, CellularIntent movement,
Inventory reserve = {{1'000}, {}},
CellularLiquidInput liquid = {{}, handling(), {}, false}) {
CellularLifeStepInput input{};
input.life_id = id;
input.position = position;
input.extent_um = 20;
input.intent.movement = movement;
input.body = {{0}, {{{5}, {5}, {5}, {5}}}};
input.reserve = reserve;
input.budget = budget();
input.membrane_um = 1;
input.source = 7;
input.liquid = liquid;
return input;
}
void propulsion_moves_and_pays() {
const auto map = liquid_habitat();
const std::array lives{life(1, {30'000, 30'000}, {1'000, 0})};
const auto tick = propose_cellular_region_step(4, area, lives, *map, rules);
CHECK(tick && tick->lives.size() == 1);
const auto& step = tick->lives[0].candidate;
CHECK(step.movement_status == CellularMovementStatus::moved);
CHECK(step.motion.velocity_x_q10 > 0 && step.position.x_um == 30'000);
// First tick: 20 um/s * 50 ms leaves sub-micrometre carry; maintenance 1 + thrust 10.
CHECK(step.motion.remainder_x > 0);
CHECK(step.maintenance_cost.value == 1 && step.movement_cost.value == 10);
CHECK(step.reserve_after.energy.value == 989 && step.heat_after.energy.value == 11);
}
void unfunded_thrust_coasts_with_the_flow() {
const auto map = liquid_habitat();
// Enough for maintenance, not for thrust; a 100 um/s current still carries the cell.
const auto broke = life(1, {30'000, 30'000}, {1'000, 0}, {{5}, {}},
{{}, handling(), {100 * um_per_s, 0}, false});
const std::array lives{broke};
const auto tick = propose_cellular_region_step(4, area, lives, *map, rules);
CHECK(tick && tick->lives.size() == 1);
const auto& step = tick->lives[0].candidate;
CHECK(step.movement_status == CellularMovementStatus::insufficient_reserve);
CHECK(step.movement_cost.value == 0 && step.reserve_after.energy.value == 4);
CHECK(step.position.x_um == 30'005);
}
void fast_cells_feed_along_their_path() {
// A bubble lies between where a very fast cell starts and where it ends this tick.
const auto map = liquid_habitat({bubble(1, 30'040, 30'010)});
const auto moving =
life(1, {30'000, 30'000}, {}, {{1'000}, {}},
{{.velocity_x_q10 = 2'000 * um_per_s}, handling(), {1'000 * um_per_s, 0}, false});
const std::array lives{moving};
const auto tick = propose_cellular_region_step(4, area, lives, *map, rules);
CHECK(tick && tick->lives.size() == 1);
const auto& step = tick->lives[0].candidate;
// It ends well past the bubble's reach, yet it fed on the way.
CHECK(step.position.x_um > 30'040 + cellular_mote_radius_um + 20);
CHECK(step.intake_status == CellularIntakeStatus::acquired);
CHECK(tick->patches.size() == 1 && tick->patches[0].stock == Inventory{});
}
void starved_cells_leave_merged_bubbles() {
const auto map = liquid_habitat();
auto starving = life(1, {30'000, 30'000}, {}, {{0}, {}});
starving.body = {{0}, {{{3}, {0}, {2}, {0}}}};
const std::array lives{starving};
const auto tick = propose_cellular_region_step(4, area, lives, *map, rules);
CHECK(tick && tick->lives.empty() && tick->starved.size() == 1);
CHECK(tick->new_patches.size() == 2);
for (const auto& patch : tick->new_patches)
CHECK(patch.kind == CellularDepositKind::mote && patch.merged == 1);
}
void frozen_cells_keep_their_motion() {
const auto map = liquid_habitat();
const CellularMotionState held{.velocity_x_q10 = 50 * um_per_s, .heading = 99};
auto frozen = life(1, {30'000, 30'000}, {}, {{1'000}, {}},
{held, handling(), {200 * um_per_s, 0}, false});
frozen.intent.frozen = true;
const std::array lives{frozen};
const auto tick = propose_cellular_region_step(4, area, lives, *map, rules);
CHECK(tick && tick->lives.size() == 1);
const auto& step = tick->lives[0].candidate;
CHECK(step.position == CellularPosition{30'000, 30'000});
CHECK(step.motion == held && step.reserve_after.energy.value == 1'000);
}
void liquid_and_format_must_match() {
const std::array liquid_life{life(1, {1'000, 1'000}, {})};
auto old = CellularHabitat::create(
{100, 1, 9, 60'000, 60'000, {}, cellular_habitat_deposit_format, 1});
CHECK(old);
const auto mismatched = propose_cellular_region_step(4, area, liquid_life, **old, rules);
CHECK(!mismatched && mismatched.error() == CellularRegionStepError::invalid_intent);
auto plain = life(1, {1'000, 1'000}, {});
plain.liquid.reset();
const std::array plain_life{plain};
const auto missing =
propose_cellular_region_step(4, area, plain_life, *liquid_habitat(), rules);
CHECK(!missing && missing.error() == CellularRegionStepError::invalid_intent);
}
} // namespace
int main() {
try {
propulsion_moves_and_pays();
unfunded_thrust_coasts_with_the_flow();
fast_cells_feed_along_their_path();
starved_cells_leave_merged_bubbles();
frozen_cells_keep_their_motion();
liquid_and_format_must_match();
} catch (const std::exception& error) {
std::fprintf(stderr, "%s\n", error.what());
return 1;
}
std::puts("cellular liquid step contracts passed");
return 0;
}