feat: add StuckAgentsWriter for population analysis

[gac55]

StuckAgentsWriter - Track and Analyze Stuck Agents

Adds a new writer to track and report stuck agents in the simulation, including their final positions and states. Can help debug, understand simulation calibration problems, or even unintended scenario testing problems.

This PR adds a new analysis tool to help diagnose simulation issues by tracking agents that get stuck during a MATSim run.

In response to #3008

What is this?
StuckAgentsWriter is an event handler that captures detailed information about stuck agents and outputs it to a structured XML file. This makes it easier to:

• Identify problematic agents in your simulation
• Understand when and where agents are getting stuck
• Debug network or scenario issues that cause agents to fail. Currently, it doesn't tell you the problem, but it can help you find the problem

Features

• Comprehensive tracking: Captures agent ID, time, link ID and mode
• Flexible usage: Can be run as a standalone CLI command or integrated into custom controller
• Structured output: Generates XML files with all stuck agent details for further analysis
• Reusable: Includes reset() method for processing multiple event files with the same writer instance

Usage
As a standalone command:

java -cp matsim.jar org.matsim.application.analysis.population.StuckAgentsWriter \
  --events events.xml.gz \
  --output output/

Integrated into a contoller:

EventsManager eventsManager = EventsUtils.createEventsManager();
StuckAgentsWriter writer = new StuckAgentsWriter();
eventsManager.addHandler(writer);
// ... run simulation or read events ...
writer.writeFile("output/stuck_agents.xml");

Output Format

The tool generates an XML file with the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<stuckAgents count="3">
  <stuckAgent personId="person1" time="02:00:00" linkId="link123" legMode="car"/>
  <stuckAgent personId="person2" time="04:00:00" linkId="link456" legMode="pt" />
  <stuckAgent personId="person3" time="05:00:00" linkId="unknown" legMode="walk"/>
</stuckAgents>

It does capture "reason", if that exists in the events, 99.99% of the time it doesn't.

Testing
Includes unit tests covering:

• Event handling and data collection
• XML output generation and validation
• Reset functionality for writer reuse
• Command-line execution

This may need some work and testing before being ready.

Next iteration could infer the reason or cause, based upon some logic. e.g. miss the last bus, by checking timetable @kainagel?