Merge branch 'main' into make-latex-docs-possible

.github/workflows/citation.yml

@@ -0,0 +1,36 @@
+name: Validate CITATION.cff
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+    types: [opened, reopened, edited, synchronize]
+
+jobs:
+  build:
+    name: Validate CITATION.cff
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: Skip Duplicate Actions
+      uses: fkirc/skip-duplicate-actions@v5
+
+    - uses: actions/checkout@v3
+
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.8
+
+    - name: Install cffconvert
+      run: |
+        pip3 install --user cffconvert
+        cffconvert --version
+
+    - name: Validate schema
+      run: |
+        cffconvert --validate -i CITATION.cff

.github/workflows/demo.yaml

@@ -36,7 +36,7 @@ jobs:
 
     - name: Install Python dependencies
       run: |
-        pip3 install --user ${{ matrix.python-inplace }} .
+        pip3 install --user ${{ matrix.inplace }} .
 
     - name: Run demo
       run: |

.github/workflows/installation-from-remote.yaml

@@ -5,6 +5,7 @@ on:
     - cron: '42 23 * * 3'  # every Wednesday at 23:42
   pull_request:
     types: [opened, reopened, edited, synchronize]
+  workflow_dispatch:
 
 jobs:
   build-conda-on-windows:
@@ -29,12 +30,14 @@ jobs:
     - name: Install ConFlowGen
       run: |
         conda info
-        conda create -n test-install-conflowgen -c conda-forge conflowgen pytest
+        conda update conda
+        conda info
+        conda create -n test-install-conflowgen -c conda-forge conflowgen pytest parameterized
 
     - name: Prepare tests
       run: |
         conda activate test-install-conflowgen
-        conda install pillow>=9.0
+        conda install -c conda-forge pillow>=9.0
 
     - name: Run tests
       run: |
@@ -65,8 +68,10 @@ jobs:
         conda init bash
         eval "$(conda shell.bash hook)"
         conda info
+        conda update conda
+        conda info
         conda activate base
-        conda create -n test-install-conflowgen -c conda-forge conflowgen pytest
+        conda create -n test-install-conflowgen -c conda-forge conflowgen pytest parameterized
 
     - name: Run tests
       run: |
@@ -97,7 +102,7 @@ jobs:
 
     - name: Install ConFlowGen
       run: |
-        python -m pip install conflowgen pytest
+        python -m pip install conflowgen pytest parameterized
         python -m pip show --verbose conflowgen
 
     - name: Run tests

.gitignore

@@ -64,3 +64,4 @@ examples/Python_Script/databases/
 # Ignore local changes as they happen with every execution. If something changes, the commit must be forced.
 conflowgen/data/tools/
 docs/notebooks/data/prepared_dbs/
+.tools/

CITATION.cff

@@ -3,6 +3,12 @@
 
 cff-version: 1.2.0
 title: ConFlowGen
+abstract: A generator for synthetic container flows at maritime container terminals with a focus on yard operations
+contact:
+  - affiliation: "Institute of Maritime Logistics, Hamburg University of Technology (TUHH)"
+    email: [email protected]
+    family-names: Kastner
+    given-names: Marvin
 message: >-
   Please cite this software using the metadata from
   'preferred-citation'.
@@ -18,7 +24,12 @@ authors:
     email: [email protected]
     affiliation: Hamburg University of Technology (TUHH), Institute of Maritime Logistics
     orcid: 'https://orcid.org/0000-0003-1982-9436'
-version: 2.1.1
+  - given-names: Shubhangi
+    family-names: Gupta
+    email: [email protected]
+    affiliation: Hamburg University of Technology (TUHH), Institute of Maritime Logistics
+    orcid: 'https://orcid.org/0009-0003-3574-2899'
+version: 3.0.0
 repository-code: "https://github.com/1kastner/conflowgen"
 keywords:
   - logistics
@@ -47,7 +58,7 @@ preferred-citation:
       country: DE
       date-start: 2022-02-23
       date-end: 2022-02-25
