JOSS software review comments

[leijerry888]

• v0.3.0 has import issues causing runtime error, I see that development branch has fixed this. so I am reviewing the development branch.
• when running in interactive mode, the "column" width of interactive options gets wider and wider and causes mis-alignments in options. (example in the following error info snippet)
• When I am testing the the e2 example (no plugin), I encountered the following breaking error:

[DEV-INFO] - 2026-06-21 22:31:18,607  bim2sim.Playground.run_task: Starting Task '<Task (CreateRelations)>'
[DEV-INFO] - 2026-06-21 22:31:18,608  bim2sim.tasks.base.CreateRelations.run: Creating bim2sim elements relations.
[DEV-INFO] - 2026-06-21 22:31:18,632  bim2sim.Playground.run_task: Successfully finished Task '<Task (CreateRelations)>'
[DEV-INFO] - 2026-06-21 22:31:18,632  bim2sim.Playground.run_task: <Task (CreateRelations)> done
[Decision 1/1] What shall we do?
Additional commands: cancel
  key  label                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             value
  0    Reset all progress                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Reset
  1    Quit interactive tasks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Quit
  2    Task to get the weather file for later simulation                                                                                                                                                                                                                                                                                                                                                                                                                                                                 Weather
  3    Deserialize elements, run() method holds detailed information.                                                                                                                                                                                                                                                                                                                                                                                                                                                    DeserializeElements
  4    Combine thermal zones to reduce the amount of thermal zones.

    As the zoning of simulation models is a time-consuming task we decided to
    automate it with the tasks.
    This task will combine multiple thermal zones into one zone based on the
    criteria selected in the simulation type settings and the decisions made.
    We do this by giving the user multiple criteria to select from:
        * External/Internal
        * Orientation
        * Usage
        * Window to wall ratio
      CombineThermalZones
  5    Disaggregation of elements, run() method holds detailed information.                                                                                                                                                                                                                                                                                                                                                                                                                                              DisaggregationCreationAndTypeCheck
