ARTIFICIAL WORLD #005 — Finite Natural Resource

INITIAL_RESOURCE = 20

AGENT_1_INITIAL_ENERGY = 3
AGENT_2_INITIAL_ENERGY = 3

FOOD_ENERGY = 3
ENERGY_COST_PER_STEP = 1

ACCESS_PROBABILITY = 0.35
CONSUMPTION_PER_SUCCESS = 1

RANDOM_SEED = 7
MAXIMUM_TIME = 200

parameters = {
    "Initial resource": INITIAL_RESOURCE,
    "Agent 1 initial energy": AGENT_1_INITIAL_ENERGY,
    "Agent 2 initial energy": AGENT_2_INITIAL_ENERGY,
    "Food energy": FOOD_ENERGY,
    "Energy cost per step": ENERGY_COST_PER_STEP,
    "Access probability": ACCESS_PROBABILITY,
    "Consumption per success": CONSUMPTION_PER_SUCCESS,
    "Random seed": RANDOM_SEED,
    "Maximum time": MAXIMUM_TIME,
}

class Agent:
    def __init__(
        self,
        name,
        initial_energy,
        energy_cost_per_step
    ):
        self.name = name
        self.energy = initial_energy
        self.energy_cost_per_step = energy_cost_per_step
        self.alive = True
        self.memory = []

    def observe(self, world):
        """
        The agent observes its own energy
        and the remaining natural resource.
        """
        return {
            "energy": self.energy,
            "resource_remaining": world.resource_remaining
        }

    def choose_action(self, observation):
        """
        The agent seeks food whenever some natural resource remains.
        """
        if observation["resource_remaining"] > 0:
            return "seek_food"

        return "wait"

    def act(self, action, world):
        """
        Carry out the chosen action.
        """
        if action == "seek_food":
            self.seek_food(world)

        elif action == "wait":
            self.wait()

    def seek_food(self, world):
        """
        The agent tries to access the shared natural resource.

        If access succeeds:
        - some natural resource is consumed;
        - the agent gains energy.
        """
        food_obtained = world.access_natural_resource()

        if food_obtained:
            self.energy += world.food_energy

            result = (
                f"{self.name} accessed the natural resource, "
                f"consumed {world.consumption_per_success} unit(s), "
                f"and gained {world.food_energy} energy."
            )

        else:
            if world.resource_remaining <= 0:
                result = (
                    f"{self.name} sought food, "
                    "but the natural resource had dried up."
                )
            else:
                result = (
                    f"{self.name} sought food "
                    "but failed to access the resource."
                )

        self.memory.append(result)

    def wait(self):
        """
        The agent waits after the resource has dried up.
        """
        self.memory.append(
            f"{self.name} waited because no natural resource remained."
        )

    def live_one_step(self):
        """
        Existing for one time step consumes energy.
        """
        self.energy -= self.energy_cost_per_step

        if self.energy <= 0:
            self.energy = 0
            self.alive = False

class World:
    def __init__(
        self,
        initial_resource,
        food_energy,
        access_probability,
        consumption_per_success,
        random_seed
    ):
        self.initial_resource = initial_resource
        self.resource_remaining = initial_resource

        self.food_energy = food_energy
        self.access_probability = access_probability
        self.consumption_per_success = consumption_per_success

        self.random_seed = random_seed
        self.time = 0

        # A private random-number generator makes
        # the history reproducible.
        self.rng = random.Random(random_seed)

    def access_natural_resource(self):
        """
        An agent attempts to access the shared natural resource.

        Successful access requires:
        1. enough resource remaining;
        2. a random draw below the access probability.

        A successful access reduces the resource stock.
        """
        if self.resource_remaining < self.consumption_per_success:
            return False

        random_draw = self.rng.random()

        if random_draw < self.access_probability:
            self.resource_remaining -= self.consumption_per_success
            return True

        return False

    def advance_time(self):
        self.time += 1

def print_initial_state(world, agents):
    """
    Display the state of the universe at time 0.
    """
    print("INITIAL CONDITION")
    print(f"Time: {world.time}")
    print(f"Resource remaining: {world.resource_remaining}")

    for agent in agents:
        print(f"{agent.name} energy: {agent.energy}")
        print(f"{agent.name} alive: {agent.alive}")
        print(f"{agent.name} memory: {agent.memory}")

    print("-" * 40)


def print_time_step(world, agents, step_records):
    """
    Display the state reached after one completed time step.
    """
    print(f"Time: {world.time}")
    print(f"Resource remaining: {world.resource_remaining}")

    for agent in agents:
        print(f"{agent.name} energy: {agent.energy}")
        print(f"{agent.name} alive: {agent.alive}")
        print(f"{agent.name} action: {step_records[agent.name]}")

    print("-" * 40)

def record_history(history, world, agents):
    """
    Record the complete state of the universe
    at the current time.
    """
    history["time"].append(world.time)
    history["resource"].append(world.resource_remaining)

    for agent in agents:
        history["energy"][agent.name].append(agent.energy)
        history["alive"][agent.name].append(agent.alive)

def find_resource_exhaustion_time(history):
    """
    Return the first time at which the natural resource
    reaches zero.

    Return None if it never reaches zero.
    """
    for time, resource in zip(
        history["time"],
        history["resource"]
    ):
        if resource <= 0:
            return time

    return None


def find_death_time(history, agent_name):
    """
    Return the first time at which the agent is no longer alive.
    """
    for time, alive in zip(
        history["time"],
        history["alive"][agent_name]
    ):
        if not alive:
            return time

    return None

