The process of creating an initial demand (the "population" of the scenario) can be quiet challanging, as a lot of different data sources may be used, depending on what's available. The good thing about MATSim is, that you can start with a fairly simple initial demand and improve it later.
A simple description of agents is as follows:
<person id="1">
<plan>
<act type="home" x="20" y="-5" end_time="06:00:00" />
<leg mode="car" />
<act type="work" x="80" y="5" end_time="16:00:00" />
<leg mode="car" />
<act type="home" x="20" y="-5" />
</plan>
</person> Each person needs a unique identifier id and at least one plan. The plan contains acts and legs. The activities need at least the type, a coordinate-pair (x, y), and an end time (end_time). Legs between activities need a mode, usually set to "car", but do not need any route information at this stage.
NOTE: There is also an activity duration attribute. At this point (may'10), this is essentially deprecated (because the functional differentiation between "dur" and "end_time" did not work that well).
If you are coming from time-dependent OD matrices, do something like the following
<person id="1">
<plan>
<act type="dummy" x="20" y="-5" end_time="06:00:00" />
<leg mode="car" />
<act type="dummy" x="80" y="5" />
</plan>
</person> Note that there is now no return trip.
end_time does not have to be an exact value; with certain set-ups, the simulation can modify these attributes to find better values on its own.
On the other hand, if you are coming from time-dependent OD matrices, you should "smear out" the activity end times (= trip departure times) over the time period of the validity of the matrix, and then not use the "TimeAllocationMutator" later.
The simulation expects all activities to take place on links. To assign each activity a link based on its coordinates, use the tool org.matsim.run.XY2Links. As an argument, pass it a configuration file which contains the information about the network, input-plans and output-plans, e.g.:
java -cp <class-to-matsim-jar>/matsim.jar org.matsim.run.XY2Links config.xml
The tool will then read all plans from the input-file and search for each activity the nearest link from the network. The plans with this additional information are then written to the output-file. That output-file could then be used to start the simulation with org.matsim.run.Controler (see the Getting-Started Tutorial).
Attached are a very small sample network, a very simplistic plans file and a configuration file that can be used with XY2Links.
In more complicated situations, it often makes sense to program the initial demand generation in Java. See matsim.org/node/340.