-  editors-series:
+  editors:
     - family-names: Freitag
       given-names: Michael
     - family-names: Kinra

Contributing.md

@@ -58,14 +58,14 @@ Each new feature should be covered by tests unless there are very good reasons w
 
 For generating the documentation, 
 [sphinx](https://www.sphinx-doc.org/)
-is used - mostly the default settings are maintained.
-The documentation generation process is based on the sphinx boilerplate and the `make` process is unchanged.
-To generate the documentation, move to the directory `<project-root>/docs`.
+is used and mostly the default settings are maintained.
+
+To generate the documentation, change your working directory to `<project-root>/docs`.
 First, please make sure that you have up-to-date prepared sqlite databases in 
 `<project-root>/docs/notebooks/data/prepared_dbs/`.
 The sqlite databases compatible with the latest version of ConFlowGen are available at
 https://media.tuhh.de/mls/software/conflowgen/docs/data/prepared_dbs/.
-In `./docs/download_prepared_sqlite_databases.ps1`, you find the instructions for how to download the latest databases
+In `<project-root>/docs/download_prepared_sqlite_databases.ps1`, you find the instructions for how to download the latest databases
 and where to store them.
 In case you have updated the sqlite scheme, you might need to create these databases on your own with your latest
 adaptions.
@@ -74,8 +74,11 @@ This is achieved by running the scripts stored in
 and copy the resulting sqlite database into
 `<project-root>/docs/notebooks/data/prepared_dbs/`.
 
-Once the prepared databases are in place, the documentation can be created.
-As a Windows user you run `.\make.bat html` from the PowerShell or CMD.
+Once the prepared databases are in place, the documentation can be built.
+The documentation generation process is based on the sphinx boilerplate and the `make` process is unchanged.
+For more information on that, see the
+[Sphinx documentation on the build process](https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build).
+As a Windows user, you run `.\make.bat html` from the PowerShell or CMD inside the directory `<project-root>/docs`.
 Linux users invoke `make html` instead.
 The landing page of the documentation is created at `<project-root>/docs/_build/html/index.html`.
 It is advised to use a strict approach by using the additional argument `SPHINXOPTS="-W --keep-going`

Readme.md

@@ -1,5 +1,6 @@
 [![Documentation Status](https://readthedocs.org/projects/conflowgen/badge/?version=latest)](https://conflowgen.readthedocs.io/en/latest/?badge=latest)
-[![Docs](https://github.com/1kastner/conflowgen/actions/workflows/docs.yaml/badge.svg)](https://github.com/1kastner/conflowgen/actions/workflows/docs.yaml)
+[![documentation built](https://github.com/1kastner/conflowgen/actions/workflows/docs.yaml/badge.svg)](https://github.com/1kastner/conflowgen/actions/workflows/docs.yaml)
+[![CITATION.cff valid](https://github.com/1kastner/conflowgen/actions/workflows/citation.yml/badge.svg)](https://github.com/1kastner/conflowgen/actions/workflows/citation.yml)
 
 [![Tests](https://github.com/1kastner/conflowgen/actions/workflows/unittests.yaml/badge.svg)](https://github.com/1kastner/conflowgen/actions/workflows/unittests.yaml)
 [![codecov](https://codecov.io/gh/1kastner/conflowgen/branch/main/graph/badge.svg?token=GICVMYHJ42)](https://codecov.io/gh/1kastner/conflowgen)

conflowgen/__init__.py

@@ -35,10 +35,10 @@
     InboundAndOutboundVehicleCapacityAnalysis
 from conflowgen.analyses.inbound_and_outbound_vehicle_capacity_analysis_report import \
     InboundAndOutboundVehicleCapacityAnalysisReport
-from conflowgen.analyses.inbound_to_outbound_vehicle_capacity_utilization_analysis import \
-    InboundToOutboundVehicleCapacityUtilizationAnalysis
-from conflowgen.analyses.inbound_to_outbound_vehicle_capacity_utilization_analysis_report import \
-    InboundToOutboundVehicleCapacityUtilizationAnalysisReport
+from conflowgen.analyses.outbound_to_inbound_vehicle_capacity_utilization_analysis import \
+    OutboundToInboundVehicleCapacityUtilizationAnalysis
+from conflowgen.analyses.outbound_to_inbound_vehicle_capacity_utilization_analysis_report import \
+    OutboundToInboundVehicleCapacityUtilizationAnalysisReport
 from conflowgen.analyses.container_flow_by_vehicle_type_analysis import ContainerFlowByVehicleTypeAnalysis
 from conflowgen.analyses.container_flow_by_vehicle_type_analysis_report import \
     ContainerFlowByVehicleTypeAnalysisReport
@@ -64,6 +64,9 @@
     ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysis
 from conflowgen.analyses.container_flow_vehicle_type_adjustment_per_vehicle_analysis_report import \
     ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport
+from conflowgen.analyses.container_flow_by_vehicle_instance_analysis import ContainerFlowByVehicleInstanceAnalysis
+from conflowgen.analyses.container_flow_by_vehicle_instance_analysis_report import (
+    ContainerFlowByVehicleInstanceAnalysisReport)
 
 # Cache for analyses and previews
 from conflowgen.data_summaries.data_summaries_cache import DataSummariesCache
@@ -83,7 +86,7 @@
 from conflowgen.domain_models.data_types.storage_requirement import StorageRequirement
 
 # List of functions
-from conflowgen.logging.logging import setup_logger
+from conflowgen.logger.logger import setup_logger
 from conflowgen.analyses import run_all_analyses
 from conflowgen.previews import run_all_previews
 

conflowgen/analyses/__init__.py

@@ -7,12 +7,13 @@
     ContainerFlowAdjustmentByVehicleTypeAnalysisReport
 from .container_flow_adjustment_by_vehicle_type_analysis_summary_report import \
     ContainerFlowAdjustmentByVehicleTypeAnalysisSummaryReport
+from .container_flow_by_vehicle_instance_analysis_report import ContainerFlowByVehicleInstanceAnalysisReport
 from .container_flow_by_vehicle_type_analysis_report import ContainerFlowByVehicleTypeAnalysisReport
 from .container_flow_vehicle_type_adjustment_per_vehicle_analysis_report import \
     ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport
 from .inbound_and_outbound_vehicle_capacity_analysis_report import InboundAndOutboundVehicleCapacityAnalysisReport
-from .inbound_to_outbound_vehicle_capacity_utilization_analysis_report import \
-    InboundToOutboundVehicleCapacityUtilizationAnalysisReport
+from .outbound_to_inbound_vehicle_capacity_utilization_analysis_report import \
+    OutboundToInboundVehicleCapacityUtilizationAnalysisReport
 from .modal_split_analysis_report import ModalSplitAnalysisReport
 from .quay_side_throughput_analysis_report import QuaySideThroughputAnalysisReport
 from .truck_gate_throughput_analysis_report import TruckGateThroughputAnalysisReport
@@ -26,6 +27,7 @@
 reports: typing.Iterable[typing.Type[AbstractReport]] = [
     InboundAndOutboundVehicleCapacityAnalysisReport,
     ContainerFlowByVehicleTypeAnalysisReport,
+    ContainerFlowByVehicleInstanceAnalysisReport,
     ContainerFlowAdjustmentByVehicleTypeAnalysisReport,
     ContainerFlowAdjustmentByVehicleTypeAnalysisSummaryReport,
     ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport,
@@ -34,7 +36,7 @@
     QuaySideThroughputAnalysisReport,
     TruckGateThroughputAnalysisReport,
     YardCapacityAnalysisReport,
-    InboundToOutboundVehicleCapacityUtilizationAnalysisReport
+    OutboundToInboundVehicleCapacityUtilizationAnalysisReport
 ]
 
 

conflowgen/analyses/abstract_analysis.py

@@ -98,35 +98,39 @@ def _restrict_storage_requirement(selected_containers: ModelSelect, storage_requ
     @staticmethod
     def _restrict_container_delivered_by_vehicle_type(
             selected_containers: ModelSelect, container_delivered_by_vehicle_type: typing.Any
-    ) -> ModelSelect:
+    ) -> (ModelSelect, list[ModeOfTransport]):
         if hashable(container_delivered_by_vehicle_type) \
                 and container_delivered_by_vehicle_type in set(ModeOfTransport):
             selected_containers = selected_containers.where(
                 Container.delivered_by == container_delivered_by_vehicle_type
             )
+            list_of_vehicle_types = [container_delivered_by_vehicle_type]
         else:  # assume it is some kind of collection (list, set, ...)
             selected_containers = selected_containers.where(
                 Container.delivered_by << container_delivered_by_vehicle_type
             )
-        return selected_containers
+            list_of_vehicle_types = list(container_delivered_by_vehicle_type)
+        return selected_containers, list_of_vehicle_types
 
     @staticmethod
     def _restrict_container_picked_up_by_vehicle_type(
             selected_containers: ModelSelect, container_picked_up_by_vehicle_type: typing.Any
-    ) -> ModelSelect:
+    ) -> (ModelSelect, list[ModeOfTransport]):
         if container_picked_up_by_vehicle_type == "scheduled vehicles":
             container_picked_up_by_vehicle_type = ModeOfTransport.get_scheduled_vehicles()
-
-        if hashable(container_picked_up_by_vehicle_type) \
+            list_of_vehicle_types = container_picked_up_by_vehicle_type
+        elif hashable(container_picked_up_by_vehicle_type) \
                 and container_picked_up_by_vehicle_type in set(ModeOfTransport):
             selected_containers = selected_containers.where(
                 Container.picked_up_by == container_picked_up_by_vehicle_type
             )
+            list_of_vehicle_types = [container_picked_up_by_vehicle_type]
         else:  # assume it is some kind of collection (list, set, ...)
             selected_containers = selected_containers.where(
                 Container.picked_up_by << container_picked_up_by_vehicle_type
             )
-        return selected_containers
+            list_of_vehicle_types = list(container_picked_up_by_vehicle_type)
+        return selected_containers, list_of_vehicle_types
 
     @staticmethod
     def _restrict_container_picked_up_by_initial_vehicle_type(

conflowgen/analyses/container_dwell_time_analysis.py

@@ -64,12 +64,12 @@ def get_container_dwell_times(
             )
 
         if container_delivered_by_vehicle_type != "all":
-            selected_containers = self._restrict_container_delivered_by_vehicle_type(
+            selected_containers, vehicle_types = self._restrict_container_delivered_by_vehicle_type(
                 selected_containers, container_delivered_by_vehicle_type
             )
 
         if container_picked_up_by_vehicle_type != "all":
-            selected_containers = self._restrict_container_picked_up_by_vehicle_type(
+            selected_containers, vehicle_types = self._restrict_container_picked_up_by_vehicle_type(
                 selected_containers, container_picked_up_by_vehicle_type
             )
 

conflowgen/analyses/container_dwell_time_analysis_report.py

@@ -4,8 +4,9 @@
 import statistics
 import typing  # noqa, pylint: disable=unused-import  # lgtm [py/unused-import]  # used in the docstring
 
-import matplotlib.axis
 import pandas as pd
+import matplotlib.axis
+
 
 from conflowgen.analyses.container_dwell_time_analysis import ContainerDwellTimeAnalysis
 from conflowgen.reporting import AbstractReportWithMatplotlib

conflowgen/analyses/container_flow_adjustment_by_vehicle_type_analysis_summary_report.py

@@ -2,9 +2,9 @@
 
 import typing  # noqa, pylint: disable=unused-import  # lgtm [py/unused-import]  # used in the docstring
 
-import matplotlib.axis
-import numpy as np
 import pandas as pd
+import numpy as np
+import matplotlib.axis
 
 from conflowgen.analyses.container_flow_adjustment_by_vehicle_type_analysis_summary import \
     ContainerFlowAdjustmentByVehicleTypeAnalysisSummary, ContainerFlowAdjustedToVehicleType