def save_history_to_csv(
    history,
    agents,
    random_seed,
    output_directory="csv"
):
    """
    Save the complete simulation history as a CSV file.

    Each row represents the state of the universe
    at one recorded time.
    """

    output_directory = Path(output_directory)

    # Create the directory if it does not already exist.
    output_directory.mkdir(
        parents=True,
        exist_ok=True
    )

    output_filename = (
        f"AW005_history_seed_{random_seed}.csv"
    )

    output_path = (
        output_directory
        / output_filename
    )

    fieldnames = [
        "time",
        "resource_remaining"
    ]

    for agent in agents:
        agent_key = (
            agent.name
                       .lower()
            .replace(" ", "_")
        )

        fieldnames.extend([
            f"{agent_key}_energy",
            f"{agent_key}_alive"
        ])

    with output_path.open(
        mode="w",
        newline="",
        encoding="utf-8"
    ) as csv_file:

        writer = csv.DictWriter(
            csv_file,
            fieldnames=fieldnames
        )

        writer.writeheader()

        number_of_records = len(
            history["time"]
        )

        for index in range(number_of_records):

            row = {
                "time":
                    history["time"][index],

                "resource_remaining":
                    history["resource"][index]
            }

            for agent in agents:
                agent_key = (
                    agent.name
                    .lower()
                    .replace(" ", "_")
                )

                row[
                    f"{agent_key}_energy"
                ] = history["energy"][
                    agent.name
                ][index]

                row[
                    f"{agent_key}_alive"
                ] = history["alive"][
                    agent.name
                ][index]

            writer.writerow(row)

    print(
        f"History saved as: "
        f"{output_path}"
    )

    return output_path

def plot_history(history, parameters, agents):
    """
    Visualize:
    1. the energy of both agents;
    2. the remaining natural resource;
    3. the parameter values used in the simulation.
    """
    exhaustion_time = find_resource_exhaustion_time(history)

    figure, axes = plt.subplots(
        nrows=2,
        ncols=1,
        figsize=(12, 8),
        sharex=True
    )

    energy_axis = axes[0]
    resource_axis = axes[1]

    # --------------------------------------------------
    # Upper graph: agent energies
    # --------------------------------------------------

    line_styles = ["-", "--", ":", "-."]

    for index, agent in enumerate(agents):
        energy_axis.plot(
            history["time"],
            history["energy"][agent.name],
            drawstyle="steps-post",
            linestyle=line_styles[index % len(line_styles)],
            linewidth=2,
            label=f"{agent.name} energy"
        )

        death_time = find_death_time(history, agent.name)

        if death_time is not None:
            energy_axis.axvline(
                death_time,
                linestyle=":",
                linewidth=1
            )

            energy_axis.text(
                death_time,
                0,
                f"  {agent.name} terminated at t={death_time}",
                rotation=90,
                verticalalignment="bottom"
            )

    if exhaustion_time is not None:
        energy_axis.axvline(
            exhaustion_time,
            linestyle="--",
            linewidth=1.5,
            label=f"Resource exhausted at t={exhaustion_time}"
        )

    energy_axis.set_title(
        "History of Two Agents in a Finite Natural World"
    )

    energy_axis.set_ylabel("Energy")
    energy_axis.grid(True, alpha=0.3)
    energy_axis.legend()


    # --------------------------------------------------
    # Lower graph: natural-resource stock
    # --------------------------------------------------

    resource_axis.plot(
        history["time"],
        history["resource"],
        drawstyle="steps-post",
        linewidth=2,
        label="Natural resource remaining"
    )

    if exhaustion_time is not None:
        resource_axis.axvline(
            exhaustion_time,
            linestyle="--",
            linewidth=1.5
        )

        resource_axis.text(
            exhaustion_time,
            0,
            f"  Resource exhausted at t={exhaustion_time}",
            rotation=90,
            verticalalignment="bottom"
        )

    resource_axis.set_xlabel("Time")
    resource_axis.set_ylabel("Resource remaining")
    resource_axis.grid(True, alpha=0.3)
    resource_axis.legend()


    # --------------------------------------------------
    # Parameter list
    # --------------------------------------------------

    parameter_lines = ["PARAMETERS"]

    for parameter_name, parameter_value in parameters.items():
        parameter_lines.append(
            f"{parameter_name}: {parameter_value}"
        )

    parameter_text = "\n".join(parameter_lines)

    figure.text(
        0.77,
        0.50,
        parameter_text,
        verticalalignment="center",
        family="monospace",
        fontsize=10,
        bbox={
            "boxstyle": "round",
            "alpha": 0.1
        }
    )

    figure.tight_layout(rect=[0.0, 0.0, 0.74, 1.0])

    output_directory = Path("image")
    output_directory.mkdir(
        parents=True,
        exist_ok=True
    )

    output_filename = (output_directory/ "AW005_Fig02_History.png")
    
    figure.savefig(
        output_filename,
        dpi=300,
        bbox_inches="tight",
    )
    
    print(f"Graph saved as: {output_filename}")

    plt.show()

world = World(
    initial_resource=INITIAL_RESOURCE,
    food_energy=FOOD_ENERGY,
    access_probability=ACCESS_PROBABILITY,
    consumption_per_success=CONSUMPTION_PER_SUCCESS,
    random_seed=RANDOM_SEED,
)

agent_1 = Agent(
    name="Agent 1",
    initial_energy=AGENT_1_INITIAL_ENERGY,
    energy_cost_per_step=ENERGY_COST_PER_STEP,
)

agent_2 = Agent(
    name="Agent 2",
    initial_energy=AGENT_2_INITIAL_ENERGY,
    energy_cost_per_step=ENERGY_COST_PER_STEP,
)

agents = [agent_1, agent_2]

history = {
    "time": [],
    "resource": [],
    "energy": {
        agent.name: []
        for agent in agents
    },
    "alive": {
        agent.name: []
        for agent in agents
    },
}