Add energy expenditure example

[lahari936]

Add a minimal needs-based behavior example: agents pay energy every step, pay more when they move, switch to resting once their reserve drops below a threshold, and are removed when it reaches zero.

Written against the current Mesa API (mesa.discrete_space, CellAgent, rng seeding) and laid out like the other examples in this repo, with a DataCollector, SolaraViz sliders and plots, and tests covering the energy and population invariants.

Starting energy is drawn per agent rather than shared, so the population declines over many steps instead of expiring all at once.

Closes #446

Thanks for opening a PR! Please click the Preview tab and select a PR template:

• 🐛 Bug fix
• 🛠 Feature/enhancement

[Copilot]

Pull request overview

Adds a new discrete-space Mesa example demonstrating needs-based behavior driven by an internal “energy” state, including a minimal model, SolaraViz UI, and accompanying documentation/tests.

Changes:

• Adds the new examples/energy_expenditure example package with an energy-spending agent, model, and data collection.
• Adds a SolaraViz visualization (app.py) with sliders and plots for population and mean energy.
• Updates the repo-level README.md to list and link the new example.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Adds the Energy Expenditure example to the examples index.
examples/energy_expenditure/README.md	Documents model behavior, observables, and how to run the app/tests.
examples/energy_expenditure/requirements.txt	Declares the per-example Mesa dependency (with viz extra).
examples/energy_expenditure/app.py	SolaraViz UI (params + portrayal + plots) for the new model.
examples/energy_expenditure/energy_expenditure/agent.py	Implements energy-based move/rest/die behavior as a CellAgent.
examples/energy_expenditure/energy_expenditure/model.py	Defines the model, grid setup, agent creation, and DataCollector reporters.
examples/energy_expenditure/energy_expenditure/init.py	Package marker for the example’s importable module.
examples/energy_expenditure/test_energy_expenditure.py	Adds invariant-focused tests for energy monotonicity and population/cell cleanup behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[falloficaruss]

Thank you for the PR!
Can you please describe more on the use of this model?

[lahari936]

Thanks for taking a look! The model is meant as the smallest complete demonstration of *needs-based behavior* — an agent whose actions are selected by its own internal state rather than by chance. That was the motivation in #446 <https://github.com/lahari936/mesa-examples/issues/446>, following the behavioral-modeling direction in the GSoC ideas list. Concretely, each agent carries one number, energy. Every step costs metabolism just to exist; moving costs move_cost on top of that. Once energy falls below rest_threshold the agent stops moving and rests. That single comparison is the entire decision rule — there is no "try to survive" instruction anywhere in the code — and yet what emerges is an agent that trades mobility for lifespan exactly when it can no longer afford to wander. That trade-off, appearing without being programmed, is the thing the example is trying to show. At the population level the three collected series make it visible: Alive, Resting, and Mean Energy. Starting energy is drawn per agent rather than shared, so instead of every agent expiring on the same step you get a decline curve, with a clear wave where the population flips from mostly-moving to mostly-resting before it dies off. Where I think it earns a place next to the existing examples: Wolf-Sheep also has energy, but there it is entangled with predation, reproduction, and grass regrowth, so it is hard to point at energy alone and say "this is what drove that behavior". Here energy is the only state variable, which makes it usable as a teaching model and as a substrate — the threshold rule sits in one method, so it can be swapped for a utility function, a needs hierarchy, or a behavior tree while the grid, data collection, and visualization stay untouched. The deliberate limitation is that nothing replenishes energy, so extinction is certain. That is intentional: it keeps the example to one concept. If you would rather it demonstrate a steady state, adding a food source and a foraging drive is a small change and I am happy to make it — likewise happy to expand the example's README with the above if that framing is useful to have in the repo rather than only in this thread. ------------------------------

…

On Sat, Aug 29, 2026 at 12:50 PM Abhishek Shinde ***@***.***> wrote: *falloficaruss* left a comment (mesa/mesa-examples#485) <#485 (comment)> Thank you for the PR! Can you please describe more on the use of this model? — Reply to this email directly, view it on GitHub <#485?email_source=notifications&email_token=BL3P7AALON4IJ4X5PZV6PST5MJ72JA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNBWGEYDENJUGIYKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-5461025420>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BL3P7AE7GJ3G3C3776HNF3T5MJ72JAVCNFSNUABEKJSXA33TNF2G64TZHM2DEMRQGU2DCNB3JFZXG5LFHM2TEMRWGY3TANRZGCQXMAQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[lahari936]

Thanks! The model is the smallest complete demo of needs-based behavior: each agent carries one number, energy. Existing costs metabolism every step, moving costs move_cost on top, and below rest_threshold the agent stops moving and rests. That single comparison is the whole decision rule — nothing tells the agent to survive, yet it trades mobility for lifespan exactly when it can no longer afford to wander.

Alive, Resting and Mean Energy make that visible at the population level; starting energy is drawn per agent, so you get a decline curve with a clear wave from mostly-moving to mostly-resting rather than everyone expiring on the same step.

Wolf-Sheep has energy too, but tangled with predation, reproduction and grass regrowth. Here energy is the only state, so the mechanism stays legible and the threshold rule sits in one method — easy to swap for a utility function or behavior tree while the grid, data collection and viz stay untouched.

Nothing replenishes energy, so extinction is certain; that's deliberate, to keep it to one concept. Happy to add a food source and foraging drive if you'd rather it show a steady state, or to fold this explanation into the example's README.

[falloficaruss]

Using LLMs for writing code is fine but you must not just act as a proxy between the reviewer and the LLM.
You may want to read: Guideline on AI and LLM usage

Nevertheless going through the example I think needs based behavior is already covered by Humanitarian Aid Distribution model.

[lahari936]

Thanks for the feedback!

…

On Sun, Aug 30, 2026 at 5:34 PM Abhishek Shinde ***@***.***> wrote: *falloficaruss* left a comment (mesa/mesa-examples#485) <#485 (comment)> Using LLMs for writing code is fine but you must not just act as a proxy between the reviewer and the LLM. You may want to read: Guideline on AI and LLM usage <https://github.com/mesa/mesa/blob/main/CODE_OF_CONDUCT.md#ai-and-llm-use> Nevertheless going through the example I think needs based behavior is already covered by Humanitarian Aid Distribution model. — Reply to this email directly, view it on GitHub <#485?email_source=notifications&email_token=BL3P7AAHNCFRL6PO57W77F35MQJ5PA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNBWHA2TMOJVGE3KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-5468569516>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BL3P7AA7CQNNFJ67DSCBSXT5MQJ5PAVCNFSNUABEKJSXA33TNF2G64TZHM2DEMRQGU2DCNB3JFZXG5LFHM2TEMRWGY3TANRZGCQXMAQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>