From 781ab30561ceb4db33e6ca1c43a0c6d99d23a945 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 6 May 2025 18:41:07 -0300 Subject: [PATCH 1/7] fix docs path --- CONTRIBUTING.md | 4 ++-- README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39e2659f..3becf3bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,7 +47,7 @@ We welcome code contributions, from bug fixes to new features. 2. **Set Up Development Environment:** - Follow the instructions in the [Installation Guide](https://firefront.readthedocs.io/en/latest/getting_started/installation.html) to build ForeFire from source. *(Update link if RTD URL changes)* + Follow the instructions in the [Installation Guide](https://forefire.readthedocs.io/en/latest/getting_started/installation.html) to build ForeFire from source. *(Update link if RTD URL changes)* 3. **Fork the Repository:** @@ -64,7 +64,7 @@ We welcome code contributions, from bug fixes to new features. Implement your code changes, following existing coding style and conventions where possible. 6. **Add Tests (if applicable):** - For new features or significant bug fixes, please add corresponding tests or update existing ones. See the [Testing Documentation](https://firefront.readthedocs.io/en/latest/developer_guide/testing.html) *(Placeholder: Link to testing section once created)* for details on how to run tests. Ensure all tests pass locally. + For new features or significant bug fixes, please add corresponding tests or update existing ones. See the [Testing Documentation](https://forefire.readthedocs.io/en/latest/developer_guide/testing.html) *(Placeholder: Link to testing section once created)* for details on how to run tests. Ensure all tests pass locally. ```bash # Example command to run tests (adjust as needed) cd tests && bash run.bash diff --git a/README.md b/README.md index 4edcc72b..1728405c 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) ![Language](https://img.shields.io/badge/C++-00599C?logo=c%2B%2B&logoColor=white) ![Language](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white) -[![Documentation Status](https://readthedocs.org/projects/firefront/badge/?version=latest)](https://firefront.readthedocs.io/en/latest/?badge=latest) +[![Documentation Status](https://readthedocs.org/projects/forefire/badge/?version=latest)](https://forefire.readthedocs.io/en/latest/?badge=latest) [![DOI](https://img.shields.io/badge/DOI-10.14195/978--989--26--0884--6_29-blue)](https://www.researchgate.net/publication/278769168_ForeFire_open-source_code_for_wildland_fire_spread_models) @@ -17,7 +17,7 @@ **Key Links:** -- 📚 **Full Documentation:** [forefire.readthedocs.io](https://firefront.readthedocs.io/en/latest/) +- 📚 **Full Documentation:** [forefire.readthedocs.io](https://forefire.readthedocs.io/en/latest/) - 🚀 **Live Demo:** [forefire.univ-corse.fr/sim](http://forefire.univ-corse.fr/sim) - 🌍 **Website:** [forefire.univ-corse.fr](https://forefire.univ-corse.fr/) From 6507e819137ec8fa9fdcc30c6e01125809efe157 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 6 May 2025 18:44:41 -0300 Subject: [PATCH 2/7] fix repo name --- bindings/python/setup.py | 2 +- docs/source/getting_started/installation.rst | 14 +++++++------- docs/source/getting_started/quickstart.rst | 2 +- .../source/getting_started/running_the_example.rst | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/bindings/python/setup.py b/bindings/python/setup.py index 05c8239a..235618d8 100644 --- a/bindings/python/setup.py +++ b/bindings/python/setup.py @@ -6,7 +6,7 @@ # Determine current directory (where setup.py resides) this_dir = os.path.abspath(os.path.dirname(__file__)) -# Compute the top-level ForeFire directory (two levels up: bindings/python -> bindings -> firefront) +# Compute the top-level ForeFire directory (two levels up: bindings/python -> bindings -> forefire) FOREFIRE_DIR = os.path.abspath(os.path.join(this_dir, "..", "..")) FOREFIRE_LIB = "forefireL" # as used in lib/libforefireL.dylib (or .so/.dll) diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 1f15cdf7..0238a01d 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -33,7 +33,7 @@ The repository provides a convenience script (`install-forefire.sh`) that automa .. code-block:: bash git clone https://github.com/forefireAPI/forefire.git - cd firefront + cd forefire 2. **Run the install script:** @@ -66,7 +66,7 @@ Use this method if you are not on Debian/Ubuntu, prefer manual control, or don't .. code-block:: bash git clone https://github.com/forefireAPI/forefire.git - cd firefront + cd forefire 2. **Install Prerequisites Manually:** @@ -102,21 +102,21 @@ The main executable `forefire` will be located at `../bin/forefire` (relative to .. code-block:: bash - # Execute this from the root of the firefront repository + # Execute this from the root of the forefire repository export PATH=$PATH:`pwd`/bin **Permanently:** - Add the following line to your shell's configuration file (e.g., `~/.bashrc`, `~/.zshrc`, `~/.profile`, or `~/.config/fish/config.fish`). Replace `/path/to/firefront` with the actual absolute path to the cloned repository. + Add the following line to your shell's configuration file (e.g., `~/.bashrc`, `~/.zshrc`, `~/.profile`, or `~/.config/fish/config.fish`). Replace `/path/to/forefire` with the actual absolute path to the cloned repository. .. code-block:: bash - export PATH="/path/to/firefront/bin:$PATH" + export PATH="/path/to/forefire/bin:$PATH" - *Optional:* The install script also sets `export FOREFIREHOME="/path/to/firefront"`. You may want to add this line as well, as some scripts or components might potentially use it. + *Optional:* The install script also sets `export FOREFIREHOME="/path/to/forefire"`. You may want to add this line as well, as some scripts or components might potentially use it. .. code-block:: bash - export FOREFIREHOME="/path/to/firefront" + export FOREFIREHOME="/path/to/forefire" After editing your configuration file, either restart your terminal or reload the configuration (e.g., `source ~/.bashrc`). \ No newline at end of file diff --git a/docs/source/getting_started/quickstart.rst b/docs/source/getting_started/quickstart.rst index 8c3a59ae..5b0b216e 100644 --- a/docs/source/getting_started/quickstart.rst +++ b/docs/source/getting_started/quickstart.rst @@ -23,7 +23,7 @@ Steps .. code-block:: bash - cd firefront + cd forefire docker build . -t forefire:latest This might take a few minutes the first time as it downloads base images and installs dependencies inside the Docker build environment. diff --git a/docs/source/getting_started/running_the_example.rst b/docs/source/getting_started/running_the_example.rst index e303f9dc..bf6a7521 100644 --- a/docs/source/getting_started/running_the_example.rst +++ b/docs/source/getting_started/running_the_example.rst @@ -29,7 +29,7 @@ This is the simplest way to run a simulation non-interactively by feeding the en 1. **Navigate to the test directory:** - Ensure your terminal's current directory is the root of the cloned `firefront` repository. Then navigate: + Ensure your terminal's current directory is the root of the cloned `forefire` repository. Then navigate: .. code-block:: bash From 6f4de630acd1af8bb4e5dbb1dca5c7772ffe1336 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 6 May 2025 19:00:05 -0300 Subject: [PATCH 3/7] better actions --- .github/workflows/main.yml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index d3dc8cd2..c4ba949b 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -4,7 +4,7 @@ on: push: branches: - "master" - - "dev-ci" + - "dev" pull_request: branches: [ "master" ] workflow_dispatch: @@ -16,7 +16,7 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 with: - lfs: true # Keep enabled as you use LFS + lfs: true # we use LFS to store large files (e.g. data.nc) - name: Install Dependencies (Build + Test) run: | @@ -39,7 +39,6 @@ jobs: - name: Check ForeFire version run: ./bin/forefire -v - # --- KEEPING DIAGNOSTIC STEPS --- - name: Add Build/Runtime Diagnostics run: | echo "--- ForeFire Linkage ---" @@ -49,7 +48,6 @@ jobs: # Install ncdump tool and check the format kind sudo apt-get install -y --no-install-recommends netcdf-bin ncdump -k tests/runff/data.nc || echo "Could not check data.nc format" - # --- END DIAGNOSTIC STEPS --- - name: Run 'runff' Test Script run: | From c63db8cbba4b82578ac0c9448d3f5ee38b1e3172 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 6 May 2025 20:07:58 -0300 Subject: [PATCH 4/7] better api reference docs --- docs/source/reference/api_reference.rst | 67 ++++++++++++++++++------- 1 file changed, 49 insertions(+), 18 deletions(-) diff --git a/docs/source/reference/api_reference.rst b/docs/source/reference/api_reference.rst index 58caa15c..662a7e17 100644 --- a/docs/source/reference/api_reference.rst +++ b/docs/source/reference/api_reference.rst @@ -1,46 +1,77 @@ C++ API Reference ================= -This section will contain the C++ API reference, automatically generated from source code comments using Doxygen and Breathe. +This section provides a high-level overview of the most fundamental C++ classes and interfaces that constitute the ForeFire simulation engine. For a comprehensive, detailed API reference for all classes and functions, please consult the full Doxygen-generated documentation. -Key C++ classes providing the core functionality of ForeFire include: +Core Simulation Objects +----------------------- + +These classes represent the primary entities in a wildfire simulation. .. doxygenclass:: libforefire::FireDomain :project: ForeFire - :members: + :members: getDomainFront, addFireFront, addFireNode, getDataBroker, getPropagationSpeed, setTimeTable, getSimulationTime, SWCorner, NECorner -.. doxygenclass:: libforefire::FireNode +.. doxygenclass:: libforefire::FireFront :project: ForeFire - :members: + :members: getHead, addFireNode, split, merge, getNumFN, isExpanding, getTime -.. doxygenclass:: libforefire::FireFront +.. doxygenclass:: libforefire::FireNode :project: ForeFire - :members: + :members: getLoc, getVel, getNormal, getSpeed, getFrontDepth, getCurvature, setFront, getTime, getState + +Data Management +--------------- + +These classes are central to how ForeFire handles environmental and simulation data. .. doxygenclass:: libforefire::DataBroker :project: ForeFire - :members: + :members: getLayer, getFluxLayer, registerPropagationModel, registerFluxModel, getPropagationData, getFluxData .. doxygenclass:: libforefire::DataLayer :project: ForeFire - :members: + :members: getKey, getValueAt, getMatrix + :outline: + +.. rubric:: Note + ForeFire provides various specializations of ``DataLayer`` (e.g., for 2D/3D arrays, NetCDF files, fuel properties, atmospheric data) to handle different data sources and types. Refer to the full Doxygen documentation for details on specific implementations like ``Array2DdataLayer``, ``NCXYZTDataLayer``, ``FuelDataLayer``, etc. -.. .. doxygenclass:: libforefire::PropagationModel -.. :project: ForeFire -.. :members: +Scientific Model Interfaces +--------------------------- -.. .. doxygenclass:: libforefire::FluxModel -.. :project: ForeFire -.. :members: +These abstract base classes define how new scientific models for fire spread and flux calculations can be integrated. + +.. doxygenclass:: libforefire::PropagationModel + :project: ForeFire + :members: getName, getSpeedForNode, getSpeed + +.. doxygenclass:: libforefire::FluxModel + :project: ForeFire + :members: getName, getValueAt, getValue + +User Interaction & Configuration +-------------------------------- + +These components manage user commands and simulation parameters. .. doxygenclass:: libforefire::Command :project: ForeFire - :members: + :members: ExecuteCommand, getDomain, setParameter, getParameter .. doxygenclass:: libforefire::SimulationParameters :project: ForeFire - :members: + :members: GetInstance, setParameter, getParameter, getDouble, getInt + +Fundamental Utilities +--------------------- -.. doxygenclass:: libforefire::Simulator +Basic geometric data types used throughout the simulation. + +.. doxygenclass:: libforefire::FFPoint :project: ForeFire :members: + +.. doxygenclass:: libforefire::FFVector + :project: ForeFire + :members: \ No newline at end of file From 81b4cca8f758a809fb5764a98c8b3270ee00b472 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 6 May 2025 20:17:10 -0300 Subject: [PATCH 5/7] api referrence --- docs/source/reference/api_reference.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/source/reference/api_reference.rst b/docs/source/reference/api_reference.rst index 662a7e17..88c35e6c 100644 --- a/docs/source/reference/api_reference.rst +++ b/docs/source/reference/api_reference.rst @@ -10,15 +10,15 @@ These classes represent the primary entities in a wildfire simulation. .. doxygenclass:: libforefire::FireDomain :project: ForeFire - :members: getDomainFront, addFireFront, addFireNode, getDataBroker, getPropagationSpeed, setTimeTable, getSimulationTime, SWCorner, NECorner + :members: .. doxygenclass:: libforefire::FireFront :project: ForeFire - :members: getHead, addFireNode, split, merge, getNumFN, isExpanding, getTime + :members: .. doxygenclass:: libforefire::FireNode :project: ForeFire - :members: getLoc, getVel, getNormal, getSpeed, getFrontDepth, getCurvature, setFront, getTime, getState + :members: Data Management --------------- @@ -27,12 +27,11 @@ These classes are central to how ForeFire handles environmental and simulation d .. doxygenclass:: libforefire::DataBroker :project: ForeFire - :members: getLayer, getFluxLayer, registerPropagationModel, registerFluxModel, getPropagationData, getFluxData + :members: .. doxygenclass:: libforefire::DataLayer :project: ForeFire - :members: getKey, getValueAt, getMatrix - :outline: + :members: .. rubric:: Note ForeFire provides various specializations of ``DataLayer`` (e.g., for 2D/3D arrays, NetCDF files, fuel properties, atmospheric data) to handle different data sources and types. Refer to the full Doxygen documentation for details on specific implementations like ``Array2DdataLayer``, ``NCXYZTDataLayer``, ``FuelDataLayer``, etc. @@ -44,11 +43,11 @@ These abstract base classes define how new scientific models for fire spread and .. doxygenclass:: libforefire::PropagationModel :project: ForeFire - :members: getName, getSpeedForNode, getSpeed + :members: .. doxygenclass:: libforefire::FluxModel :project: ForeFire - :members: getName, getValueAt, getValue + :members: User Interaction & Configuration -------------------------------- @@ -57,11 +56,11 @@ These components manage user commands and simulation parameters. .. doxygenclass:: libforefire::Command :project: ForeFire - :members: ExecuteCommand, getDomain, setParameter, getParameter + :members: .. doxygenclass:: libforefire::SimulationParameters :project: ForeFire - :members: GetInstance, setParameter, getParameter, getDouble, getInt + :members: Fundamental Utilities --------------------- From 93a1dbf594d5dcfa39638d9e170632ae20b649d8 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 6 May 2025 20:23:27 -0300 Subject: [PATCH 6/7] git atrubutes --- .gitattributes | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/.gitattributes b/.gitattributes index 1afd67d3..d8381b0b 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,12 @@ -*.ipynb linguist-detectable=false + +# handles large files via git-lfs *.ref filter=lfs diff=lfs merge=lfs -text + +# handles lf and crlf for those using git on windows with wsl * text=auto -*.sh text eol=lf +*.sh text eol=lf +*.bash text eol=lf +*.csv text eol=lf + +# makes ipynb extension not detectable by linguist +*.ipynb linguist-detectable=false From b314cc584988b65b3483ab036fea8a9bd2872dcd Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 6 May 2025 20:43:27 -0300 Subject: [PATCH 7/7] forefire -l (listen) --- README.md | 2 +- docs/source/getting_started/quickstart.rst | 2 +- .../getting_started/running_the_example.rst | 18 ++++++++++++++++-- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1728405c..a53eae9f 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ The easiest way to get started is often using Docker and the interactive console forefire> listenHTTP[] # the output should be - >> HTTP command server listening at http://localhost:8000 + >> ForeFire HTTP command server listening at http://localhost:8000 ``` This server provides a grafical user interface that you can access on your browser at http://localhost:8000/ diff --git a/docs/source/getting_started/quickstart.rst b/docs/source/getting_started/quickstart.rst index 5b0b216e..85e28976 100644 --- a/docs/source/getting_started/quickstart.rst +++ b/docs/source/getting_started/quickstart.rst @@ -58,7 +58,7 @@ Steps forefire> listenHTTP[] - You should see output like: `>> HTTP command server listening at http://localhost:8000` + You should see the output : `>> ForeFire HTTP command server listening at http://localhost:8000` 7. **Access the Web Console:** diff --git a/docs/source/getting_started/running_the_example.rst b/docs/source/getting_started/running_the_example.rst index bf6a7521..e53c4577 100644 --- a/docs/source/getting_started/running_the_example.rst +++ b/docs/source/getting_started/running_the_example.rst @@ -100,9 +100,13 @@ This method uses the built-in HTTP server to provide a web-based console and map cd tests/runff -2. **Start the ForeFire interpreter** (as shown in Method 2, ensuring you start it from *within* the `tests/runff` directory for simplicity with file paths in the next steps). +2. **Start the ForeFire interpreter and launch the HTTP server:** -3. **Launch the HTTP server:** + Assuming ``forefire`` is in your PATH: + + .. code-block:: bash + + forefire At the ``forefire>`` prompt, type: @@ -110,6 +114,16 @@ This method uses the built-in HTTP server to provide a web-based console and map forefire> listenHTTP[] + You should see the output: `>> ForeFire HTTP command server listening at http://localhost:8000`. + + **Alternative Shortcut** using ``-l`` (listen) flag: + + Alternatively, to launch the HTTP server directly without entering the interactive console first, you can use the `-l` command-line option. This is convenient if you primarily want to use the web interface. + + .. code-block:: none + + forefire -l + 4. **Use the Web Interface:** - Open your browser to ``http://localhost:8000/`` (or the specified port).