Enter key: 4
[DEV-INFO] - 2026-06-21 22:31:23,001  bim2sim.Playground.run_task: Starting Task '<Task (CombineThermalZones)>'
[DEV-INFO] - 2026-06-21 22:31:23,001  bim2sim.tasks.base.CombineThermalZones.run: Try to reduce number of thermal zones by combining.
[DEV-ERROR] - 2026-06-21 22:31:23,002  bim2sim.Playground.run_task: Task '<Task (CombineThermalZones)>' failed!
Traceback (most recent call last):
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/base.py", line 110, in run_task
    result = task.run(**read_state)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/bps/combine_tz.py", line 30, in run
    elif (self.playground.sim_settings.zoning_criteria is not
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'BuildingSimSettings' object has no attribute 'zoning_criteria'
[DEV-ERROR] - 2026-06-21 22:31:23,014  bim2sim.run: Something went wrong!: <Task (CombineThermalZones)>
Traceback (most recent call last):
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/base.py", line 110, in run_task
    result = task.run(**read_state)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/bps/combine_tz.py", line 30, in run
    elif (self.playground.sim_settings.zoning_criteria is not
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'BuildingSimSettings' object has no attribute 'zoning_criteria'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/project.py", line 447, in run
    for decision_bunch in run():
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/project.py", line 493, in _run_interactive
    yield from self.playground.run_task(task_class(self.playground))
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/base.py", line 113, in run_task
    raise TaskFailed(str(task))
bim2sim.tasks.base.TaskFailed: <Task (CombineThermalZones)>
[DEV-INFO] - 2026-06-21 22:31:23,019  bim2sim.kernel.decision.save: Saved 10 decisions.
[DEV-WARNING] - 2026-06-21 22:31:23,019  bim2sim.finalize: Decisions are saved in '/private/var/folders/y2/p87g4l150bs4g7ffc5qmy_xh0000gn/T/bim2sim_example1dywxikb_/decisions_backup.json'. Rename file to 'decisions.json' to reuse them.

• run the energyplus e1 example has the following error, please check. Is there a version compatibility requirement for EnergyPlus? I am testing with v26.1. When the line of setting project.sim_settings.ep_install_path is commented out, like in the current state of the example py and ipynb file, terminal message indicates that the code goes to look for EnergyPlus 9.4 documents.

[31;20m[DEV-ERROR] - 2026-06-21 22:45:42,061  bim2sim.Playground.run_task: Task '<Task (CreateIdf)>' failed![0m
Traceback (most recent call last):
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/base.py", line 110, in run_task
    result = task.run(**read_state)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/plugins/PluginEnergyPlus/bim2sim_energyplus/task/ep_create_idf.py", line 87, in run
    idf, sim_results_path = self.init_idf(self.playground.sim_settings,
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/plugins/PluginEnergyPlus/bim2sim_energyplus/task/ep_create_idf.py", line 209, in init_idf
    idf = IDF(plugin_ep_path + '/data/Minimal.idf')
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/eppy/modeleditor.py", line 579, in __init__
    self.read()
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/geomeppy/patches.py", line 262, in read
    ) = idfreader1(
        ^^^^^^^^^^^
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/geomeppy/patches.py", line 90, in idfreader1
    versiontuple = iddversiontuple(iddfile)
                   ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/eppy/idfreader.py", line 41, in iddversiontuple
    fhandle = open(afile, "rb")
              ^^^^^^^^^^^^^^^^^
NotADirectoryError: [Errno 20] Not a directory: '/usr/local/bin/energyplus/Energy+.idd'
[31;20m[DEV-ERROR] - 2026-06-21 22:45:42,110  bim2sim.run: Something went wrong!: <Task (CreateIdf)>[0m
Traceback (most recent call last):
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/base.py", line 110, in run_task
    result = task.run(**read_state)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/plugins/PluginEnergyPlus/bim2sim_energyplus/task/ep_create_idf.py", line 87, in run
    idf, sim_results_path = self.init_idf(self.playground.sim_settings,
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/plugins/PluginEnergyPlus/bim2sim_energyplus/task/ep_create_idf.py", line 209, in init_idf
    idf = IDF(plugin_ep_path + '/data/Minimal.idf')
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/eppy/modeleditor.py", line 579, in __init__
    self.read()
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/geomeppy/patches.py", line 262, in read
    ) = idfreader1(
        ^^^^^^^^^^^
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/geomeppy/patches.py", line 90, in idfreader1
    versiontuple = iddversiontuple(iddfile)
                   ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/jxl/mamba/envs/bim2sim/lib/python3.11/site-packages/eppy/idfreader.py", line 41, in iddversiontuple
    fhandle = open(afile, "rb")
              ^^^^^^^^^^^^^^^^^
NotADirectoryError: [Errno 20] Not a directory: '/usr/local/bin/energyplus/Energy+.idd'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/project.py", line 447, in run
    for decision_bunch in run():
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/project.py", line 470, in _run_default
    yield from self.playground.run_task(task_cls(self.playground))
  File "/Users/jxl/GitRepos/bim2sim/bim2sim/tasks/base.py", line 113, in run_task
    raise TaskFailed(str(task))
bim2sim.tasks.base.TaskFailed: <Task (CreateIdf)>
[32;20m[DEV-INFO] - 2026-06-21 22:45:42,113  bim2sim.kernel.decision.save: Saved 0 decisions.[0m
[33;20m[DEV-WARNING] - 2026-06-21 22:45:42,113  bim2sim.finalize: Decisions are saved in '/private/var/folders/y2/p87g4l150bs4g7ffc5qmy_xh0000gn/T/bim2sim_example16ea19pu4/decisions_backup.json'. Rename file to 'decisions.json' to reuse them.[0m
[31;20m[DEV-ERROR] - 2026-06-21 22:45:42,114  bim2sim.finalize: Project "AC20-FZK-Haus" finished, but not successful[0m

• There seem to be around 20 todos in the code that marked discovered issues not being fixed. Pleas check if they have been fixed or can be safely left for later.
• Many sub-sections in the github page of this repo seems to be a duplicate with no contents within. For example: https://bim2sim.github.io/bim2sim//development/docs/user-guide/PluginTemplate.html#how-to-run-the-simulation . Please re-visit and update"