tudelft-citg/opentnsim

Analysis of traffic behaviour on networks for different traffic scenarios and network configurations.

OpenTNSim

Open source Transport Network Simulation - Analysis of traffic behaviour on networks for different traffic scenarios and network configurations.

Documentation can be found: here

Book

You can find the opentnsim book, based on the examples in the notebooks folder on the opentnsim-book website.

Installation

To install OpenTNSim, run this command in your terminal:

pip install opentnsim

To also install the extra dependencies used for testing you can use:

pip install opentnsim[testing]

This is the preferred method to install OpenTNSim, as it will always install the most recent stable release.

If you don not have pip installed, this Python installation guide can guide you through the process.

You can read the documentation for other installation methods.

Testing

You can run the unit tests

pytest

Or you can run the notebook tests:

pytest --nbmake ./notebooks --nbmake-kernel=python3 --ignore ./notebooks/cleanup ./notebooks/students

Or you can run a specific test like this:

pytest -k test_single_engine

`

Examples

The benefit of OpenTNSim is the generic set-up. A number of examples are presented in a seperate Jupyter Notebook repository. Information on how to use the notebooks is presented in that repository as well.

Book

Based on the examples and docs a book can be generated using the commands make book and cleaned up using make clean-book. These commands are unix only.

Code quality

Code quality is checked using sonarcloud. You can see results on the sonarcloud website. For now we have disabled coverage and duplication checks. These can be enabled when we include coverage measurements and reduce duplication by optimizing the tests.

OpenCLSim

OpenTNSim makes use of the OpenCLSim code. Both packages are maintained by the same team of developers. There are some differences between packages (e.g. in logging approaches), but you can use them together. We are working towards further integrating these two software packages.

opentnsim's Issues

Add remaining notebooks (1-17)

Edit: I added the notebooks in toc folder already so as soon as the notebooks are ready I can copy them

Edit 2: I added all working notebooks. 8, 9, 14, 15, 16 are not working for me.

Create (or use) notebooks for section 'setting up python environment'.

Update the create environment documentation so that it is easy to understand for students:

• Add link to simple tutorial for Command (windows + osx)
• Check if the steps we have now lead to a usable environment
• Add videos from Fedor's tutorial
• Describe the mamba alternative for slow computers.

Cleanup / remove duplicates

• hide/remove shapely 2.0 .coords warning
• move data to separate dir
• move unused notebooks to cleanup / students/phd

Create design of TOC

Add Example 00 to book

Integrate docs with book

• Determine optimal file structure for docs/book combination
• Add to Makefile (to run in circleci)
• Determine the "main doc" (book in docs or docs book)

Fix broken notebooks (check in CircleCi)

Check in circle ci:
https://app.circleci.com/pipelines/github/TUDelft-CITG/OpenTNSim?branch=feature%2Fnotebooks-integration&filter=all

Fix broken notebooks

Advanced / Energy

• Create new toc for Advanced simulations
• Pick notebooks per toc item
• Improve notebooks

Publish book at readthedocs / github pages / elsewhere

• Add picture reference to book in rtfm
• Add book to azure static pages

Write intro text

And look at other notebooks for inspiration. Content should answer the 'What's in it for me'-question.

Environment for windows/students

Run on Tenzin laptop

Gives error
Remove notebook from environment and see if create works.

Edit: Does not work, conda forge seems to be the problem

Now gives the following error:

Doing some more tests

AIS real data chapter

Use patlib in notebooks

So we do not have to copy all the files into the book folder as well

Edit: I updated the TOC folder already, so as soon as I fixed the relative paths all notebooks can be constructed

Edit 2: I got it working for notebook 5, but if I commit there are a lot of changes so want to discuss tomorrow first

Locking module improvements

second step

• Add real world lock notebook to example book, based on student example
  • Create graph + lock on fis graph
• review new modules
• cherry pick existing modules
• write the abstract lock / core functionality unit tests
• manual re-merge the changed modules
• add real world unit test
• add schematic lock figure (for terminology)
• refactor most important parts (add lock complex to network, flexible approach to digraph/multidigraph, make log variants consistent, consider use of HasLockInformation, make variable names more consistent (Wlev vs WLev))
• Rerun previous simulation (check e.g. if leave_opposite_lineup_area directions are correct)
• Check code that uses things like current_velocity[2] or current_velocity[-1]. That is unreliable without checks.
• Extend real world lock notebook to example book
  • Create schematic graph + lock
  • Create fis graph based lock
  • Create Weurt + Graven reconstruction
  • Create Lock + Salt (IJmuiden)
  • Create Volkerak + Energy + Compare with AIS energy

Trying to get relative path to work

Now we have to copy every file we need into the book folder. I think the issue is that in the _toc.yml file it states root: intro.md and it searches files from there

Edit: Fedor will look into it

Evaluate content from a student perspective and make it easier, more fun to consume.

• go over text
• check simplest examples
• double check structure
• use fresh test case (n=1), other student for first impression

Simplify the core VesselProperties

• Separate dimensions (Width, Height, Length)
• 3 implementations for draught (T):
  • Fixed draught (_T)
  • Payload Payload2T
  • Filling degree (T_e, T_f)
• Separate HasSquat

Create section that contains an intro to how OpenTNSim program is created. (Event simulation, SimPy)

Add an already existing notebook from Fedor Baart to the book that describes the creation of a program such as OpenTNSim from start to finish.

Add Notebooks 1-5

Move Energy out of core.py

• Create separate (consumesenergy) branch from master
• move ConsumesEnergy to energy.py
• Check if notebooks/tests are still working
• Merge branch with PhdManJiang