The MATSim API was/is designed with the following use cases in mind:
A 5th case, starting the controler out of a java pgm (including capability to set controler listeners), may have to be added ... it is possible to do this, but not api-based.
In apr'11, api-based network generation was added as use case 0.
Case 0, i.e. "network generation", is roughly there, but needs a number of "utilities" that do not have stable paths.
Case 1, i.e. "initial demand generation", in our view works quite well. Please talk to us if things do not work or if you desire additional functionality.
Case 2, i.e. "behavioral modules", is not tested, and needs an entry in the core. Testers are welcome; please talk to us.
Case 3, i.e. "alternative mobsims", is not tested. Testers are welcome; please talk to us.
Case 5, i.e. "analysis/postprocessing", is not tested. Testers are welcome; please talk to us.