We want to use libfmt for formatting strings.

• Add libfmt installation to cpp/scripts/setup-dependencies.sh
• Update cpp/scripts/README.md
• Link libfmt in cmake
• Check and implement required libfmt configuration
• Write test to check linking and existence of libfmt

Currently the position of the agents is saved as a list of floating point values + the id of the Level the agent should be generated. For easier usage and to unify the handling of positions the geometry types should be used.

# TODO (kkz) The SpawnPedestrianEvent should already contian jpscore.Coordinates.
# It feels way to verbose to create them here
self.simulation.add_agent(
    Coordinate(
        LengthUnit(event.event.position[0], Units.m),
        LengthUnit(event.event.position[1], Units.m),
        Level(event.event.level),
    )
)

would become

self.simulation.add_agent( event.coordinate )

When exposing the cpp part to python, often a warning for different types of UniqueId<T> is generated. The types seem to vary from the classes themselves, e.g., SpecialArea to their usage, e.g., 'World`. There seem to be some shenanigans with the order in which the types are bound, but I couldn't figure out any reoccurring patterns. See complete error message:

  LINK : error C2220: the following warning is treated as an error [C:\BuildAgent\work\826b4a2133b258c8\build\pycore\source\jpscore.vcxproj]
LINK : warning C4744: 'static struct std::atomic<unsigned __int64> jps::UniqueId<class jps::SpecialArea,unsigned __int64>::uid_counter' has different type in 'c:\buildagent\work\826b4a2133b258c8\cpp\pycore\source\geometry\world_binding.cpp' and 'c:\buildagent\work\826b4a2133b258c8\cpp\pycore\source\geometry\special_area_binding.cpp': '__declspec(align(8)) struct (8 bytes)' and 'struct (8 bytes)' [C:\BuildAgent\work\826b4a2133b258c8\build\pycore\source\jpscore.vcxproj]

Creating library C:/BuildAgent/work/826b4a2133b258c8/build/lib/Release/jpscore.lib and object C:/BuildAgent/work/826b4a2133b258c8/build/lib/Release/jpscore.exp
Generating code
LINK : fatal error LNK1257: code generation failed [C:\BuildAgent\work\826b4a2133b258c8\build\pycore\source\jpscore.vcxproj]

It seemed to be a compiler bug: https://developercommunity.visualstudio.com/t/strange-alignment-warnings-with-inlined-static-ato/605753 which is already solved but the error still occurs.

For solving:

