From 50c5a313407a279f4e62555029ebb74d456d689b Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 17:47:34 +0200 Subject: [PATCH 01/19] add top-level TiMBA description at top --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index e6f50b9..f125a69 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,13 @@ In the equilibrium processes, product supply, demand and price are balanced for ----------------- +**TiMBA** is a partial economic equilibrium model for the global forest products +market. The model endogenously simulates production, consumption and trade of +wood and wood-based products in 180 countries. TiMBA recursively computes the +market equilibrium for each country and product in a given period by maximizing +the social surplus in the global forest sector. In the equilibrium processes, +product supply, demand and price are balanced for each simulation period. + ## 1. Cite TiMBA We are happy that you use TiMBA for your research. When publishing your work in articles, working paper, presentations From c29375154228b490e7a6684fbb041ac98d605d46 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 17:48:52 +0200 Subject: [PATCH 02/19] fix citation --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f125a69..def384a 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,8 @@ product supply, demand and price are balanced for each simulation period. We are happy that you use TiMBA for your research. When publishing your work in articles, working paper, presentations or elsewhere, please cite the model as -[TI-FSM, Morland, C., Schier, F., Tandetzki, J., Honkomp, T. (2025). TiMBA (Timber market Model for policy-Based Analysis). Journal of Open Source Software, 10(115), 8034, https://doi.org/10.21105/joss.08034](https://joss.theoj.org/papers/10.21105/joss.08034#) +TI-FSM, Morland, C., Schier, F., Tandetzki, J., Honkomp, T. (2025). TiMBA (Timber market Model for policy-Based Analysis). Journal of Open Source Software, 10(115), 8034, [https://doi.org/10.21105/joss.08034](https://doi.org/10.21105/joss.08034) +[Download BibTeX](./citation.bib) The authors' collective is named Thünen Institute Forest Sector Modelling (TI-FSM). The individual authors are listed as co-authors in alphabetical order. From e9e73cdb9329cec792e34c084e6cd7ac5a7e3b18 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 17:57:25 +0200 Subject: [PATCH 03/19] add citation.bib for convenient citing --- citation.bib | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 citation.bib diff --git a/citation.bib b/citation.bib new file mode 100644 index 0000000..0cae39a --- /dev/null +++ b/citation.bib @@ -0,0 +1,12 @@ +@article{TI-FSM2025, + doi = {10.21105/joss.08034}, + url = {https://doi.org/10.21105/joss.08034}, + year = 2025, + publisher = {The Open Journal}, + volume = 10, + number = 115, + pages = 8034, + author = {TI-FSM and Morland, Christian and Schier, Franziska and Tandetzki, Julia and Honkomp, Tomke}, + title = {TiMBA (Timber market Model for policy-Based Analysis)}, + journal = {Journal of Open Source Software} +} From 64bdc700567a7928331cbfcb99b6e4218f31a3bd Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 17:58:15 +0200 Subject: [PATCH 04/19] fix Installation 'preamble', add requirements & known issues --- README.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index def384a..715352e 100644 --- a/README.md +++ b/README.md @@ -66,20 +66,31 @@ co-authors in alphabetical order. ## 2. Installation -The package is developed and tested with Python 3.9 on Windows. TiMBA is compatible with Python versions between 3.9–3.11 -with Windows and Ubuntu OS. The functionality with Python versions and different OS is continuously tested using GitHub -Actions. - -Before proceeding, please ensure that Python is installed on your system. -It can be downloaded and installed from [Python.org](https://www.python.org/downloads/release/python-3119/). +The package is developed and tested with Python 3.9 on Windows 11. TiMBA is +compatible with Python versions between 3.9 - 3.11. The functionality with +supported Python versions is continuously tested using GitHub CI with [operating +system images](https://github.com/actions/runner-images#available-images) +`windows-latest` and `ubuntu-latest`. + +### 2.1 Requirements + +- Operating system: Linux or Windows on a x64 architecture. We test Windows 11 + and Ubuntu 24.04, but other Windows and Linux versions are likely to work too. +- The Python package manager [uv](https://docs.astral.sh/uv/). We strongly + recommend to use `uv`, because it provides a very user-friendly, quick, + platform-independent and reliable way to install, use and develop TiMBA. + +That said, TiMBA can be also installed classically by creating a virtual +environment using [`venv`](https://docs.python.org/3.14/library/venv.html) and +installing with [`pip`](https://pip.pypa.io/en/stable/). To make the virtual +environment use the right Python version (if your system Python doesn't happen +to be version 3.9 - 3.11), you need to install a supported Python the the +operating system level and create the virtual environment with that version, +e.g. `python3.11 -m venv .venv`. ***Known Issues***: -TiMBA currently has compatibility issues on macOS and with Python 3.12 and 3.13. Users may experience unexpected behavior during the optimization -process on macOS, as well as package installation problems when using Python 3.12 and 3.13. -We recommend using Python 3.9–3.11 on Windows or Ubuntu OS for best results until full support of Python 3.12 and 3.13 and macOS is implemented. - +TiMBA currently does not work with Python 3.12 or higher. We observe numerical discrepancies (>5% compared to results generated on Windows or Linux) when running TiMBA on macOS which could traced back to the solver OSQP in CVXPY. The results with MacOS have not been validated. We are investigating the issue. -The package can be installed from **PyPI** or directly from **GitHub**: ### 2.1. PyPI package From 268a2eb7ae37544d6dc1f619f198accdf35c3af4 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:09:52 +0200 Subject: [PATCH 05/19] add install as cli tools --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/README.md b/README.md index 715352e..c83e43f 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,62 @@ e.g. `python3.11 -m venv .venv`. ***Known Issues***: TiMBA currently does not work with Python 3.12 or higher. We observe numerical discrepancies (>5% compared to results generated on Windows or Linux) when running TiMBA on macOS which could traced back to the solver OSQP in CVXPY. The results with MacOS have not been validated. We are investigating the issue. +### 2.2 Install uv +#### 2.2.1 Linux + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` +#### 2.2.2 Windows +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +### 2.3 Install the TiMBA command line programs + +If you want to use TiMBA as executable program, install it globally like so: + +``` bash +uv tool install -p 3.11 pytimba +``` +You will then have access to the CLI command `timba` with the subcommands `carbon`, `dashboard`, `load` ans `run`. Get an overview with `timba --help`. Detailed usage instructions are available with the argument `--help` for each of the subcommands. See section [Model settings](#model-settings) for further details. + +### 2.4 Install TiMBA from PyPi + +If you want to use TiMBA as part of your own program, you can install it from PyPi like so: + +``` bash +uv init -p 3.11 my_timba_program # Create a project skeleton with Python 3.11 +cd my_timba_program # Change into the project directory +uv add pytimba # Install TiMBA into the project's virtual environment. +``` +Use TiMBA in Python modules, for example + +```python +from TiMBA.main import run_timba + +run_timba() +``` + +To change the folder for input and output data, the user can use the `folderpath` option (note: the path must be a `Path` object from `pathlib`): + +```python +from TiMBA.main import run_timba +from pathlib import Path + +run_timba(folderpath=Path(r"your_path")) +``` + +To modify specific parameters, you can import `parameter_setter` from `TiMBA.main` and set new values: + +```python +from TiMBA.main import run_timba, parameter_setter + +parameters = parameter_setter() +parameters.max_period = 2 + +run_timba(Parameters=parameters) ### 2.1. PyPI package ```bash From e26dbc94a5c61aa3daccbc7ea2ebf74c8bcc7e26 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:11:03 +0200 Subject: [PATCH 06/19] add Troubleshooting: command not found --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index c83e43f..85f596e 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,32 @@ uv tool install -p 3.11 pytimba ``` You will then have access to the CLI command `timba` with the subcommands `carbon`, `dashboard`, `load` ans `run`. Get an overview with `timba --help`. Detailed usage instructions are available with the argument `--help` for each of the subcommands. See section [Model settings](#model-settings) for further details. +#### 2.3.1 Troubleshooting: `uv` command not found + +If you encounter the following error message: + +``` +'uv' is not recognized as an internal or external command, +operable program or batch file. +``` + +`uv` may be installed successfully, but the installation directory is not available in your `PATH`. + +Check the installation output for the line: + +``` +installing to +``` + +Add this path to your environment variable `PATH`, e.g. und Windows like so: + +```cmd +set PATH=%PATH%; +``` + +For a permanent solution, add `` to your user `PATH` environment variable in Windows. + + ### 2.4 Install TiMBA from PyPi If you want to use TiMBA as part of your own program, you can install it from PyPi like so: From 16818e82de6b54bee894a8bdfba19528305c66b0 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:18:45 +0200 Subject: [PATCH 07/19] fix markup --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 85f596e..3d7c03a 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,8 @@ parameters = parameter_setter() parameters.max_period = 2 run_timba(Parameters=parameters) +``` + ### 2.1. PyPI package ```bash From 5e08c143886e3410dd21f97643226c994bd32485 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:21:15 +0200 Subject: [PATCH 08/19] add installation from GitHub --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 3d7c03a..e999a2d 100644 --- a/README.md +++ b/README.md @@ -175,6 +175,26 @@ parameters.max_period = 2 run_timba(Parameters=parameters) ``` +### 2.5 Install TiMBA from GitHub + +To install TiMBA in editable mode, so that you can modify the TiMBA source code, install it directly from GitHub: + +1. Clone the repository and move into the project folder: + ```bash + git clone https://github.com/TI-Forest-Sector-Modelling/TiMBA.git timba + cd timba + ``` +2. Create the virtual environment and install all dependencies into it: + ```bash + uv sync + ``` +3. Verify the installation and run a first period: + ```bash + uv run run_timba --help + uv run run_timba -MP=1 + ``` + + ### 2.1. PyPI package ```bash From 80eef26e8b985ee00e18a297c2f85733b07a1013 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:29:15 +0200 Subject: [PATCH 09/19] add Install from GitHub without uv --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/README.md b/README.md index e999a2d..8e95c89 100644 --- a/README.md +++ b/README.md @@ -193,7 +193,41 @@ To install TiMBA in editable mode, so that you can modify the TiMBA source code, uv run run_timba --help uv run run_timba -MP=1 ``` +### 2.5.1 Install from GitHub without 'uv` +If you want to develop without using `uv`, you can install TiMBA with `venv` and `pip`, for example for Windows like so: + +The prerequistite is, that the version of you system-Python is supported (3.9 - 3.11). + +1. Clone the repository and move into the project folder: + ```bash + git clone https://github.com/TI-Forest-Sector-Modelling/TiMBA.git timba + cd timba +``` + +2. Create a virtual environment + + Select the correct Python interpreter. + Show installed versions: + >py -0 + > + - If you have installed multiple versions of Python, activate the correct version using the py-Launcher. + >py -3.11 -m venv venv + > + - If you are using only a single version of Python on your computer: + >python -m venv venv + > +3. Activate the virtual environment +Enable the virtual environment to isolate TiMBA dependencies. + >venv\Scripts\activate + +4. Install TiMBA in the editable mode + >pip install -e . + + If the following error occurs: "ERROR: File "setup.py" or "setup.cfg" not found." + you might need to update the pip version you use with: + >python.exe -m pip install --upgrade pip + ### 2.1. PyPI package From 40dd5fb43bfaeec0297cd1411df7585a131b5dea Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:37:38 +0200 Subject: [PATCH 10/19] replace run_timba in places, add prerequisites for uv-less Windows install --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8e95c89..145025c 100644 --- a/README.md +++ b/README.md @@ -190,14 +190,17 @@ To install TiMBA in editable mode, so that you can modify the TiMBA source code, ``` 3. Verify the installation and run a first period: ```bash - uv run run_timba --help - uv run run_timba -MP=1 + uv run timba run --help + uv run timba run -MP=1 ``` ### 2.5.1 Install from GitHub without 'uv` If you want to develop without using `uv`, you can install TiMBA with `venv` and `pip`, for example for Windows like so: -The prerequistite is, that the version of you system-Python is supported (3.9 - 3.11). +The prerequistite is that a supported version (9.9 -3.11) is among your +system-wide installed Python interpreters and that you have [Python Launcher for +Windows](https://github.com/oleksis/pylauncher/blob/master/docs/launcher.rst) +installed. 1. Clone the repository and move into the project folder: ```bash From 12506f8523dfb685ba1234dec935babe36a023fe Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:38:46 +0200 Subject: [PATCH 11/19] remove stuff altready covered --- README.md | 89 ------------------------------------------------------- 1 file changed, 89 deletions(-) diff --git a/README.md b/README.md index 145025c..684aa9c 100644 --- a/README.md +++ b/README.md @@ -232,95 +232,6 @@ Enable the virtual environment to isolate TiMBA dependencies. >python.exe -m pip install --upgrade pip -### 2.1. PyPI package - -```bash -pip install pytimba -```` - -Once installed, `timba` can be imported with standard settings: - -```python -from timba.main import run_timba - -run_timba() -``` - -To change the folder for input and output data, the user can use the `folderpath` option (note: the path must be a `Path` object from `pathlib`): - -```python -from timba.main import run_timba -from pathlib import Path - -run_timba(folderpath=Path(r"your_path")) -``` - -To modify specific parameters, the user can import `parameter_setter` from `TiMBA.main` and set new values: - -```python -from timba.main import run_timba, parameter_setter - -parameters = parameter_setter() -parameters.max_period = 2 - -run_timba(Parameters=parameters) -``` - -### 2.2. GitHub repository - -1. Clone the repository -Begin by cloning the repository to your local machine using the following command: - >git clone https://github.com/TI-Forest-Sector-Modelling/TiMBA.git - > -2. Switch to the TiMBA directory -Navigate into the TiMBA project folder on your local machine. - >cd TiMBA - > -3. Create a virtual environment -It is recommended to set up a virtual environment for TiMBA to manage dependencies. The package is tested for - Python versions up to 3.11. With a newer Python version, we can not guarantee the full functionality of the package. - Select the correct Python interpreter. - Show installed versions: - >py -0 - > - - If you have installed multiple versions of Python, activate the correct version using the py-Launcher. - >py -3.11 -m venv venv - > - - If you are using only a single version of Python on your computer: - >python -m venv venv - > -4. Activate the virtual environment -Enable the virtual environment to isolate TiMBA dependencies. - >venv\Scripts\activate - - Or for Linux: - >source venv/bin/activate - -5. Install TiMBA in the editable mode - >pip install -e . - - If the following error occurs: "ERROR: File "setup.py" or "setup.cfg" not found." - you might need to update the pip version you use with: - >python.exe -m pip install --upgrade pip - - -***Double check installation and test suite***: -Double check if installation was successful by running following command from terminal: - >timba --help - -The help provides you information about the basic model commands. - -The TiMBA model comes with a test suite to ensure its functionality. -Run the test suite to check the functionality of the package and validate the produced results with those provided by the -TI-FSM using the coverage report: - - > coverage run - -To reduce the test suite running time, only the first period will be computed and compared. The test suite results will not be saved. -The computed results and provided validation results are compared with a relative tolerance of 5%. - -The coverage report of the TiMBA model can be accessed using: - > coverage report ## 3. Use TiMBA From 2a0eb2f5c4ddc147f32f262f51c5c7168dfda0ae Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:40:21 +0200 Subject: [PATCH 12/19] add testing Timba --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 684aa9c..768bd11 100644 --- a/README.md +++ b/README.md @@ -193,7 +193,7 @@ To install TiMBA in editable mode, so that you can modify the TiMBA source code, uv run timba run --help uv run timba run -MP=1 ``` -### 2.5.1 Install from GitHub without 'uv` +#### 2.5.1 Install from GitHub without 'uv` If you want to develop without using `uv`, you can install TiMBA with `venv` and `pip`, for example for Windows like so: @@ -231,7 +231,20 @@ Enable the virtual environment to isolate TiMBA dependencies. you might need to update the pip version you use with: >python.exe -m pip install --upgrade pip +### 3. Testing TiMBA +The TiMBA model comes with a test suite to ensure its functionality. Run the +test suite to check the functionality of the package and validate the produced +results with those provided by the TI-FSM using the coverage report: + + ```bash + uv run python -W ignore::DeprecationWarning -m coverage run --rcfile=.coveragerc -m unittest discover + uv run coverage report + ``` + +To reduce the test suite running time, only the first period will be computed +and compared. The test suite results will not be saved. The computed results and +provided validation results are compared with a relative tolerance of 5%. ## 3. Use TiMBA From 20f54d35a5ec30ae96bff1e8f9c123e1671c93e1 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:43:50 +0200 Subject: [PATCH 13/19] update use TiMBA --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 768bd11..6659d09 100644 --- a/README.md +++ b/README.md @@ -246,8 +246,7 @@ To reduce the test suite running time, only the first period will be computed and compared. The test suite results will not be saved. The computed results and provided validation results are compared with a relative tolerance of 5%. - -## 3. Use TiMBA +## 4. Use TiMBA TiMBA provides a built-in command-line interface (CLI) that enables users to download input data, execute simulations, and analyse model outputs. @@ -296,6 +295,7 @@ To verify that the installation is working correctly, execute a simulation for t timba run -MP 1 ``` + ## 4. Supplementary modules The TiMBA ecosystem has a modular design. Each module extends the base functionality of TiMBA in a specific way. @@ -453,7 +453,7 @@ In its basic version, TiMBA uses the assumptions made in the “Middle of the ro Price and income elasticities of demand are taken from Morland et al. (2018). Further exogenous specifications on technology developments (input-output coefficients and manufacturing cost) are estimated based historical developments from 1993-2020. Information on trade inertia are based on WTO data as provided in the GFPM (Buongiorno et al. 2015; GFPM version 1-29-2017-World500) while data on WTO Ad-valorem taxes rates were recalculated by the authors as described in Schier et al. (2026). The base year for the scenario simulations with the current version of TiMBA is 2020. -The input data used for simulation with TiMBA needs to be calibrated and provided in a source file prior to model runs. This file is provided together with the model (`scenario_input.xlsx`) as described in [3. Use TiMBA](#3-use-timba). +The input data used for simulation with TiMBA needs to be calibrated and provided in a source file prior to model runs. This file is provided together with the model (`scenario_input.xlsx`) as described in [4. Use TiMBA](#4-use-timba). The model input data calibration procedure is described in Buongiorno and Zhu (2015) and altered according to Schier et al. (2018). The input data for calibrating the model are obtained from three global databases: The FAO forestry statistics (FAOSTAT), the FAO Forest Global Resources Assessment (FAO 2020) and the World Bank Development Indicators (World Bank). The model output comprises information about production, consumption and trade quantities, and prices as well as forest development. The model concept bases on the formal description of the Global Forest Products Model (GFPM) (Buongiorno et al. 2015, Buongiorno et al. 2003). From 78b2879e42493c2d5d8713299de4863592ddd018 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:50:18 +0200 Subject: [PATCH 14/19] update the rest --- README.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 143 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6659d09..ae61ffc 100644 --- a/README.md +++ b/README.md @@ -294,9 +294,7 @@ To verify that the installation is working correctly, execute a simulation for t ```bash timba run -MP 1 ``` - - -## 4. Supplementary modules +## 5. Supplementary modules The TiMBA ecosystem has a modular design. Each module extends the base functionality of TiMBA in a specific way. TiMBA includes support for **[TiMBA Charts](https://doi.org/10.5281/zenodo.20925292)**, an interactive dashboard for exploring simulation results. @@ -325,7 +323,7 @@ timba carbon This module estimates carbon stocks in forest biomass, forest soils, deadwood, litter, harvested wood products, and substitution effects based on TiMBA simulation results and historical statistics on forest resources and forest product markets ([Honkomp 2026](https://www.sciencedirect.com/science/article/pii/S2352711026000828#abs0001)). -## 5. Project structure +## 6. Project structure After downloading the input data (`timba load`), the project directory is organised as follows: @@ -379,12 +377,21 @@ Each model run creates a new set of output files using timestamp-based filenames results_D20260708T14-32-18.csv ``` -This guarantees that previous simulation results remain available for comparison and documentation. +**Important output information** +No output file will ever be overwritten by the application itself. New +results-files will be generated in the format +`results_DT.csv` and will be saved to the output folder as +well. The logfile itself won't be overwritten as well but also no new file +created on additional runs. Log information simply gets appended to the existing +logfile. Removing the logfile ahead of executing the model won't result in +errors. -## 6. Model settings +## 7. Model settings Multiple settings are integrated for the ***timba run*** command to allow users to interact with the model and adapt the modelling parameters to their research interests. -The following chapter provides a brief overview of the model settings. A detailed description of the settings is provided in the model documentation (TI-FSM 2025). +The following chapter provides a brief overview of the model settings. A detailed description of the settings is provided in the model documentation ([TI-FSM 2025](https://literatur.thuenen.de/digbib_extern/dn069603.pdf)). + +This guarantees that previous simulation results remain available for comparison and documentation. Basic model settings include: @@ -414,19 +421,19 @@ Basic add-on module settings include (see [add-on modules for TiMBA](#add-on-mod TiMBA is delivered with a validated set of default settings that were tested for stability and consistency. These default parameters can be modified when executing the package via CLI or directly in `default_parameters.py`. Please note that any parameters specified in the CLI will overwrite those defined in `default_parameters.py`. Not all combinations of functionalities and settings have been tested or validated. In particular, shadow and calculated price modes for country- and product-level (PP) and world (WP) prices must be applied consistently. Mixing the two (e.g., PP="calculated_PP" and WP="shadow_WP") is currently not supported and may result in an error. -### 6.1. Settings as parameters +### 7.1. Settings as parameters The CLI provides access to basic model settings and their default values. Check if CLI command is registered and available on your computer by executing: - >timba run --help Default settings can be changed in the following way: (Note that the change of default settings as described below is for demonstration purposes only, and the results have not been validated.): + - > timba run -MP=5 -MB="RCG_specific" -CP="True" - For this example, TiMBA will simulate 5 periods using calculated prices as product prices and shadow prices as world market prices. -### 6.2. Advanced settings +### 7.2. Advanced settings In addition to the settings accessible via the CLI, users can control advanced settings through changes in `Defines.py` Advance settings include: - solver settings (like accuracy, number of iterations and penalties) @@ -436,7 +443,7 @@ Advance settings include: Some setting combinations might not be coherent and can lead to errors in the simulations or to unreliable results. Those combinations have neither been tested nor validated. Note: TiMBA was tested with a pre-defined number of periods and respective periods' lenght. If the number of periods is changed, it is necessary to compare and adjust this in the ExogChange sheet in the input file. -## 7. TiMBA extended model description +## 8. TiMBA extended model description TiMBA is a partial economic equilibrium model for the global forest products market. The market equilibrium is subject to market clearance and constraints balancing necessary raw materials and produced wood products and limiting the trade (Samuelson 1952). The model structure distinguishes between raw, intermediate and end products. TiMBA differentiates three types of roundwood @@ -453,12 +460,12 @@ In its basic version, TiMBA uses the assumptions made in the “Middle of the ro Price and income elasticities of demand are taken from Morland et al. (2018). Further exogenous specifications on technology developments (input-output coefficients and manufacturing cost) are estimated based historical developments from 1993-2020. Information on trade inertia are based on WTO data as provided in the GFPM (Buongiorno et al. 2015; GFPM version 1-29-2017-World500) while data on WTO Ad-valorem taxes rates were recalculated by the authors as described in Schier et al. (2026). The base year for the scenario simulations with the current version of TiMBA is 2020. -The input data used for simulation with TiMBA needs to be calibrated and provided in a source file prior to model runs. This file is provided together with the model (`scenario_input.xlsx`) as described in [4. Use TiMBA](#4-use-timba). +The input data used for simulation with TiMBA needs to be calibrated and provided in a source file prior to model runs. This file is provided together with the model (`scenario_input.xlsx`) as described in [3. Use TiMBA](#3-use-timba). The model input data calibration procedure is described in Buongiorno and Zhu (2015) and altered according to Schier et al. (2018). The input data for calibrating the model are obtained from three global databases: The FAO forestry statistics (FAOSTAT), the FAO Forest Global Resources Assessment (FAO 2020) and the World Bank Development Indicators (World Bank). The model output comprises information about production, consumption and trade quantities, and prices as well as forest development. The model concept bases on the formal description of the Global Forest Products Model (GFPM) (Buongiorno et al. 2015, Buongiorno et al. 2003). -## 8. Supplementary modules for TiMBA +## 9. Supplementary modules for TiMBA TiMBA is designed as a modular modelling framework that can be extended with additional applications to enable further functionalities. Depending on the use case and the research question, users can activate or deactivate these modular extensions via the CLI or through the `default_parameters`. In this way, the computational load is tailored to the user's needs. The modules are designed @@ -476,7 +483,7 @@ users should refer the respective GitHub repositories. | Carbon Module | tracks carbon stocks and stock changes across pools in the forestry sector including aboveground and belowground biomass, forest soils, deadwood and litter, and harvested wood products. The module applies updated guidelines of the IPCC (2019). A visualization dashbord for carbon results is generated automatically. | `activate_cmodule=True` in `default_parameters.py`
or
`-C=True` in the CLI | [C-Module](https://github.com/TI-Forest-Sector-Modelling/C-Module) | [Honkomp (2025)](https://zenodo.org/records/16912178) | | TiMBA Charts | an analysis toolbox with multiple dashboards about the main TiMBA results | `timba run -SD True` to open the toolbox directly after simulation has ended, or `timba dashboard` to open the toolbox indepently from a specific TiMBA run | [TiMBA Charts](https://github.com/TI-Forest-Sector-Modelling/TiMBA_Charts) | [Morland, C., Tandetzki, J., & Honkomp, T. (2026)](https://doi.org/10.5281/zenodo.20925292) | -## 9. Roadmap and project status +## 10. Roadmap and project status The development of TiMBA is ongoing and we are already working on future releases. @@ -491,17 +498,125 @@ Several projects are currently extending different components of TiMBA: Frequently check [TiMBA repository](https://github.com/TI-Forest-Sector-Modelling/TiMBA) for new releases. -## 10. Contributing to the project -We welcome contributions, additions, and suggestion to further develop or improve the code and the model. To check, discuss and include them into this project, we would like you to share your ideas with us so that we can agree on the requirements needed for accepting your contribution. +## 11. FAIR research software + +We attempt to adhere as much as possible to the FAIR Principles for research +software (e.g. see Barker et al. 2022 and Chue Hong et al. 2022) and reach high +standards of scientific quality and openness. If you find that TiMBA or its documentation could be improved, we would greatly appreciate your feedback. +Please submit it as an [Issue](https://github.com/TI-Forest-Sector-Modelling/TiMBA/issues/new/choose) +in the GitHub repository or via email to [wf-timba@thuenen.de](mailto:wf-timba@thuenen.de). + +In the following we detail our efforts and considerations. + +### 11.1 Findable + +- Zenodo provides a DOI with extensive metadata according to the DataCite schema. + - Separate DOIs for each release and one representing all releases. +- A set of SWHID (Software Hash IDentifiers) is created by the [Software + Heritage archive](https://archive.softwareheritage.org/) for each release and + refereneces the code in a very granular fashion. +- An accompanying [software paper](https://doi.org/10.21105/joss.08034) makes + sure the software is also referenced in search indices that focus on journal articles. +- We provide rich metadata also as linked data in the form of the file `codemeta.json` in the + [CodeMeta](https://codemeta.github.io/) standard. +- We provide machine-actionable citation information in the [Citation File Format + (CFF)](https://citation-file-format.github.io/). + +### 11.2 Accessible + +- The source code can be accessed in the form of a *git remote* from GitHub, via + *http* from Zenodo, but also by Python package managers through the [Python + Package Index](https://pypi.org/), both as source distribution and as a + *Wheel*. + +- Metadata is preserved to a very high degree of safety in a redundant fashion. + The DataCite type metadata not only preserved by DataCite but also by Zenodo + and in the form of a file `zenodo.json` on GitHub and in the SoftwareHeritage + datacenters. These three repositories also hold the file `codemeta.json`. + +- We recognize that GitHub, a commercial platform owned by Microsoft, is subject +to business and strategic considerations that may raise concerns regarding data +governance, security, adherence to scientific community standards, and long-term +sustainability. Nevertheless, GitHub's seamless integration with Zenodo provides +substantial benefits, including automated archiving and DOI assignment, which would +be difficult to achieve with our current resources. We hope that a comparable integration +will be developed in the future for better suited Forges such as [Forgejo](https://forgejo.org/) or + self-hosted [GitLab](gitlab.com). + +### 11.3 Interoperable + +#### 11.3.1 Software interoperability + +- TiMBA installs both as executable script (`timba_run`) as well as as a Python + module (`TiMBA`). The script copies its output also to STDOUT and allows to + chain TiMBA with other command line tools in a classical UNIX fashion. + Importing the module allows users to integrate TiMBA into their own Python + programs. + +- We also maintain extensions to TiMBA ([Carbon + Module](https://github.com/TI-Forest-Sector-Modelling/C-Module) and [TiMBA + Charts](https://github.com/TI-Forest-Sector-Modelling/TiMBA_Charts)) in the + form of Python packages that can be used by importing them. These packages + also adhere to FAIR principles, are version-controlled in GitHub and can be + referenced with DOIs registered by Zenodo. + +#### 11.3.2 Data interoperability + +- TiMBA relies on a set of required input data. The canonical versions of these + data (a non-trivial scientific output) are also kept [version controlled in + GitHub](https://github.com/TI-Forest-Sector-Modelling/TiMBA_Additional_Information) + and releases are [published to + Zenodo](https://doi.org/10.5281/zenodo.14928910). + +- The main input data file is Office Open XML ("Microsoft Excel") format. We are + aware that this format is not a good choice from a purely technical point of + view and has severe shortcomings with regard to robustness, stability over + time, machine readability, interoperability, platform independence and + accessibility. However, this is the optimal format to make the input + understandable and modifyable by our main target group, who understands + Microsoft Excel very well but might struggle with less common formats and + conventions. This is a cultural and educational problem we can't solve in this + context. We are familiar with and track projects such as [Frictionnless + Data](https://frictionlessdata.io/) with its [Data Package + standard](https://datapackage.org/). We hope to eventually be able to combine + user-friendliness with robust data standards to represent our input data. + +- TiMBA output is written to universally readable CSV-files. We plan to describe + these files with standardized metadata in the future. + +### 11.4 Reusable + +- TiMBA has dependencies and sub-dependencies which are extensively recorded in + the `uv.lock` file to ensure reproducibility. +- We continually strife to keep and improve software quality. We utilize + automated CI processes (testing for different platforms, linting) in the form + of GitHub workflows. +- We have licensed the software under the [GNU Affero General Public + License](https://www.gnu.org/licenses/agpl-3.0.txt). On the one hand side this + license is most compatible with the potential need to In-license further + dependencies. On the other hand, as a *Copyleft* license, it is very well + suited to support Open Science, reproducibility and transparency (von Waldow, + 2024). +- The scientific background and in particular prior software on which this work + improves, is extensively documented and referenced in this README file. +- Python as a programming language, adherence to an improved + ([`ruff`](https://docs.astral.sh/ruff/)-defaults) PEP8 style guide, + user-friendly formatting of input data, and instructions about how to + contribute increase the chances that this software is being reused in our + research community. + + +## 12. Contributing to the project +We welcome contributions, additions and suggestion to further develop or improve the code and the model. To check, discuss and include them into this project, we would like you to share your ideas with us so that we can agree on the requirements needed for accepting your contribution. + You can contact us directly via GitHub by creating issues, or by writing an Email to: [wf-timba@thuenen.de](mailto:wf-timba@thuenen.de) -So far, this README serves as a comprehensive introduction and guidance on how to get started. ´The model documentation (TI-FSM 2025) and model validation (TI-FSM 2026) enables a deeper dive. +So far, this README serves as a comprehensive introduction and guidance on how to get started. ´The model documentation ([TI-FSM 2025](https://literatur.thuenen.de/digbib_extern/dn069603.pdf)) and model validation ([TI-FSM 2026](https://literatur.thuenen.de/digbib_extern/dn070984.pdf)) enables a deeper dive. - -## 11. Authors +## 13. Authors TiMBA was developed and written by an authors' collective named Thünen Institute Forest Sector Modelling (TI-FSM). The individual authors are listed in alphabetical order @@ -510,7 +625,7 @@ The individual authors are listed in alphabetical order - [Julia Tandetzki](https://www.thuenen.de/de/fachinstitute/waldwirtschaft/personal/wissenschaftliches-personal/julia-tandetzki-msc) [(ORCID 0000-0002-0630-9434)](https://orcid.org/0000-0002-0630-9434), and - [Tomke Honkomp](https://www.thuenen.de/de/fachinstitute/waldwirtschaft/personal/wissenschaftliches-personal/tomke-honkomp-msc) [(ORCID 0000-0002-6719-0190)](https://orcid.org/0000-0002-6719-0190). -## 12. Contribution statement +## 14. Contribution statement Within the authors' collective TI-FSM, the authors have contributed over years their individual strengths and knowledge to make the model work: | Author | Conceptualization and theoretical framework | Methodology | Data Curation and Management | Formal Analysis | Programming | Writing and Documentation | Visualization | Review and Editing | Supervision | @@ -520,7 +635,7 @@ Within the authors' collective TI-FSM, the authors have contributed over years t | Julia Tandetzki | X | X | X | X | X | X | X | X | | | Tomke Honkomp | X | X | X | X | X | X | X | X | | -## 13. License and copyright note +## 15. License and copyright note Licensed under the GNU AGPL, Version 3.0. @@ -542,7 +657,7 @@ Copyright ©, 2024, Thuenen Institute, TI-FSM, wf-timba@thuenen.de -## 14. Acknowledgements +## 16. Acknowledgements This work is the result of great joint efforts of the forest products market analysis team at the Thünen Institute of Forestry and others from 2018 to 2024. In the last years, many people made important contributions to this work. Without their support, reflection, and constructive criticism, this undertaking would not have been as successful as it turns out to be now. We would like express our gratitude to all of them. In particular, we would like to thank - Pixida GmbH and especially Tobias Hierlmeier for professional support in revising and restructuring the model architecture and code and being valuable help in programming tasks @@ -552,11 +667,13 @@ This work is the result of great joint efforts of the forest products market ana - The Thünen Institut of Forestry and its Head Matthias Dieter for providing financial resources over the years - [makeareadme.com](https://www.makeareadme.com/) for providing the template this README is leaned on. -## 15. References +## 17. References +- Barker, M., Chue Hong, N.P., Katz, D.S. et al. Introducing the FAIR Principles for research software. Sci Data 9, 622 (2022). https://doi.org/10.1038/s41597-022-01710-x - Buongiorno, J.; Zhu, S.; Zhang, D.; Turner, J.; Tomberlin, D. The Global Forest Products Model; Academic Press: Cambridge, MA, USA, 2003; ISBN 978-0-12-141362-0 - Buongiorno, J. Global modelling to predict timber production and prices: The GFPM approach. Forestry 2015, 88, 291–303. - Buongiorno, J.; and Zhu, S. 2015. Technical change in forest sector models: The GFPM approach. Scand. J. For. Research, 30, 30-48. - GFPM - Global Forest Product Model is available at https://onedrive.live.com/?authkey=%21AEF7RY7oAPlrDPk&id=93BC28B749A1DFB6%21118&cid=93BC28B749A1DFB6 +- Chue Hong, N.P. et al. (2022) “FAIR Principles for Research Software (FAIR4RS Principles)”. Zenodo. Available at: https://doi.org/10.15497/RDA00068. - FAO. Global Forest Resources Assessment: Terms and Definitions; Forest Resources Assessment Working Paper 188; FAO: Rome, Italia, 2020; Available online: http://www.fao.org/3/I8661EN/i8661en.pdf - FAO. Global Forest Resources Assessment. 2022. Available online: https://fra-data.fao.org/ - FAOSTAT. Forestry Production and Trade: Datenbank. Available online: https://www.fao.org/faostat/en/#data/FO @@ -568,5 +685,8 @@ This work is the result of great joint efforts of the forest products market ana - Samuelson, Paul A. Spatial Price Equilibrium and Linear Programming; The American Economic Review, 1952, 42 (3), 283–303; Available online http://www.jstor.org/stable/1810381. - Schier, F.; Morland, C.; Tandetzki, J.; Honkomp, T. (2026). TI-Forest-Sector-Modelling/TiMBA_Additional_Information: Reworking data files and licenses (Version v1.0.2). Zenodo. https://doi.org/10.5281/zenodo.19466845 - TI-FSM (2025) TiMBA - Timber market Model for policy-Based Analysis: Documentation of model structure, data, and parameters. Braunschweig: Johann Heinrich von Thünen-Institut, 35 p, Thünen Working Paper 263, DOI:10.3220/253-2025-16 +- von Waldow, H. (2024). Research Software Licensing Guide (Version v1.0.2). Zenodo. https://doi.org/10.5281/zenodo.14008091 - TI-FSM (2026) TiMBA - Timber market Model for policy-Based Analysis: Validation of a partial equilibrium model. Braunschweig: Johann Heinrich von Thünen-Institut, 36 p, Thünen Working Paper 282, DOI:10.3220/253-2026-29 - World Bank. World Development Indicators|DataBank. Available online: https://databank.worldbank.org/source/world-development-indicators + + From 17aaf5c673ce494e324edc1b1e0002ba44cc7be0 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Thu, 16 Jul 2026 18:55:28 +0200 Subject: [PATCH 15/19] fix TOC and redundand high-level description --- README.md | 54 +++++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index ae61ffc..1ee5c59 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ [![DOI](https://joss.theoj.org/papers/10.21105/joss.08034/status.svg)](https://doi.org/10.21105/joss.08034) [![License](https://img.shields.io/github/license/TI-Forest-Sector-Modelling/TiMBA?style=flat)](https://github.com/TI-Forest-Sector-Modelling/TiMBA/blob/main/COPYING) ------------------ +----------------- **TiMBA** is a partial economic equilibrium model for the global forest products market. The model endogenously simulates production, consumption, and trade of wood and wood-based products in 180 countries. TiMBA recursively computes the market @@ -25,34 +25,34 @@ In the equilibrium processes, product supply, demand and price are balanced for - [TiMBA - Timber market Model for policy-Based Analysis](#timba---timber-market-model-for-policy-based-analysis) - [1. Cite TiMBA](#1-cite-timba) - [2. Installation](#2-installation) - - [2.1. PyPI package](#21-pypi-package) - - [2.2. GitHub repository](#22-github-repository) - - [3. Use TiMBA](#3-use-timba) - - [4. Model extensions](#4-model-extensions) - - [5. Project structure](#5-project-structure) - - [6. Model settings](#6-model-settings) - - [6.1. Settings as parameters](#61-settings-as-parameters) - - [6.2. Advanced settings](#62-advanced-settings) - - [7. TiMBA extended model description](#7-timba-extended-model-description) - - [8. Extensions for TiMBA](#8-extensions-for-timba) - - [9. Roadmap and project status](#9-roadmap-and-project-status) - - [10. Contributing to the project](#10-contributing-to-the-project) - - [11. Authors](#11-authors) - - [12. Contribution statement](#12-contribution-statement) - - [13. License and copyright note](#13-license-and-copyright-note) - - [14. Acknowledgements](#14-acknowledgements) - - [15. References](#15-references) - - + - [2.1 Requirements](#21-requirements) + - [2.2 Install uv](#22-install-uv) + - [2.3 Install the TiMBA command line programs](#23-install-the-timba-command-line-programs) + - [2.4 Install TiMBA from PyPi](#24-install-timba-from-pypi) + - [2.5 Install TiMBA from GitHub](#25-install-timba-from-github) + - [3. Testing TiMBA](#3-testing-timba) + - [4. Use TiMBA](#4-use-timba) + - [5. Supplementary modules](#5-supplementary-modules) + - [6. Project structure](#6-project-structure) + - [7. Model settings](#7-model-settings) + - [7.1. Settings as parameters](#71-settings-as-parameters) + - [7.2. Advanced settings](#72-advanced-settings) + - [8. TiMBA extended model description](#8-timba-extended-model-description) + - [9. Supplementary modules for TiMBA](#9-supplementary-modules-for-timba) + - [10. Roadmap and project status](#10-roadmap-and-project-status) + - [11. FAIR research software](#11-fair-research-software) + - [11.1 Findable](#111-findable) + - [11.2 Accessible](#112-accessible) + - [11.3 Interoperable](#113-interoperable) + - [11.4 Reusable](#114-reusable) + - [12. Contributing to the project](#12-contributing-to-the-project) + - [13. Authors](#13-authors) + - [14. Contribution statement](#14-contribution-statement) + - [15. License and copyright note](#15-license-and-copyright-note) + - [16. Acknowledgements](#16-acknowledgements) + - [17. References](#17-references) ----------------- -**TiMBA** is a partial economic equilibrium model for the global forest products -market. The model endogenously simulates production, consumption and trade of -wood and wood-based products in 180 countries. TiMBA recursively computes the -market equilibrium for each country and product in a given period by maximizing -the social surplus in the global forest sector. In the equilibrium processes, -product supply, demand and price are balanced for each simulation period. - ## 1. Cite TiMBA We are happy that you use TiMBA for your research. When publishing your work in articles, working paper, presentations From b4424290c84205a632a4544fafe54ef6ca0e7e26 Mon Sep 17 00:00:00 2001 From: Christian Morland Date: Fri, 17 Jul 2026 08:22:40 +0200 Subject: [PATCH 16/19] check README for typos and formatting issue. --- README.md | 81 +++++++++++++++++++++++-------------------------------- 1 file changed, 34 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 1ee5c59..25b26c7 100644 --- a/README.md +++ b/README.md @@ -76,9 +76,9 @@ system images](https://github.com/actions/runner-images#available-images) - Operating system: Linux or Windows on a x64 architecture. We test Windows 11 and Ubuntu 24.04, but other Windows and Linux versions are likely to work too. -- The Python package manager [uv](https://docs.astral.sh/uv/). We strongly - recommend to use `uv`, because it provides a very user-friendly, quick, - platform-independent and reliable way to install, use and develop TiMBA. +- The Python package manager [uv](https://docs.astral.sh/uv/). We recommend to + use `uv`, because it provides a user-friendly, quick, platform-independent + and reliable way to install, use and develop TiMBA. That said, TiMBA can be also installed classically by creating a virtual environment using [`venv`](https://docs.python.org/3.14/library/venv.html) and @@ -89,7 +89,10 @@ operating system level and create the virtual environment with that version, e.g. `python3.11 -m venv .venv`. ***Known Issues***: -TiMBA currently does not work with Python 3.12 or higher. We observe numerical discrepancies (>5% compared to results generated on Windows or Linux) when running TiMBA on macOS which could traced back to the solver OSQP in CVXPY. The results with MacOS have not been validated. We are investigating the issue. +TiMBA currently does not work with Python 3.12 or higher. We observe numerical discrepancies +(>5% compared to results generated on Windows or Linux) when running TiMBA on macOS which +could traced back to the solver OSQP in CVXPY. The results with MacOS have not been validated. +We are investigating the issue. ### 2.2 Install uv @@ -129,7 +132,7 @@ Check the installation output for the line: installing to ``` -Add this path to your environment variable `PATH`, e.g. und Windows like so: +Add this path to your environment variable `PATH`, e.g. on Windows like so: ```cmd set PATH=%PATH%; @@ -238,13 +241,12 @@ test suite to check the functionality of the package and validate the produced results with those provided by the TI-FSM using the coverage report: ```bash - uv run python -W ignore::DeprecationWarning -m coverage run --rcfile=.coveragerc -m unittest discover + uv run python -W ignore::DeprecationWarning -m coverage run --rcfile=.coveragerc -m unittest discover -s test -p "test*.py" uv run coverage report ``` To reduce the test suite running time, only the first period will be computed -and compared. The test suite results will not be saved. The computed results and -provided validation results are compared with a relative tolerance of 5%. +and compared. The test suite results will not be saved. ## 4. Use TiMBA @@ -281,7 +283,7 @@ The available CLI commands are: | `carbon` | Calculate forest carbon stocks in forests and harvested wood products. | | `dashboard` | Launch an interactive dashboard for analysing simulation results. | -By default, TiMBA uses the current working directory for input and output files. A different project directory can be specified using the `-FP` (folder path) option: +By default, TiMBA uses the current working directory also for output files. A different project directory can be specified using the `-FP` (folder path) option: ```bash timba run -FP your_path @@ -289,11 +291,6 @@ timba run -FP your_path This allows users to organise multiple projects or customise model runs with alternative input datasets (see [Model settings](#model-settings) for further details). -To verify that the installation is working correctly, execute a simulation for the first model period only: - -```bash -timba run -MP 1 -``` ## 5. Supplementary modules The TiMBA ecosystem has a modular design. Each module extends the base functionality of TiMBA in a specific way. @@ -348,44 +345,33 @@ After simulation, TiMBA creates an `output` directory inside the `data` folder. ```text data └── output - ├── TiMBA.log - ├── DataContainer_.pkl - ├── results_.csv - ├── worldprices_.csv - ├── forest_.csv - ├── manufacture_.csv - └── results_aggregated_.csv + └── data + ├── DataContainer_.pkl + ├── results_.csv + ├── worldprices_.csv + ├── forest_.csv + ├── manufacture_.csv + └── results_aggregated_.csv + └── logs + ├── TiMBA.log + └── _info.yml ``` The output files contain: -| File | Description | -|--------------------------------------|---------------------------------------------------------------| -| `TiMBA.log` | Log file containing information about the simulation process. | -| `DataContainer_.pkl` | Complete serialized simulation results for programmatic use. | -| `results_.csv` | Main simulation results in csv format. | -| `worldprices_.csv` | World price results in csv format. | -| `forest_.csv` | Forest resources-related results in csv format. | -| `manufacture_.csv` | Manufacturing sector-related results in csv format. | -| `results_aggregated_.csv` | Results aggregated at the continental level in csv format. | +| File | Description | +|------------------------------------------------|----------------------------------------------------------------------------| +| `TiMBA.log` | Log file containing information about the simulation process. | +| `_info.yml` | Records all model input parameters for reproducibility and transparency. | +| `DataContainer_.pkl` | Contains the complete serialized simulation output for efficient reuse. | +| `results_.csv` | Main simulation results in csv format. | +| `worldprices_.csv` | World price results in csv format. | +| `forest_.csv` | Forest resources-related results in csv format. | +| `manufacture_.csv` | Manufacturing sector-related results in csv format. | +| `results_aggregated_.csv` | Results aggregated at the continental level in csv format. | To ensure reproducibility, TiMBA never overwrites existing simulation results. -Each model run creates a new set of output files using timestamp-based filenames, for example: - -```text -results_D20260708T14-32-18.csv -``` - -**Important output information** -No output file will ever be overwritten by the application itself. New -results-files will be generated in the format -`results_DT.csv` and will be saved to the output folder as -well. The logfile itself won't be overwritten as well but also no new file -created on additional runs. Log information simply gets appended to the existing -logfile. Removing the logfile ahead of executing the model won't result in -errors. - ## 7. Model settings Multiple settings are integrated for the ***timba run*** command to allow users to interact with the model and adapt the modelling parameters to their research interests. @@ -581,8 +567,9 @@ will be developed in the future for better suited Forges such as [Forgejo](https standard](https://datapackage.org/). We hope to eventually be able to combine user-friendliness with robust data standards to represent our input data. -- TiMBA output is written to universally readable CSV-files. We plan to describe - these files with standardized metadata in the future. +- TiMBA output is written to universally readable CSV-files, while a serialized PKL file + preserves the complete simulation state for efficient reuse in Python. + We plan to describe these files with standardized metadata in the future. ### 11.4 Reusable From 936e195ecec384654afe0f956a636584c3d27617 Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Fri, 17 Jul 2026 09:47:58 +0200 Subject: [PATCH 17/19] add zenodo.json --- zenodo.json | 514 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 514 insertions(+) create mode 100644 zenodo.json diff --git a/zenodo.json b/zenodo.json new file mode 100644 index 0000000..94953a5 --- /dev/null +++ b/zenodo.json @@ -0,0 +1,514 @@ +{ + "access": { + "embargo": { + "active": false, + "reason": null + }, + "files": "public", + "record": "public", + "status": "open" + }, + "created": "2025-12-03T17:06:07.427226+00:00", + "custom_fields": { + "code:codeRepository": "https://github.com/TI-Forest-Sector-Modelling/TiMBA", + "code:developmentStatus": { + "id": "active", + "title": { + "en": "Active" + } + }, + "code:programmingLanguage": [ + { + "id": "python", + "title": { + "en": "Python" + } + } + ], + "imprint:imprint": { + "place": "Braunschweig, Germany", + "title": "TiMBA - Timber market Model for policy-Based Analysis: Validation of a Partial Equilibrium Model (DOI: 10.3220/253-2026-29)" + }, + "journal:journal": { + "issn": "2475-9066", + "issue": "115", + "pages": "1-5", + "title": "TiMBA (Timber market Model for policy-Based Analysis)", + "volume": "10" + } + }, + "deletion_status": { + "is_deleted": false, + "status": "P" + }, + "files": { + "count": 1, + "enabled": true, + "entries": { + "TI-Forest-Sector-Modelling/TiMBA-v1.3.0.zip": { + "access": { + "hidden": false + }, + "checksum": "md5:0d3e8a0259e2be2e734125bba5713ec8", + "ext": "zip", + "id": "2cffde54-b8c4-4627-bdd2-778909c99ee4", + "key": "TI-Forest-Sector-Modelling/TiMBA-v1.3.0.zip", + "links": { + "container": "https://zenodo.org/api/records/17806030/files/TI-Forest-Sector-Modelling/TiMBA-v1.3.0.zip/container", + "content": "https://zenodo.org/api/records/17806030/files/TI-Forest-Sector-Modelling/TiMBA-v1.3.0.zip/content", + "self": "https://zenodo.org/api/records/17806030/files/TI-Forest-Sector-Modelling/TiMBA-v1.3.0.zip" + }, + "metadata": null, + "mimetype": "application/zip", + "size": 5805385, + "storage_class": "L" + } + }, + "order": [], + "total_bytes": 5805385 + }, + "id": "17806030", + "is_draft": false, + "is_published": true, + "links": { + "access": "https://zenodo.org/api/records/17806030/access", + "access_grants": "https://zenodo.org/api/records/17806030/access/grants", + "access_links": "https://zenodo.org/api/records/17806030/access/links", + "access_request": "https://zenodo.org/api/records/17806030/access/request", + "access_users": "https://zenodo.org/api/records/17806030/access/users", + "archive": "https://zenodo.org/api/records/17806030/files-archive", + "archive_media": "https://zenodo.org/api/records/17806030/media-files-archive", + "communities": "https://zenodo.org/api/records/17806030/communities", + "communities-suggestions": "https://zenodo.org/api/records/17806030/communities-suggestions", + "doi": "https://doi.org/10.5281/zenodo.17806030", + "draft": "https://zenodo.org/api/records/17806030/draft", + "file_modification": "https://zenodo.org/api/records/17806030/file-modification", + "files": "https://zenodo.org/api/records/17806030/files", + "latest": "https://zenodo.org/api/records/17806030/versions/latest", + "latest_html": "https://zenodo.org/records/17806030/latest", + "media_files": "https://zenodo.org/api/records/17806030/media-files", + "parent": "https://zenodo.org/api/records/13842384", + "parent_doi": "https://doi.org/10.5281/zenodo.13842384", + "parent_doi_html": "https://zenodo.org/doi/10.5281/zenodo.13842384", + "parent_html": "https://zenodo.org/records/13842384", + "preview_html": "https://zenodo.org/records/17806030?preview=1", + "quota_increase": "https://zenodo.org/api/records/17806030/quota-increase", + "request_deletion": "https://zenodo.org/api/records/17806030/request-deletion", + "requests": "https://zenodo.org/api/records/17806030/requests", + "reserve_doi": "https://zenodo.org/api/records/17806030/draft/pids/doi", + "self": "https://zenodo.org/api/records/17806030", + "self_doi": "https://doi.org/10.5281/zenodo.17806030", + "self_doi_html": "https://zenodo.org/doi/10.5281/zenodo.17806030", + "self_html": "https://zenodo.org/records/17806030", + "self_iiif_manifest": "https://zenodo.org/api/iiif/record:17806030/manifest", + "self_iiif_sequence": "https://zenodo.org/api/iiif/record:17806030/sequence/default", + "versions": "https://zenodo.org/api/records/17806030/versions" + }, + "media_files": { + "count": 0, + "enabled": false, + "entries": {}, + "order": [], + "total_bytes": 0 + }, + "metadata": { + "additional_descriptions": [ + { + "description": "TiMBA was developed and written by an authors' collective in which the authors have contributed over years their individual strengths and knowledge to make the model work. The authors' collective is named Th\u00fcnen Institute Forest Sector Modelling (TI-FSM). The individual authors are listed as Co-authors in alphabetical order.", + "type": { + "id": "notes", + "title": { + "de": "Anmerkungen", + "en": "Notes" + } + } + } + ], + "copyright": "Copyright (C) 2025 Thuenen Institute, TI-FSM, Christian Morland, Franziska Schier, Julia Tandetzki, Tomke Honkomp", + "creators": [ + { + "person_or_org": { + "family_name": "TI-FSM", + "name": "TI-FSM", + "type": "personal" + } + }, + { + "affiliations": [ + { + "name": "Th\u00fcnen Institue of Forestry" + } + ], + "person_or_org": { + "family_name": "Morland", + "given_name": "Christian", + "identifiers": [ + { + "identifier": "0000-0001-6600-570X", + "scheme": "orcid" + } + ], + "name": "Morland, Christian", + "type": "personal" + } + }, + { + "affiliations": [ + { + "name": "Th\u00fcnen Institue of Forestry" + } + ], + "person_or_org": { + "family_name": "Schier", + "given_name": "Franziska", + "identifiers": [ + { + "identifier": "0000-0002-3378-1371", + "scheme": "orcid" + } + ], + "name": "Schier, Franziska", + "type": "personal" + } + }, + { + "affiliations": [ + { + "name": "Th\u00fcnen Institue of Forestry" + } + ], + "person_or_org": { + "family_name": "Tandetzki", + "given_name": "Julia", + "identifiers": [ + { + "identifier": "0000-0002-0630-9434", + "scheme": "orcid" + } + ], + "name": "Tandetzki, Julia", + "type": "personal" + } + }, + { + "affiliations": [ + { + "name": "Th\u00fcnen Institue of Forestry" + } + ], + "person_or_org": { + "family_name": "Honkomp", + "given_name": "Tomke", + "identifiers": [ + { + "identifier": "0000-0002-6719-0190", + "scheme": "orcid" + } + ], + "name": "Honkomp, Tomke", + "type": "personal" + } + } + ], + "dates": [ + { + "date": "2024-09-26", + "description": "Release first version", + "type": { + "id": "available", + "title": { + "de": "Verf\u00fcgbar", + "en": "Available" + } + } + } + ], + "description": "TiMBA is a partial economic equilibrium model for the\n global forest products market. The model endogenously\n simulates production, consumption and trade of wood and\n wood-based products in 180 countries. TiMBA recursively\n computes the market equilibrium for each country and\n product in a given period by maximizing the social surplus\n in the global forest sector. In the equilibrium processes,\n product supply, demand and price are balanced for each\n simulation period.", + "identifiers": [ + { + "identifier": "https://archive.softwareheritage.org/swh:1:dir:1828c8cf6b8df60176209f7d2f2d8e6f49e68950", + "scheme": "url" + } + ], + "languages": [ + { + "id": "eng", + "title": { + "en": "English" + } + } + ], + "publication_date": "2025-12-03", + "publisher": "Zenodo", + "references": [ + { + "reference": "Buongiorno, J., Zhu, S., Zhang, D., Turner, J., & Tomberlin, D. (2003). The global forest products model: Structure, estimation, and applications. Academic Press. ISBN: 978- 0121413620" + }, + { + "reference": "Buongiorno, J. (2015). Global modelling to predict timber production and prices: The GFPM approach. Forestry, 88(3), 291\u2013303. https://doi.org/10.1093/forestry/cpu047" + }, + { + "reference": "Diamond, S., & Boyd, S. (2016). CVXPY: A Python-embedded modeling language for convex optimization. Journal of Machine Learning Research, 17 (83), 1\u20135." + }, + { + "reference": "Stellato, B., Banjac, G., Goulart, P., Bemporad, A., & Boyd, S. (2020). OSQP: An operator splitting solver for quadratic programs. Mathematical Programming Computation, 12(4), 637\u2013672. https://doi.org/10.1007/s12532-020-00179-2" + }, + { + "reference": "Samuelson, P. A. (1952). Spatial price equilibrium and linear programming. The American Economic Review, 42(3), 283\u2013303. http://www.jstor.org/stable/1810381" + } + ], + "related_identifiers": [ + { + "identifier": "https://github.com/TI-Forest-Sector-Modelling/TiMBA/tree/v1.3.0", + "relation_type": { + "id": "issupplementto", + "title": { + "de": "Erg\u00e4nzt", + "en": "Is supplement to" + } + }, + "resource_type": { + "id": "software", + "title": { + "de": "Software", + "en": "Software" + } + }, + "scheme": "url" + }, + { + "identifier": "10.21105/joss.08034", + "relation_type": { + "id": "ispublishedin", + "title": { + "de": "Ist ver\u00f6ffentlicht in", + "en": "Is published in" + } + }, + "resource_type": { + "id": "publication-article", + "title": { + "de": "Zeitschriftenartikel", + "en": "Journal article" + } + }, + "scheme": "doi" + }, + { + "identifier": "10.5281/zenodo.20925292", + "relation_type": { + "id": "issupplementedby", + "title": { + "de": "Wird erg\u00e4nzt durch", + "en": "Is supplemented by" + } + }, + "resource_type": { + "id": "software", + "title": { + "de": "Software", + "en": "Software" + } + }, + "scheme": "doi" + }, + { + "identifier": "10.5281/zenodo.17814169", + "relation_type": { + "id": "issupplementedby", + "title": { + "de": "Wird erg\u00e4nzt durch", + "en": "Is supplemented by" + } + }, + "resource_type": { + "id": "software", + "title": { + "de": "Software", + "en": "Software" + } + }, + "scheme": "doi" + }, + { + "identifier": "10.5281/zenodo.19466845", + "relation_type": { + "id": "requires", + "title": { + "de": "Setzt voraus", + "en": "Requires" + } + }, + "resource_type": { + "id": "dataset", + "title": { + "de": "Datensatz", + "en": "Dataset" + } + }, + "scheme": "doi" + }, + { + "identifier": "10.5281/zenodo.19466845", + "relation_type": { + "id": "haspart", + "title": { + "de": "Umfasst folgenden Teil", + "en": "Has part" + } + }, + "resource_type": { + "id": "dataset", + "title": { + "de": "Datensatz", + "en": "Dataset" + } + }, + "scheme": "doi" + } + ], + "resource_type": { + "id": "software", + "title": { + "de": "Software", + "en": "Software" + } + }, + "rights": [ + { + "description": { + "en": "" + }, + "id": "agpl-3.0-or-later", + "props": { + "scheme": "spdx", + "url": "https://www.gnu.org/licenses/agpl.txt" + }, + "title": { + "en": "GNU Affero General Public License v3.0 or later" + } + } + ], + "subjects": [ + { + "subject": "research" + }, + { + "subject": "Forest sector model" + }, + { + "subject": "partial equilibrium model" + }, + { + "subject": "optimization" + }, + { + "subject": "wood markets" + } + ], + "title": "TiMBA (Timber market Model for policy-Based Analysis)", + "version": "v1.3.0" + }, + "parent": { + "access": { + "owned_by": { + "user": "1194720" + }, + "settings": { + "accept_conditions_text": null, + "allow_guest_requests": false, + "allow_user_requests": false, + "secret_link_expiration": 0 + } + }, + "communities": { + "default": "09c92e32-50ba-4d88-8c60-9a74a198078d", + "entries": [ + { + "access": { + "member_policy": "open", + "members_visibility": "public", + "record_submission_policy": "open", + "review_policy": "open", + "visibility": "public" + }, + "children": { + "allow": false + }, + "created": "2024-03-26T14:59:31.275326+00:00", + "custom_fields": {}, + "deletion_status": { + "is_deleted": false, + "status": "P" + }, + "id": "09c92e32-50ba-4d88-8c60-9a74a198078d", + "links": {}, + "metadata": { + "curation_policy": "

The Zenodo community of the Thünen-Institut contains exclusively content with contributions of the Thünen-Institut. All other submissions will be rejected.

", + "organizations": [ + { + "id": "00mr84n67" + } + ], + "title": "Johann Heinrich von Th\u00fcnen-Institut", + "type": { + "id": "organization" + }, + "website": "https://www.thuenen.de/de/" + }, + "revision_id": 7, + "slug": "thuenen", + "updated": "2024-03-26T15:18:00.842375+00:00" + } + ], + "ids": [ + "09c92e32-50ba-4d88-8c60-9a74a198078d" + ] + }, + "id": "13842384", + "pids": { + "doi": { + "client": "datacite", + "identifier": "10.5281/zenodo.13842384", + "provider": "datacite" + } + } + }, + "pids": { + "doi": { + "client": "datacite", + "identifier": "10.5281/zenodo.17806030", + "provider": "datacite" + }, + "oai": { + "identifier": "oai:zenodo.org:17806030", + "provider": "oai" + } + }, + "revision_id": 8, + "stats": { + "all_versions": { + "data_volume": 1962166898.0, + "downloads": 225, + "unique_downloads": 216, + "unique_views": 1850, + "views": 2018 + }, + "this_version": { + "data_volume": 249631555.0, + "downloads": 43, + "unique_downloads": 42, + "unique_views": 202, + "views": 216 + } + }, + "status": "published", + "swh": { + "swhid": "swh:1:dir:e6e6240c08c0b70af91ed91083b3e37fce702214;origin=https://doi.org/10.5281/zenodo.13842384;visit=swh:1:snp:2f6aed0842a62a28ae45836d1833807ac77f2a2d;anchor=swh:1:rel:82b8d27a24ca85e5c57a89bcae5b69d8f9bc047f;path=TI-Forest-Sector-Modelling-TiMBA-b659274" + }, + "updated": "2026-07-08T09:23:34.471797+00:00", + "versions": { + "index": 7, + "is_latest": false + } +} \ No newline at end of file From b3d2fd5a8813bf8475b1397c5254cfe016eb9b1b Mon Sep 17 00:00:00 2001 From: Harald von Waldow Date: Fri, 17 Jul 2026 10:47:43 +0200 Subject: [PATCH 18/19] rename zenodo.json --- zenodo.json => .zenodo.json | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename zenodo.json => .zenodo.json (100%) diff --git a/zenodo.json b/.zenodo.json similarity index 100% rename from zenodo.json rename to .zenodo.json From d0f5df632aa2dafb87a389ee9464929d92d70b0a Mon Sep 17 00:00:00 2001 From: Tomke Honkomp <118673759+tomkeH@users.noreply.github.com> Date: Fri, 17 Jul 2026 11:02:57 +0200 Subject: [PATCH 19/19] Corrections in README.md --- README.md | 86 +++++++++++++++++++++++++++---------------------------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 25b26c7..05220e7 100644 --- a/README.md +++ b/README.md @@ -31,26 +31,26 @@ In the equilibrium processes, product supply, demand and price are balanced for - [2.4 Install TiMBA from PyPi](#24-install-timba-from-pypi) - [2.5 Install TiMBA from GitHub](#25-install-timba-from-github) - [3. Testing TiMBA](#3-testing-timba) - - [4. Use TiMBA](#4-use-timba) - - [5. Supplementary modules](#5-supplementary-modules) - - [6. Project structure](#6-project-structure) - - [7. Model settings](#7-model-settings) - - [7.1. Settings as parameters](#71-settings-as-parameters) - - [7.2. Advanced settings](#72-advanced-settings) - - [8. TiMBA extended model description](#8-timba-extended-model-description) - - [9. Supplementary modules for TiMBA](#9-supplementary-modules-for-timba) - - [10. Roadmap and project status](#10-roadmap-and-project-status) - - [11. FAIR research software](#11-fair-research-software) - - [11.1 Findable](#111-findable) - - [11.2 Accessible](#112-accessible) - - [11.3 Interoperable](#113-interoperable) - - [11.4 Reusable](#114-reusable) - - [12. Contributing to the project](#12-contributing-to-the-project) - - [13. Authors](#13-authors) - - [14. Contribution statement](#14-contribution-statement) - - [15. License and copyright note](#15-license-and-copyright-note) - - [16. Acknowledgements](#16-acknowledgements) - - [17. References](#17-references) + - [3. Use TiMBA](#3-use-timba) + - [4. Supplementary modules](#4-supplementary-modules) + - [5. Project structure](#5-project-structure) + - [6. Model settings](#6-model-settings) + - [6.1. Settings as parameters](#61-settings-as-parameters) + - [6.2. Advanced settings](#62-advanced-settings) + - [7. TiMBA extended model description](#7-timba-extended-model-description) + - [8. Supplementary modules for TiMBA](#8-supplementary-modules-for-timba) + - [9. Roadmap and project status](#9-roadmap-and-project-status) + - [10. FAIR research software](#10-fair-research-software) + - [10.1 Findable](#101-findable) + - [10.2 Accessible](#102-accessible) + - [10.3 Interoperable](#103-interoperable) + - [10.4 Reusable](#104-reusable) + - [11. Contributing to the project](#11-contributing-to-the-project) + - [12. Authors](#12-authors) + - [13. Contribution statement](#13-contribution-statement) + - [14. License and copyright note](#14-license-and-copyright-note) + - [15. Acknowledgements](#15-acknowledgements) + - [16. References](#16-references) ----------------- ## 1. Cite TiMBA @@ -200,7 +200,7 @@ To install TiMBA in editable mode, so that you can modify the TiMBA source code, If you want to develop without using `uv`, you can install TiMBA with `venv` and `pip`, for example for Windows like so: -The prerequistite is that a supported version (9.9 -3.11) is among your +The prerequisite is that a supported version (3.9 -3.11) is among your system-wide installed Python interpreters and that you have [Python Launcher for Windows](https://github.com/oleksis/pylauncher/blob/master/docs/launcher.rst) installed. @@ -248,7 +248,7 @@ results with those provided by the TI-FSM using the coverage report: To reduce the test suite running time, only the first period will be computed and compared. The test suite results will not be saved. -## 4. Use TiMBA +## 3. Use TiMBA TiMBA provides a built-in command-line interface (CLI) that enables users to download input data, execute simulations, and analyse model outputs. @@ -291,7 +291,7 @@ timba run -FP your_path This allows users to organise multiple projects or customise model runs with alternative input datasets (see [Model settings](#model-settings) for further details). -## 5. Supplementary modules +## 4. Supplementary modules The TiMBA ecosystem has a modular design. Each module extends the base functionality of TiMBA in a specific way. TiMBA includes support for **[TiMBA Charts](https://doi.org/10.5281/zenodo.20925292)**, an interactive dashboard for exploring simulation results. @@ -320,7 +320,7 @@ timba carbon This module estimates carbon stocks in forest biomass, forest soils, deadwood, litter, harvested wood products, and substitution effects based on TiMBA simulation results and historical statistics on forest resources and forest product markets ([Honkomp 2026](https://www.sciencedirect.com/science/article/pii/S2352711026000828#abs0001)). -## 6. Project structure +## 5. Project structure After downloading the input data (`timba load`), the project directory is organised as follows: @@ -373,7 +373,7 @@ The output files contain: To ensure reproducibility, TiMBA never overwrites existing simulation results. -## 7. Model settings +## 6. Model settings Multiple settings are integrated for the ***timba run*** command to allow users to interact with the model and adapt the modelling parameters to their research interests. The following chapter provides a brief overview of the model settings. A detailed description of the settings is provided in the model documentation ([TI-FSM 2025](https://literatur.thuenen.de/digbib_extern/dn069603.pdf)). @@ -407,7 +407,7 @@ Basic add-on module settings include (see [add-on modules for TiMBA](#add-on-mod TiMBA is delivered with a validated set of default settings that were tested for stability and consistency. These default parameters can be modified when executing the package via CLI or directly in `default_parameters.py`. Please note that any parameters specified in the CLI will overwrite those defined in `default_parameters.py`. Not all combinations of functionalities and settings have been tested or validated. In particular, shadow and calculated price modes for country- and product-level (PP) and world (WP) prices must be applied consistently. Mixing the two (e.g., PP="calculated_PP" and WP="shadow_WP") is currently not supported and may result in an error. -### 7.1. Settings as parameters +### 6.1. Settings as parameters The CLI provides access to basic model settings and their default values. Check if CLI command is registered and available on your computer by executing: @@ -419,7 +419,7 @@ Default settings can be changed in the following way: (Note that the change of d For this example, TiMBA will simulate 5 periods using calculated prices as product prices and shadow prices as world market prices. -### 7.2. Advanced settings +### 6.2. Advanced settings In addition to the settings accessible via the CLI, users can control advanced settings through changes in `Defines.py` Advance settings include: - solver settings (like accuracy, number of iterations and penalties) @@ -429,7 +429,7 @@ Advance settings include: Some setting combinations might not be coherent and can lead to errors in the simulations or to unreliable results. Those combinations have neither been tested nor validated. Note: TiMBA was tested with a pre-defined number of periods and respective periods' lenght. If the number of periods is changed, it is necessary to compare and adjust this in the ExogChange sheet in the input file. -## 8. TiMBA extended model description +## 7. TiMBA extended model description TiMBA is a partial economic equilibrium model for the global forest products market. The market equilibrium is subject to market clearance and constraints balancing necessary raw materials and produced wood products and limiting the trade (Samuelson 1952). The model structure distinguishes between raw, intermediate and end products. TiMBA differentiates three types of roundwood @@ -451,7 +451,7 @@ The model input data calibration procedure is described in Buongiorno and Zhu (2 The model output comprises information about production, consumption and trade quantities, and prices as well as forest development. The model concept bases on the formal description of the Global Forest Products Model (GFPM) (Buongiorno et al. 2015, Buongiorno et al. 2003). -## 9. Supplementary modules for TiMBA +## 8. Supplementary modules for TiMBA TiMBA is designed as a modular modelling framework that can be extended with additional applications to enable further functionalities. Depending on the use case and the research question, users can activate or deactivate these modular extensions via the CLI or through the `default_parameters`. In this way, the computational load is tailored to the user's needs. The modules are designed @@ -469,7 +469,7 @@ users should refer the respective GitHub repositories. | Carbon Module | tracks carbon stocks and stock changes across pools in the forestry sector including aboveground and belowground biomass, forest soils, deadwood and litter, and harvested wood products. The module applies updated guidelines of the IPCC (2019). A visualization dashbord for carbon results is generated automatically. | `activate_cmodule=True` in `default_parameters.py`
or
`-C=True` in the CLI | [C-Module](https://github.com/TI-Forest-Sector-Modelling/C-Module) | [Honkomp (2025)](https://zenodo.org/records/16912178) | | TiMBA Charts | an analysis toolbox with multiple dashboards about the main TiMBA results | `timba run -SD True` to open the toolbox directly after simulation has ended, or `timba dashboard` to open the toolbox indepently from a specific TiMBA run | [TiMBA Charts](https://github.com/TI-Forest-Sector-Modelling/TiMBA_Charts) | [Morland, C., Tandetzki, J., & Honkomp, T. (2026)](https://doi.org/10.5281/zenodo.20925292) | -## 10. Roadmap and project status +## 9. Roadmap and project status The development of TiMBA is ongoing and we are already working on future releases. @@ -484,7 +484,7 @@ Several projects are currently extending different components of TiMBA: Frequently check [TiMBA repository](https://github.com/TI-Forest-Sector-Modelling/TiMBA) for new releases. -## 11. FAIR research software +## 10. FAIR research software We attempt to adhere as much as possible to the FAIR Principles for research software (e.g. see Barker et al. 2022 and Chue Hong et al. 2022) and reach high @@ -494,7 +494,7 @@ in the GitHub repository or via email to [wf-timba@thuenen.de](mailto:wf-timba@t In the following we detail our efforts and considerations. -### 11.1 Findable +### 10.1 Findable - Zenodo provides a DOI with extensive metadata according to the DataCite schema. - Separate DOIs for each release and one representing all releases. @@ -508,7 +508,7 @@ In the following we detail our efforts and considerations. - We provide machine-actionable citation information in the [Citation File Format (CFF)](https://citation-file-format.github.io/). -### 11.2 Accessible +### 10.2 Accessible - The source code can be accessed in the form of a *git remote* from GitHub, via *http* from Zenodo, but also by Python package managers through the [Python @@ -529,9 +529,9 @@ be difficult to achieve with our current resources. We hope that a comparable in will be developed in the future for better suited Forges such as [Forgejo](https://forgejo.org/) or self-hosted [GitLab](gitlab.com). -### 11.3 Interoperable +### 10.3 Interoperable -#### 11.3.1 Software interoperability +#### 10.3.1 Software interoperability - TiMBA installs both as executable script (`timba_run`) as well as as a Python module (`TiMBA`). The script copies its output also to STDOUT and allows to @@ -546,7 +546,7 @@ will be developed in the future for better suited Forges such as [Forgejo](https also adhere to FAIR principles, are version-controlled in GitHub and can be referenced with DOIs registered by Zenodo. -#### 11.3.2 Data interoperability +#### 10.3.2 Data interoperability - TiMBA relies on a set of required input data. The canonical versions of these data (a non-trivial scientific output) are also kept [version controlled in @@ -571,7 +571,7 @@ will be developed in the future for better suited Forges such as [Forgejo](https preserves the complete simulation state for efficient reuse in Python. We plan to describe these files with standardized metadata in the future. -### 11.4 Reusable +### 10.4 Reusable - TiMBA has dependencies and sub-dependencies which are extensively recorded in the `uv.lock` file to ensure reproducibility. @@ -593,7 +593,7 @@ will be developed in the future for better suited Forges such as [Forgejo](https research community. -## 12. Contributing to the project +## 11. Contributing to the project We welcome contributions, additions and suggestion to further develop or improve the code and the model. To check, discuss and include them into this project, we would like you to share your ideas with us so that we can agree on the requirements needed for accepting your contribution. You can contact us directly via GitHub by creating issues, or by writing an Email to: @@ -603,7 +603,7 @@ You can contact us directly via GitHub by creating issues, or by writing an Emai So far, this README serves as a comprehensive introduction and guidance on how to get started. ´The model documentation ([TI-FSM 2025](https://literatur.thuenen.de/digbib_extern/dn069603.pdf)) and model validation ([TI-FSM 2026](https://literatur.thuenen.de/digbib_extern/dn070984.pdf)) enables a deeper dive. -## 13. Authors +## 12. Authors TiMBA was developed and written by an authors' collective named Thünen Institute Forest Sector Modelling (TI-FSM). The individual authors are listed in alphabetical order @@ -612,7 +612,7 @@ The individual authors are listed in alphabetical order - [Julia Tandetzki](https://www.thuenen.de/de/fachinstitute/waldwirtschaft/personal/wissenschaftliches-personal/julia-tandetzki-msc) [(ORCID 0000-0002-0630-9434)](https://orcid.org/0000-0002-0630-9434), and - [Tomke Honkomp](https://www.thuenen.de/de/fachinstitute/waldwirtschaft/personal/wissenschaftliches-personal/tomke-honkomp-msc) [(ORCID 0000-0002-6719-0190)](https://orcid.org/0000-0002-6719-0190). -## 14. Contribution statement +## 13. Contribution statement Within the authors' collective TI-FSM, the authors have contributed over years their individual strengths and knowledge to make the model work: | Author | Conceptualization and theoretical framework | Methodology | Data Curation and Management | Formal Analysis | Programming | Writing and Documentation | Visualization | Review and Editing | Supervision | @@ -622,7 +622,7 @@ Within the authors' collective TI-FSM, the authors have contributed over years t | Julia Tandetzki | X | X | X | X | X | X | X | X | | | Tomke Honkomp | X | X | X | X | X | X | X | X | | -## 15. License and copyright note +## 14. License and copyright note Licensed under the GNU AGPL, Version 3.0. @@ -644,7 +644,7 @@ Copyright ©, 2024, Thuenen Institute, TI-FSM, wf-timba@thuenen.de -## 16. Acknowledgements +## 15. Acknowledgements This work is the result of great joint efforts of the forest products market analysis team at the Thünen Institute of Forestry and others from 2018 to 2024. In the last years, many people made important contributions to this work. Without their support, reflection, and constructive criticism, this undertaking would not have been as successful as it turns out to be now. We would like express our gratitude to all of them. In particular, we would like to thank - Pixida GmbH and especially Tobias Hierlmeier for professional support in revising and restructuring the model architecture and code and being valuable help in programming tasks @@ -654,7 +654,7 @@ This work is the result of great joint efforts of the forest products market ana - The Thünen Institut of Forestry and its Head Matthias Dieter for providing financial resources over the years - [makeareadme.com](https://www.makeareadme.com/) for providing the template this README is leaned on. -## 17. References +## 16. References - Barker, M., Chue Hong, N.P., Katz, D.S. et al. Introducing the FAIR Principles for research software. Sci Data 9, 622 (2022). https://doi.org/10.1038/s41597-022-01710-x - Buongiorno, J.; Zhu, S.; Zhang, D.; Turner, J.; Tomberlin, D. The Global Forest Products Model; Academic Press: Cambridge, MA, USA, 2003; ISBN 978-0-12-141362-0 - Buongiorno, J. Global modelling to predict timber production and prices: The GFPM approach. Forestry 2015, 88, 291–303.