• create minimum example where this error occurs
• create issue/question in pybind github (https://github.com/pybind/pybind11/)
• learn what needs to be changed

Pedestrians in the simulation should be spawned corresponding to a event configuration file. This file can be created using python tooling.
Implement the tool for generating pedestrian spawn events in the event configuration file. The first tool should create uniform random distributed pedestrians in a spawn area. Command line arguments: which area, how many, distribution.

A suggested example event configuration file could be:

[
	{
		"t": 0, 
		"event": {
			"type": "spawn_pedestrian",
			"x":22.6,
			"y": -1.5,
			"floor": "groundfloor"
		}
	},
	{
		"t": 1337, 
		"event": {
			"type": "panic"
		}
	},
]

World should be created using a WorldBuilder with python bindings.

• API for adding new levels, walls and special areas
• Collecting the new geometry structures
• Method for creating the world from collected structure (buildWorld())
• Sanity Checks for definition and implementation

QCAD is a free, open source software and might be used to define geometries and export them as .dxf files.
Following things must be tested:

• draw lines for several floors (the basic geometry)
• draw areas for several floors
• define different types of areas by color
• which options/properties are available?
• easy usage?
• editing of existing geometries
• draw a simple, intermediate and complex geometry

Since the core C++ library should not write log files directly we want to register callbacks to call with the log messages.
The available Logging Levels should be: Debug, Info, Warning, Error

• Define Callback signature (callback(string or string_view or const char*) ?)
• Implement API Functions for registering Logging Callbacks
• Without callback set it should be a nullop

This issues should collect all open Documentation issues until we have a Documentation set up.
Feel free to add your Parts below

• Document the file names required for the dxf file (at the moment only world.dxf). (From #57)

Turn compiler warnings on, currently turned off.

Currently tests for formatting the basic spatial data types are missing:

• Coordinate
• SpatialVector
• Area
• SpecialArea
• LengthUnit
• LineSegment

Currently we use the LengthUnit type to emphasize that we are dealing with a certain type of value instead of simply double/float values. We should extend this approach to further needed physical types.
Especially we would need a resulting type for any arithmetic operation with a LengthUnit, e.g., LengthUnit/time should yield a speed type, LengthUnit*LengthUnit should yield an area type, etc.

Suggestion:
Use units, which may be included in the C++ standard with C++23/26.

Advantages:

• see units-repo

Disadvantages:

• Needs C++-20
• AppleClang not supported

If you have any other ideas? Or should we stick with double types for the rest?

The user defined literals expect long double, but the LengthUnit is based on double. Hence it may happen that when inline auto operator"" _um(long double p_quantity) -> jps::LengthUnit (or any other) is called we lose some precision. We should assure that this doesn't happen (static_assert maybe).

• Tests for parsing of different geometry entities
• Unit tests

Write the first draft of the Simulator class which can be used by python to conduct a simulation. This will be changed and extended later.

• write simple API draft
• write unit tests
• write python bindings
• write python unit tests

libfmt offers the possibility to pass the desired precision of the output to the formatter for the spatial data types.
https://fmt.dev/latest/api.html#formatting-user-defined-types

This would enable to a better controllable output, example:

fmt::format("{:.4f}", Coordiante{0.1, 0.1, Level{1}}); // "COORDINATE(0.1000, 0.1000) -- LEVEL 1"
fmt::format("{:.1f}", Coordiante{0.1, 0.1, Level{1}}); // "COORDINATE(0.1, 0.1) -- LEVEL 1"

ToDo:

• add formatting option to formatter
• add unit tests on cpp side
• change the precision for __str__ and __repr__ in the pybinds

The screenshot says it all. Tested when using clang-tidy-13. See #92

Write a tutorial about the dev environment setup.

Should contain the following:

• How to install C++ dependencies
• How to install python requirements
• How to Compile
• How to run tests
• Describe the existing folder structure

The following points must be taken care of:

• Exception handling
• Check unit specified in dxf file and parsing
• Pybind update for extended geometry components
• Parsing of POLYLINES
• Parsing of several layers/levels
• Tests -> #47
• Adequate logging information

As we will need to exchange data from the input files to the simulation, e.g., the position information from the Events, the geometry information should be (json-)serializable at the python side.

We should soon add tests for the basic spatial data structures

As the dxf-geometries may contain different levels (with different heights) there needs to be a function which maps a (x,y) coordinate + level to the corresponding z-coordinate.

• Define interface, how height information will be read from dxf-files (layer name?). In particular how to store tilted surfaces as stairs.
• Document interface!
• Add height information to level
• Add function for computing the z-coordinate.

One of the critical aspects in the simulation is the determination of the relevant neighbors who influence the movement of an Agent.

Possible solutions:

• simple 2D square grid as in jpscore
• QuadTree

Known difficulties:

• Neighborhood search need to take walls or obstacles into account

We should have a naming scheme and a corresponding clang tidy check for ensuring it.

• Define naming scheme
• Add bullet points to the CONTRIBUTING.md
• Addd clang-tidy check

Implement classes in C++ for strategic, tactical and operational level.
We want to discover missing functionality and validate the assumptions made in our design workshop.
The different levels must be independent from each other.

Currently it is only possible to generate a single pedestrian at a fixed position. For larger simulations it will be helpful to generate multiple pedestrians in a specific area.

Suggestion:
Extend the generate_pedestrian command such that instead of a fixed position also a bounding box and the number of pedestrians can be used as inputs. The position of the pedestrians should be random inside the bounding box.

Example:

jps generate_pedestrians -n 10 -xmin 0 -xmax 10 -ymin -5 -ymax 5 -o events.json -t 10 -level 0

Note:
-xmin 0 -xmax 10 -ymin -5 -ymax 5 is just one simple solution, maybe there is a more elegant way to handle such cases with argparse.

Discussion:

• An additional parameter could be the seed for the random number generator to get the same distribution (for debugging). Not sure if needed?
• Do we want already here ensure that pedestrians do not overlap are to close together? If yes an additional parameter as offset/min_distance which defines the minimal distance between two pedestrians.

When an Area is created the corresponding polygon must be closed and the segments should not intersect.

The list of all Agents inside the simulation is read on the python side, e.g., to write the trajectories. But with #72 the Agents will only be stored for each level. To hide the implementation details and add an extra layer of abstraction, I suggest to add an function getAgents to Simulation. This might be just a wrapper to a call to World::getAgents().

Discussion:
As the list of agents needs to be created as the superset of all agents per level, it will be created inside the function. Hence returning a reference won't work. Returning copies will result in some unnecessary overhead as on python side only reading this data occurs.