From b0d8bc9d346f1620993af64810950fb3b940d3a9 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Mon, 28 Apr 2025 15:20:58 -0300 Subject: [PATCH 01/13] update running example --- docs/source/running_the_example.rst | 175 +++++++++++----------------- 1 file changed, 65 insertions(+), 110 deletions(-) diff --git a/docs/source/running_the_example.rst b/docs/source/running_the_example.rst index 05f14044..15fde3d0 100644 --- a/docs/source/running_the_example.rst +++ b/docs/source/running_the_example.rst @@ -1,178 +1,133 @@ +.. _running-the-example: + Running an Example ================== -After successfully installing ForeFire (either :doc:`from source ` or via :doc:`Docker `), you can run the example simulation located in the ``tests/runff/`` directory. This helps verify your installation and introduces you to the basic workflow and command execution methods. +After successfully installing ForeFire (either :doc:`from source ` or via :doc:`Docker `), you can run the example simulation located in the ``tests/runff/`` directory. This helps verify your installation and introduces you to the basic command execution methods. -Simulation files ----------------- +Simulation Files Used +--------------------- The directory ``tests/runff/`` contains the necessary files for the ``real_case.ff`` simulation: -* ``real_case.ff``: The main **script file** defining the simulation steps. This is the file we will execute. -* ``params.ff``: Contains simulation parameters (like model choices, resolutions) included by ``real_case.ff``. -* ``data.nc``: The NetCDF **landscape file** containing geospatial data (elevation, fuel types) for the simulation domain. -* ``fuels.csv``: The **fuels definition file**, specifying properties for different fuel types referenced in ``data.nc``. - - -Understanding the Example Script (`real_case.ff`) -------------------------------------------------- - -Before running the example, let's briefly look at what the ``real_case.ff`` script instructs ForeFire to do. While the full script might be longer, it typically performs actions like these using specific ForeFire commands: - -1. **Include Parameters:** Often starts by including parameter settings from another file (like ``params.ff``) using the :ref:`include ` command. - - .. code-block:: none - - # Example snippet from a .ff file: - include[input=params.ff] - -2. **Load Landscape Data:** Loads the terrain, fuel, and potentially weather data from the NetCDF file (``data.nc``) using the :ref:`loadData ` command, associating it with a start date/time. - - .. code-block:: none - - # Example snippet: - loadData[data.nc;2020-02-10T17:35:54Z] # Date/time may vary - -3. **Define Ignition:** Starts the fire at a specific location and time using the :ref:`startFire ` command. - - .. code-block:: none - - # Example snippet (coordinates may vary): - startFire[lonlat=(8.916,41.816);t=0] - -4. **Set Dynamic Conditions (Optional):** May use :ref:`trigger ` commands to introduce changes during the simulation, like setting wind conditions at specific times. - - .. code-block:: none - - # Example snippet (values/time may vary): - trigger[fuelType=wind;vel=(5.0, 2.0, 0.0);t=1800] # Set wind at 1800s - -5. **Run the Simulation:** Advances the simulation time using :ref:`step ` (run for a duration) or :ref:`goTo ` (run until a specific time). - - .. code-block:: none - - # Example snippet (time may vary): - goTo[t=7200] # Run simulation until t = 7200 seconds (2 hours) - -6. **Generate Output:** Saves the final state (or intermediate states) using commands like :ref:`print ` (saves front geometry) or :ref:`save ` (saves arrival time map). - - .. code-block:: none - - # Example snippet (filename may vary): - setParameter[dumpMode=geojson] # Set output format - print[output_front.geojson] - save[] # Save arrival time map - -7. **Terminate:** The script execution finishes, or it might contain an explicit :ref:`quit ` command. +- ``real_case.ff``: The main **script file** defining the simulation steps and commands. This is the file we will execute. +- ``params.ff``: Contains simulation parameters (like model choices, resolutions) included by ``real_case.ff``. +- ``data.nc``: The NetCDF **landscape file** containing geospatial data (elevation, fuel types) for the simulation domain. +- ``fuels.csv``: The **fuels definition file**, specifying properties for different fuel types referenced in ``data.nc``. -Knowing these basic steps helps understand what happens when you execute the ``real_case.ff`` script using the methods below. For full details on each command, see the :doc:`Command Reference `. +The ``real_case.ff`` file itself contains a sequence of ForeFire commands that set up parameters, load data, define an ignition, run the simulation, and save results. To learn about the syntax, structure, and typical commands used within a ``.ff`` script file, please refer to the :doc:`ForeFire Script File guide `. Executing the Example Script ---------------------------- -You can run the ``real_case.ff`` simulation (which contains commands like those shown above) using the ``forefire`` executable in several ways: +The following sections demonstrate three different ways to execute the commands contained within the ``real_case.ff`` script using the ``forefire`` interpreter. 1: Direct Execution (Command Line / Batch Mode) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is the simplest way to run a simulation non-interactively by feeding the entire script file to the interpreter. It's useful for automated runs or when you don't need interaction. +This is the simplest way to run a simulation non-interactively by feeding the entire script file to the interpreter. It's useful for automated runs. 1. **Navigate to the test directory:** - + + Ensure your terminal's current directory is the root of the cloned `firefront` repository. Then navigate: + .. code-block:: bash cd tests/runff 2. **Execute using the** ``-i`` **flag:** - This tells ForeFire to read and execute all commands sequentially from the specified file (``real_case.ff``). + + This tells ForeFire to read and execute all commands sequentially from the specified file (``real_case.ff``). - If ``forefire`` is in your PATH: - - .. code-block:: bash + If ``forefire`` is in your PATH: - forefire -i real_case.ff + .. code-block:: bash - If ``forefire`` is NOT in your PATH (running from ``tests/runff``): - - .. code-block:: bash + forefire -i real_case.ff + + If ``forefire`` is NOT in your PATH (run from the root of the repo): + + .. code-block:: bash - ../../bin/forefire -i real_case.ff + ../../bin/forefire -i real_case.ff -3. **Observe:** ForeFire will print status messages to the console as it executes the commands within ``real_case.ff``. It will likely create output files (like ``to_reload.ff`` or others specified by ``print``/``save`` commands in the script) in the current directory (``tests/runff``). +3. **Observe:** ForeFire will print status messages to the console as it executes the commands within ``real_case.ff``. It will likely create output files (as specified by ``print``/``save`` commands in the script) in the current directory (``tests/runff``). 2: Interactive Console ~~~~~~~~~~~~~~~~~~~~~~ -This method starts the ForeFire interpreter first, allowing you to type all the commands manually. You can then use the ``include`` command to execute the script file, and potentially interact further before or after. +This method starts the ForeFire interpreter first, allowing you to execute the script file using the ``include`` command, and potentially interact further before or after. + +1. **Navigate to the test directory** (if not already there): -1. **Navigate to the test directory:** - .. code-block:: bash cd tests/runff 2. **Start the ForeFire interpreter:** - If ``forefire`` is in your PATH: - - .. code-block:: bash + If ``forefire`` is in your PATH: + + .. code-block:: bash + + forefire - forefire + If ``forefire`` is NOT in your PATH (run from the root of the repo): - If ``forefire`` is NOT in your PATH (running from ``tests/runff``): - - .. code-block:: bash + .. code-block:: bash - ../../bin/forefire + ../../bin/forefire 3. **Run the script using the** ``include`` **command:** - - Once you see the ``forefire>`` prompt, type the command to execute the script file: - - .. code-block:: none - forefire> include[real_case.ff] + Once you see the ``forefire>`` prompt, type the command to execute the script file. + + .. code-block:: none + + forefire> include[input=real_case.ff] + 4. **Observe:** The simulation will run similarly to Method 1, executing the commands from ``real_case.ff`` and printing output to the console. Afterwards, you remain in the interactive console (``forefire>`` prompt) and can inspect parameters (e.g., ``getParameter[propagationModel]``), run further steps manually (e.g., ``step[dt=600]``), or exit using ``quit[]``. 3: Web Interface ~~~~~~~~~~~~~~~~ -This method uses the built-in HTTP server to provide a web-based console and map visualization. It executes commands in the same way as the interactive console but through your browser. It's great for demonstrations or visual exploration. +This method uses the built-in HTTP server to provide a web-based console and map visualization. It executes commands in the same way as the interactive console but through your browser. -1. **Navigate to the test directory:** - - .. code-block:: bash +1. **Navigate to the test directory** (if not already there): + + .. code-block:: bash - cd tests/runff + cd tests/runff -2. **Start the ForeFire interpreter** (as shown in Method 2). +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). 3. **Launch the HTTP server:** - At the ``forefire>`` prompt, type: - - .. code-block:: none + + At the ``forefire>`` prompt, type: - forefire> listenHTTP[] + .. code-block:: none + + forefire> listenHTTP[] 4. **Use the Web Interface:** - - * Open your browser to ``http://localhost:8000/`` (or the specified port). - * In the command input box in the web UI, type ``include[real_case.ff]`` and press Enter or click Send. This executes the script file. - * Click "Refresh Map" periodically to see the simulation progress visually. You can also type other commands directly into the web console. + + - Open your browser to ``http://localhost:8000/`` (or the specified port). + - In the command input box in the web UI, type ``include[input=real_case.ff]`` and press Enter or click Send. This executes the script file relative to where the interpreter was started (which we ensured was `tests/runff`). + - Click "Refresh Map" periodically to see the simulation progress visually. You can also type other commands directly into the web console. Choosing a Method ----------------- -* Use **Method 1 (Direct Execution)** for standard, non-interactive runs or scripting. -* Use **Method 2 (Interactive Console)** when you want to experiment with commands step-by-step or inspect the state directly via text after running a script. -* Use **Method 3 (Web UI)** for visual feedback and interactive demonstrations. +- Use **Method 1 (Direct Execution)** for standard, non-interactive runs or scripting. +- Use **Method 2 (Interactive Console)** when you want to experiment with commands step-by-step or inspect the state directly via text after running a script. +- Use **Method 3 (Web UI)** for visual feedback and interactive demonstrations. Next Steps ---------- -Now that you've seen how to run an existing example script and understand the basic commands it contains, you can learn more about: +Now that you've seen the different ways to *execute* a ForeFire script, you can learn more about: -* The :doc:`basic_configuration` files required for setting up your own simulations. -* The detailed :doc:`reference/commands` and :doc:`reference/parameters`. -* Exploring the core concepts in the **User Guide** (coming soon!). \ No newline at end of file +- How to **write and structure** your own scripts in the :doc:`ForeFire Script File guide `. +- The specific :doc:`Input Files ` required (Fuels, Landscape). +- The detailed :doc:`Command ` and :doc:`Parameter ` references. \ No newline at end of file From 7fb7e908c096b1b15ad3fafd0fed49fc859dce35 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Mon, 28 Apr 2025 17:20:45 -0300 Subject: [PATCH 02/13] ff script explanation --- docs/source/index.rst | 1 + docs/source/running_the_example.rst | 2 +- docs/source/user_guide/forefire_script.rst | 152 +++++++++++++++++++++ 3 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 docs/source/user_guide/forefire_script.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 67fbcc35..27aa4dac 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,6 +24,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire user_guide/basic_configuration user_guide/fuels_file user_guide/landscape_file + user_guide/forefire_script .. toctree:: :maxdepth: 2 diff --git a/docs/source/running_the_example.rst b/docs/source/running_the_example.rst index 15fde3d0..f981583f 100644 --- a/docs/source/running_the_example.rst +++ b/docs/source/running_the_example.rst @@ -129,5 +129,5 @@ Next Steps Now that you've seen the different ways to *execute* a ForeFire script, you can learn more about: - How to **write and structure** your own scripts in the :doc:`ForeFire Script File guide `. -- The specific :doc:`Input Files ` required (Fuels, Landscape). +- The specific :doc:`Input Files ` required (Fuels, Landscape). - The detailed :doc:`Command ` and :doc:`Parameter ` references. \ No newline at end of file diff --git a/docs/source/user_guide/forefire_script.rst b/docs/source/user_guide/forefire_script.rst new file mode 100644 index 00000000..226c56e7 --- /dev/null +++ b/docs/source/user_guide/forefire_script.rst @@ -0,0 +1,152 @@ +.. _userguide-forefire-script: + +ForeFire Script File (.ff) +========================== + +The ForeFire Script File, conventionally given a ``.ff`` extension, is a plain text file that contains a sequence of commands to control and execute a ForeFire simulation. It acts as the primary way to define a simulation scenario for non-interactive runs. + +Purpose +------- + +The script file allows you to automate the entire simulation process, including: + +- Setting simulation parameters. +- Loading necessary input data (landscape, fuels). +- Defining the initial state of the fire (ignition points or lines). +- Specifying dynamic conditions (like changing winds). +- Controlling the simulation's time progression. +- Generating output files at desired intervals or at the end. + +Basic Syntax +------------ + +- **One Command Per Line:** Each line in the script file generally represents a single ForeFire command. +- **Command Structure:** Commands follow the format ``CommandName[argument1=value1;argument2=value2;...]``. + + - The command name is case-sensitive (e.g., ``setParameter`` is different from ``setparameter``). + - Arguments are enclosed in square brackets ``[...]``. + - Arguments are typically key-value pairs separated by an equals sign ``=``. + - Multiple arguments within the brackets are separated by semicolons ``;``. + - Some commands might take positional arguments (like :ref:`loadData `) or have optional arguments (prefixed with `opt:` in the :doc:`Command Reference `). +- **Comments:** Lines beginning with a hash symbol ``#`` are treated as comments and are ignored by the interpreter. +- **Whitespace:** Leading and trailing whitespace on a line is generally ignored, except for indentation (see below). + +Indentation for Hierarchy (FireFront / FireNode) +------------------------------------------------ + +Certain commands, specifically :ref:`FireFront ` and :ref:`FireNode `, use **leading spaces (indentation)** to define their relationship within the simulation structure when creating custom initial fire perimeters: + +- A ``FireFront`` defined within a :ref:`FireDomain ` is typically indented (e.g., 4 spaces). +- A ``FireNode`` belonging to that ``FireFront`` is indented further relative to the `FireFront` (e.g., another 4 spaces, totaling 8). +- An inner ``FireFront`` (representing an unburned island within another `FireFront`) would be indented relative to its parent `FireFront`. + +.. code-block:: none + :caption: Example Indentation for Custom Front + + # FireDomain defined earlier or implicitly... + + # Indented FireFront (e.g., 4 spaces) + FireFront[t=0] + # Further indented FireNode (e.g., 8 spaces total) + FireNode[loc=(100,100,0);t=0] + FireNode[loc=(200,100,0);t=0] + FireNode[loc=(150,150,0);t=0] + # ... potentially more nodes defining the outer perimeter + + +.. important:: + Consistent use of spaces (not tabs) is recommended for indentation. The exact number of spaces required might need experimentation or checking examples, but the relative indentation defines the hierarchy. Using :ref:`startFire ` is often simpler for basic point ignitions. + +Typical Script Workflow +----------------------- + +While the exact commands depend on the simulation, a common workflow within a ``.ff`` script looks like this: + +1. **Setup Parameters:** Define simulation controls, model choices, resolution, etc. + + .. code-block:: none + + # Include parameters from a separate file (optional) + # include[input=params.ff] + + # Set specific parameters directly + setParameters[propagationModel=Rothermel;perimeterResolution=30;dumpMode=geojson] + +2. **Load Input Data:** Load the geospatial context. + + .. code-block:: none + + # Load landscape and associate with a time + loadData[my_landscape.nc;2024-01-01T12:00:00Z] + # Note: The fuels file (e.g., fuels.csv) is usually implicitly loaded + # based on the 'fuelsTableFile' parameter or defaults, + # but its path might need to be relative to 'caseDirectory'. + +3. **Define Simulation Domain (if needed):** While ``loadData`` can implicitly define the domain extent based on the NetCDF file, you can also explicitly define it using ``FireDomain``. + + .. code-block:: none + + # Optional explicit domain definition (using projected coords) + # FireDomain[sw=(0,0,0);ne=(50000,50000,0);t=0] + +4. **Define Initial Fire State:** Specify where and when the fire starts. + + .. code-block:: none + + # Simple point ignition + startFire[lonlat=(9.1, 42.2); t=0] # Using geographic coordinates + + # --- OR --- + + # Custom initial front (using projected coords and indentation) + # Ensure FireDomain covers these coordinates + # FireFront[t=0] + # FireNode[loc=(2500,3000,150);t=0] + # FireNode[loc=(2600,3000,150);t=0] + # FireNode[loc=(2550,3100,150);t=0] + + +5. **Set Dynamic Conditions (Optional):** Introduce time-varying inputs, like wind changes. + + .. code-block:: none + + # Set initial wind (applied from t=0 if not in landscape file) + trigger[fuelType=wind;vel=(3.0, -1.0, 0.0);t=0] + + # Change wind later in the simulation + trigger[fuelType=wind;vel=(0.0, 5.0, 0.0);t=3600] # New wind at 1 hour + +6. **Advance Simulation Time:** Run the simulation forward. + + .. code-block:: none + + # Run until a specific absolute simulation time + goTo[t=7200] # Run until t = 2 hours + + # --- OR --- + + # Run in discrete steps (useful for periodic output) + # step[dt=600] # Run for 10 minutes + # print[front_t600.geojson]@t=600 # Output using scheduler + # step[dt=600] # Run for another 10 minutes + # print[front_t1200.geojson]@t=1200 + # ... + +7. **Generate Outputs:** Save the simulation results. + + .. code-block:: none + + # Save final front geometry (format set by dumpMode parameter) + print[final_front.geojson] + + # Save final arrival time map to NetCDF + save[] # Uses default filename pattern ForeFire..nc + + # Plot a specific variable to an image + # plot[parameter=arrival_time_of_front;filename=arrival_map.png] + + +Complete Example (`real_case.ff`) +--------------------------------- + +The file ``tests/runff/real_case.ff`` serves as a complete, working example demonstrating many of these concepts in practice. After understanding the basics outlined here and consulting the :doc:`Command ` and :doc:`Parameter ` references, studying ``real_case.ff`` is highly recommended. \ No newline at end of file From 5cea0f935b70c5340e44a4db50c726ffba864d36 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Mon, 28 Apr 2025 18:27:17 -0300 Subject: [PATCH 03/13] core concepts --- docs/source/index.rst | 1 + docs/source/reference/parameters.rst | 4 + docs/source/user_guide/core_concepts.rst | 116 +++++++++++++++++++++++ 3 files changed, 121 insertions(+) create mode 100644 docs/source/user_guide/core_concepts.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 27aa4dac..8df5479e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,6 +25,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire user_guide/fuels_file user_guide/landscape_file user_guide/forefire_script + user_guide/core_concepts .. toctree:: :maxdepth: 2 diff --git a/docs/source/reference/parameters.rst b/docs/source/reference/parameters.rst index 29e7f53b..4ce368d6 100644 --- a/docs/source/reference/parameters.rst +++ b/docs/source/reference/parameters.rst @@ -111,6 +111,8 @@ InitTime Domain & Discretization ~~~~~~~~~~~~~~~~~~~~~~~ +.. _param-perimeterResolution: + perimeterResolution """"""""""""""""""" * **Description:** Target maximum distance (in meters) between adjacent FireNodes discretizing the fire front. The simulation dynamically adds nodes to maintain this resolution. @@ -165,6 +167,8 @@ frontDepthScheme Physics & Models ~~~~~~~~~~~~~~~~ +.. _param-propagationModel: + propagationModel """""""""""""""" * **Description:** Name of the primary Rate of Spread (ROS) model to use for calculating fire spread speed (e.g., `Iso`, `Rothermel`, `Balbi`). Specific models may have their own parameters (e.g., `Iso.speed`). diff --git a/docs/source/user_guide/core_concepts.rst b/docs/source/user_guide/core_concepts.rst new file mode 100644 index 00000000..82cdad60 --- /dev/null +++ b/docs/source/user_guide/core_concepts.rst @@ -0,0 +1,116 @@ +.. _userguide-core-concepts: + +Core Concepts +============= + +Understanding the fundamental concepts behind ForeFire can help you use the simulator more effectively and interpret its behavior and outputs. This page provides a high-level overview of the key components and the simulation process. + +Simulation Engine & Interpreter +------------------------------- + +As discussed in the :doc:`/introduction`, ForeFire consists of: + +1. **Simulation Engine** (Library ``libforefireL``): The core C++ code containing the physics, data structures, and algorithms for simulating fire spread. +2. **Interpreter** (Executable ``forefire``): The program you typically interact with. It reads commands (from scripts, console, or web UI) and instructs the engine library what to do. + +This separation allows ForeFire to be used both as a standalone tool (via the interpreter) and as a component linked into other software (like atmospheric models). + +Key Simulation Components +------------------------- + +The simulation engine relies on several key C++ components (classes) to manage the fire spread process: + +* **`Simulator` & `TimeTable` (Event-Driven Core)** + + * ForeFire uses an **event-driven** approach. Instead of fixed time steps for the entire simulation, it maintains a `TimeTable` (a prioritized queue) of future events. + * Each event typically corresponds to a `FireNode` needing an update at a specific future time. + * The `Simulator` processes events from the `TimeTable` in chronological order. It retrieves the next event, tells the associated object (like a `FireNode`) to update its state and calculate its next move, and then the object schedules its *next* update event back into the `TimeTable`. + * **This event-driven approach means the simulation doesn't use fixed global time steps; different parts of the front can advance according to their own calculated timings.** + +* **`FireDomain` (The Simulation World)** + + * Represents the overall simulation area and context. + * Manages the simulation's current time. + * Defines the spatial boundaries (often derived from the :doc:`/user_guide/landscape_file`). + * Contains the `DataBroker` to access environmental data. + * Owns the main `FireFront` (s). + * Manages the `TimeTable` of simulation events. + * May handle discretization of the domain into cells (e.g., for flux calculations or burning map outputs). + +* **`FireFront` & `FireNode` (Representing the Fire)** + + * ForeFire uses a **Lagrangian** approach to track the fire's edge. + * A `FireFront` represents a continuous segment of the fire perimeter. It is essentially a linked list of `FireNode` objects. + * A `FireNode` is a point (marker) on the fire front. It has properties like: + + * Location (x, y, z coordinates) + * Velocity (calculated based on local conditions) + * Normal vector (direction perpendicular to the front) + * Curvature and potentially front depth + * When a `FireNode`'s event occurs, it calculates its propagation speed based on local environmental data and the chosen :ref:`propagation model `, determines its next location, and schedules its next update. + * The `FireDomain` monitors the `FireNode` s to handle topological changes: + + * **Adding nodes:** When nodes spread too far apart (controlled by :ref:`perimeterResolution `), new nodes are inserted. + * **Merging:** When different parts of a `FireFront` touch, they merge. + * **Splitting:** Not explicitly mentioned in summary, but might occur if front self-intersects or hits complex boundaries. + * **Inner Fronts:** `FireFront` s can be nested to represent unburned islands within the main fire perimeter. + +* **`DataBroker` & `DataLayer` (Accessing Environmental Data)** + + * The `DataBroker` is the central hub for all environmental data needed by the simulation (terrain, fuel, weather). + * It manages a collection of `DataLayer` objects. Each `DataLayer` provides access to a specific type of data (e.g., elevation, fuel index, wind speed). + * **Data layers can also manage which specific physical model (e.g., which heat flux calculation) applies at different locations, often based on index maps read from the input files.** + * Different `DataLayer` subclasses handle various data sources and formats: + + * Loading grids from the NetCDF :doc:`/user_guide/landscape_file`. + * Handling constant values across the domain (e.g., constant wind). + * Calculating gradients (like slope/aspect from elevation). + * Accessing the computed arrival time map (Burning Map). + * Interpolating data in space and potentially time (e.g., for time-varying wind fields). + * When a `FireNode` needs environmental data to calculate its speed, it asks the `DataBroker`, which efficiently retrieves the necessary values from the relevant `DataLayer` (s) at the node's location. + +* **`PropagationModel` & `FluxModel` (The Physics)** + + * ForeFire uses a **Strategy pattern** for physical calculations, allowing different models to be plugged in. + * `PropagationModel` subclasses (e.g., `Rothermel`, `Balbi`, `Iso`) implement specific algorithms to calculate the Rate of Spread (ROS) based on properties fetched via the `DataBroker`. The active model is chosen using the :ref:`propagationModel ` parameter. + * `FluxModel` subclasses (e.g., `HeatFluxBasicModel`) calculate fluxes (like heat, water vapor) from the burning area, often needed for coupled simulations or specific research outputs. + +* **`SimulationParameters` (Configuration)** + + * A central place (likely a Singleton class internally) holding the global configuration values set by the user via :ref:`setParameter ` or :ref:`setParameters ` commands. This includes things like model choices, resolution parameters, output settings, etc. + +Simulation Workflow Summary +--------------------------- + +1. **Initialization:** + + * The `forefire` interpreter starts. + * Commands from a script file (or interactive input) are processed. + * :doc:`Parameters ` are set. + * The :ref:`FireDomain ` is created. + * :ref:`loadData ` populates the `DataBroker` with `DataLayer`s from the :doc:`/user_guide/landscape_file`. The :doc:`/user_guide/fuels_file` information is associated. + * The initial fire state is defined using :ref:`startFire ` or custom `FireFront`/`FireNode` commands, scheduling the first update events for the initial nodes into the `TimeTable`. + +2. **Simulation Loop (driven by `step` or `goTo`):** + + * The `Simulator` gets the chronologically next event (usually a `FireNode` update) from the `TimeTable`. + * The `Simulator` advances the global simulation time to the event time. + * The `Simulator` calls the update method on the `FireNode`. + * The `FireNode` calculates its new position based on its previously calculated velocity. + * The `FireDomain` checks for topological changes (node spacing, potential merges). + * The `Simulator` calls the time-advance method on the `FireNode`. + * The `FireNode`: + + * Determines its local normal vector and curvature. + * Requests necessary environmental properties (fuel type, slope, wind, etc.) from the `DataBroker` for its current location. + * Calls the active `PropagationModel`'s `getSpeed()` method with these properties. + * Calculates its new velocity and intended next location. + * Determines its next update time based on speed and resolution parameters. + * Schedules its next update event back into the `TimeTable`. + * This loop continues until the target time specified by :ref:`goTo ` is reached, the duration specified by :ref:`step ` elapses, or the `TimeTable` becomes empty. + +3. **Output:** + + * Commands like :ref:`print `, :ref:`save `, or :ref:`plot ` are executed (either when encountered in the script or scheduled via :ref:`@t=... `) to query the state of the `FireFront` (s) or `DataLayer` (s) (like the burning map) and write them to files. + +Understanding these core concepts provides context for the various commands, parameters, and input files required to run a ForeFire simulation. \ No newline at end of file From 1292aa788e7235d395a2184b0a7df0aa37b3a0c7 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Mon, 28 Apr 2025 18:46:57 -0300 Subject: [PATCH 04/13] folders to strcuture --- docs/source/{ => getting_started}/installation.rst | 0 docs/source/{ => getting_started}/introduction.rst | 0 docs/source/{ => getting_started}/quickstart.rst | 0 docs/source/{ => getting_started}/running_the_example.rst | 8 ++++---- docs/source/index.rst | 8 ++++---- docs/source/user_guide/core_concepts.rst | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) rename docs/source/{ => getting_started}/installation.rst (100%) rename docs/source/{ => getting_started}/introduction.rst (100%) rename docs/source/{ => getting_started}/quickstart.rst (100%) rename docs/source/{ => getting_started}/running_the_example.rst (93%) diff --git a/docs/source/installation.rst b/docs/source/getting_started/installation.rst similarity index 100% rename from docs/source/installation.rst rename to docs/source/getting_started/installation.rst diff --git a/docs/source/introduction.rst b/docs/source/getting_started/introduction.rst similarity index 100% rename from docs/source/introduction.rst rename to docs/source/getting_started/introduction.rst diff --git a/docs/source/quickstart.rst b/docs/source/getting_started/quickstart.rst similarity index 100% rename from docs/source/quickstart.rst rename to docs/source/getting_started/quickstart.rst diff --git a/docs/source/running_the_example.rst b/docs/source/getting_started/running_the_example.rst similarity index 93% rename from docs/source/running_the_example.rst rename to docs/source/getting_started/running_the_example.rst index f981583f..e303f9dc 100644 --- a/docs/source/running_the_example.rst +++ b/docs/source/getting_started/running_the_example.rst @@ -15,7 +15,7 @@ The directory ``tests/runff/`` contains the necessary files for the ``real_case. - ``data.nc``: The NetCDF **landscape file** containing geospatial data (elevation, fuel types) for the simulation domain. - ``fuels.csv``: The **fuels definition file**, specifying properties for different fuel types referenced in ``data.nc``. -The ``real_case.ff`` file itself contains a sequence of ForeFire commands that set up parameters, load data, define an ignition, run the simulation, and save results. To learn about the syntax, structure, and typical commands used within a ``.ff`` script file, please refer to the :doc:`ForeFire Script File guide `. +The ``real_case.ff`` file itself contains a sequence of ForeFire commands that set up parameters, load data, define an ignition, run the simulation, and save results. To learn about the syntax, structure, and typical commands used within a ``.ff`` script file, please refer to the :doc:`ForeFire Script File guide `. Executing the Example Script ---------------------------- @@ -128,6 +128,6 @@ Next Steps Now that you've seen the different ways to *execute* a ForeFire script, you can learn more about: -- How to **write and structure** your own scripts in the :doc:`ForeFire Script File guide `. -- The specific :doc:`Input Files ` required (Fuels, Landscape). -- The detailed :doc:`Command ` and :doc:`Parameter ` references. \ No newline at end of file +- How to **write and structure** your own scripts in the :doc:`ForeFire Script File guide `. +- The specific :doc:`Input Files ` required (Fuels, Landscape). +- The detailed :doc:`Command ` and :doc:`Parameter ` references. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 8df5479e..d0a7e6ef 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,10 +12,10 @@ Welcome to the official documentation for ForeFire — the open-source wildfire :maxdepth: 2 :caption: Getting Started - introduction - quickstart - installation - running_the_example + getting_started/introduction + getting_started/quickstart + getting_started/installation + getting_started/running_the_example .. toctree:: :maxdepth: 2 diff --git a/docs/source/user_guide/core_concepts.rst b/docs/source/user_guide/core_concepts.rst index 82cdad60..4592d368 100644 --- a/docs/source/user_guide/core_concepts.rst +++ b/docs/source/user_guide/core_concepts.rst @@ -8,7 +8,7 @@ Understanding the fundamental concepts behind ForeFire can help you use the simu Simulation Engine & Interpreter ------------------------------- -As discussed in the :doc:`/introduction`, ForeFire consists of: +As discussed in the :doc:`/getting_started/introduction`, ForeFire consists of: 1. **Simulation Engine** (Library ``libforefireL``): The core C++ code containing the physics, data structures, and algorithms for simulating fire spread. 2. **Interpreter** (Executable ``forefire``): The program you typically interact with. It reads commands (from scripts, console, or web UI) and instructs the engine library what to do. From f450049245a506fc9545e27bc20999cf52acbfc9 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Mon, 28 Apr 2025 19:01:01 -0300 Subject: [PATCH 05/13] docs improvement --- docs/source/getting_started/installation.rst | 7 ++++++- docs/source/getting_started/introduction.rst | 2 +- docs/source/getting_started/quickstart.rst | 2 +- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 4c8440e3..8fb4dc5e 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -87,7 +87,12 @@ Use this method if you are not on Debian/Ubuntu, prefer manual control, or don't cmake .. make -The main executable `forefire` will be located at `../bin/forefire` (relative to the `build` directory). +The main executable `forefire` will be located at `../bin/forefire` (relative to the `build` directory). Check installation with + + .. code-block:: bash + + cd .. # Go back to the root of the repository + ./bin/forefire -v 4. **Making ForeFire Executable System-Wide (Manual PATH setup)** diff --git a/docs/source/getting_started/introduction.rst b/docs/source/getting_started/introduction.rst index c4987c9c..edae4ff1 100644 --- a/docs/source/getting_started/introduction.rst +++ b/docs/source/getting_started/introduction.rst @@ -47,7 +47,7 @@ ForeFire is suitable for a range of applications, including: Supported Platforms ------------------- -ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. +ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. It can run o Windows via WSL (windows Subsystem for Linux) or Docker. About This Documentation ------------------------ diff --git a/docs/source/getting_started/quickstart.rst b/docs/source/getting_started/quickstart.rst index c694661d..11e5f13a 100644 --- a/docs/source/getting_started/quickstart.rst +++ b/docs/source/getting_started/quickstart.rst @@ -1,7 +1,7 @@ Quick Start =========== -This guide shows the quickest way to **see ForeFire in action** using its interactive web console, powered by **Docker**. This method bundles all dependencies, so you don't need to install them on your host system, and is the only way to run ForeFire on Windows. +This guide shows the quickest way to get the standard **ForeFire example simulation running** using its interactive web console, powered by Docker. This method bundles all dependencies, so you don't need to install them on your host system, and is the only way to run ForeFire on Windows. Prerequisites ------------- From c6677af70710817f8fc98b24edf32d5ee4ed8ebe Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Mon, 28 Apr 2025 19:07:44 -0300 Subject: [PATCH 06/13] better intro --- docs/source/getting_started/introduction.rst | 54 +++++++++++--------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/source/getting_started/introduction.rst b/docs/source/getting_started/introduction.rst index edae4ff1..e997f231 100644 --- a/docs/source/getting_started/introduction.rst +++ b/docs/source/getting_started/introduction.rst @@ -10,54 +10,58 @@ What is ForeFire? ForeFire is a powerful, open-source **wildfire simulation engine** written in C++. Its core purpose is to simulate the spread of wildfires over complex terrain using various physical models and geospatial data inputs. -The engine's logic is compiled into a **reusable shared library** (``libforefireL.so``) that can be directly linked against by other C/C++ or Fortran programs. The most common way to use ForeFire is through the ``forefire`` **executable program**. +Architecturally, it consists of two primary components: -This ``forefire`` program acts as a **command-line interpreter**. It reads and executes commands from: +1. **Simulation Engine (Library):** + + The core C++ logic containing the physics, data structures, and simulation algorithms. This is compiled into a **reusable shared library** (``libforefireL.so``/``.dylib``) which can be directly linked by other programs (e.g., for atmospheric coupling). -* Script files (typically `.ff` files) -* An interactive console session -* An HTTP server interface (activated by the ``listenHTTP[]`` command, powering the web UI) +2. **Interpreter (Executable):** + + The ``forefire`` program acts as the primary user interface. It's a **command-line interpreter** that reads instructions and directs the underlying Simulation Engine. Users interact with the interpreter via: -These commands instruct the underlying library engine to perform actions like loading data, setting parameters, defining ignitions, and advancing the simulation state over time. + - Script files (``.ff``) + - Interactive console commands + - A web UI (powered by the ``listenHTTP[]`` command) -This structure allows ForeFire to be both a versatile standalone simulation tool and a computational engine integrable into larger modeling systems. +This separation allows ForeFire to function both as a standalone simulation tool and as an embeddable computational engine for larger systems. Key Capabilities ---------------- -* **Physics-Based Simulation:** Implements established Rate of Spread (ROS) models (e.g., based on Rothermel equations) and provides a framework for adding custom models. -* **Geospatial Data Handling:** Natively uses NetCDF files for input data layers such as elevation, fuel type, and weather variables. -* **Fire-Atmosphere Coupling:** Explicitly designed for two-way coupling with atmospheric models (e.g., MesoNH) to capture crucial wind-fire interactions. -* **High-Performance Computing:** The C++ core is optimized for performance, and MPI support enables efficient parallel execution on multi-core systems and clusters, allowing for large-scale and faster-than-real-time simulations. -* **Multiple Interaction Modes:** Accessible via command-line scripts, an interactive console, a web-based visualization interface, direct C++ library linking, and potentially Python bindings. -* **Extensibility:** Users can implement and integrate their own C++ modules for specific fire behavior (ROS) or flux calculations. -* **Open Source:** Developed under the GPLv3 license, fostering transparency and community contributions. +- **Physics-Based Simulation:** Implements established Rate of Spread (ROS) models (e.g., based on Rothermel equations) and provides a framework for adding custom models. +- **Geospatial Data Handling:** Natively uses NetCDF files for input data layers such as elevation, fuel type, and weather variables. +- **Fire-Atmosphere Coupling:** Explicitly designed for two-way coupling with atmospheric models (e.g., MesoNH) to capture crucial wind-fire interactions. +- **High-Performance Computing:** The C++ core is optimized for performance, and MPI support enables efficient parallel execution on multi-core systems and clusters, allowing for large-scale and faster-than-real-time simulations. +- **Multiple Interaction Modes:** Accessible via command-line scripts, an interactive console, a web-based visualization interface, direct C++ library linking, and potentially Python bindings. +- **Extensibility:** Users can implement and integrate their own C++ modules for specific fire behavior (ROS) or flux calculations. +- **Open Source:** Developed under the GPLv3 license, fostering transparency and community contributions. Intended Use Cases ------------------ ForeFire is suitable for a range of applications, including: -* Wildfire behavior research -* Detailed reanalysis of past fire events -* Operational or near-real-time fire spread forecasting (standalone or ensemble) -* Investigating fire-atmosphere interactions through coupled simulations -* Testing and comparing different fire spread models +- Wildfire behavior research +- Detailed reanalysis of past fire events +- Operational or near-real-time fire spread forecasting (standalone or ensemble) +- Investigating fire-atmosphere interactions through coupled simulations +- Testing and comparing different fire spread models Supported Platforms ------------------- -ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. It can run o Windows via WSL (windows Subsystem for Linux) or Docker. +ForeFire is primarily developed and tested on **Unix-like systems (Linux and macOS)**. It can run o Windows via **WSL** (windows Subsystem for Linux) or **Docker**. About This Documentation ------------------------ This documentation aims to provide comprehensive guidance for users and developers. It is organized into the following main sections: -* **Getting Started:** Installation, quick start guides, and running basic examples. -* **User Guide:** Explanations of core concepts, configuration files, and common workflows. -* **Reference:** Detailed reference material for commands, parameters, and file formats. -* **API Reference:** Documentation for the C++ library classes and functions (generated from source code). -* **About:** License, citation information, and acknowledgements. +- **Getting Started:** Installation, quick start guides, and running basic examples. +- **User Guide:** Explanations of core concepts, configuration files, and common workflows. +- **Reference:** Detailed reference material for commands, parameters, and file formats. +- **API Reference:** Documentation for the C++ library classes and functions (generated from source code). +- **About:** License, citation information, and acknowledgements. We recommend starting with the :doc:`quickstart` or :doc:`installation` guides. \ No newline at end of file From 8f330ef0295590bebbd8d6ecce0c2fd950ec1424 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Mon, 28 Apr 2025 19:12:40 -0300 Subject: [PATCH 07/13] correct ident --- docs/source/user_guide/forefire_script.rst | 36 +++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/source/user_guide/forefire_script.rst b/docs/source/user_guide/forefire_script.rst index 226c56e7..cf7cc20b 100644 --- a/docs/source/user_guide/forefire_script.rst +++ b/docs/source/user_guide/forefire_script.rst @@ -41,17 +41,17 @@ Certain commands, specifically :ref:`FireFront ` and :ref:`FireNo - An inner ``FireFront`` (representing an unburned island within another `FireFront`) would be indented relative to its parent `FireFront`. .. code-block:: none - :caption: Example Indentation for Custom Front + :caption: Example Indentation for Custom Front - # FireDomain defined earlier or implicitly... + # FireDomain defined earlier or implicitly... - # Indented FireFront (e.g., 4 spaces) - FireFront[t=0] - # Further indented FireNode (e.g., 8 spaces total) - FireNode[loc=(100,100,0);t=0] - FireNode[loc=(200,100,0);t=0] - FireNode[loc=(150,150,0);t=0] - # ... potentially more nodes defining the outer perimeter + # Indented FireFront (e.g., 4 spaces) + FireFront[t=0] + # Further indented FireNode (e.g., 8 spaces total) + FireNode[loc=(100,100,0);t=0] + FireNode[loc=(200,100,0);t=0] + FireNode[loc=(150,150,0);t=0] + # ... potentially more nodes defining the outer perimeter .. important:: @@ -93,17 +93,17 @@ While the exact commands depend on the simulation, a common workflow within a `` .. code-block:: none - # Simple point ignition - startFire[lonlat=(9.1, 42.2); t=0] # Using geographic coordinates + # Simple point ignition + startFire[lonlat=(9.1, 42.2); t=0] # Using geographic coordinates - # --- OR --- + # --- OR --- - # Custom initial front (using projected coords and indentation) - # Ensure FireDomain covers these coordinates - # FireFront[t=0] - # FireNode[loc=(2500,3000,150);t=0] - # FireNode[loc=(2600,3000,150);t=0] - # FireNode[loc=(2550,3100,150);t=0] + # Custom initial front (using projected coords and indentation) + # Ensure FireDomain covers these coordinates + # FireFront[t=0] + # FireNode[loc=(2500,3000,150);t=0] + # FireNode[loc=(2600,3000,150);t=0] + # FireNode[loc=(2550,3100,150);t=0] 5. **Set Dynamic Conditions (Optional):** Introduce time-varying inputs, like wind changes. From 7e99622056fd88b73ef7c9180baeb93628c79da6 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 29 Apr 2025 00:08:26 -0300 Subject: [PATCH 08/13] compile code script --- .gitignore | 1 + tools/ai/compile.py | 131 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 tools/ai/compile.py diff --git a/.gitignore b/.gitignore index 2b79d65f..4e45b87f 100644 --- a/.gitignore +++ b/.gitignore @@ -49,3 +49,4 @@ tests/python/log.txt tests/python/runROS.bash changeLicense.py httpConnectInfo.txt +compiled_code.txt diff --git a/tools/ai/compile.py b/tools/ai/compile.py new file mode 100644 index 00000000..ebb24eef --- /dev/null +++ b/tools/ai/compile.py @@ -0,0 +1,131 @@ +import os +import sys + + +input_folder_path = '../../src' + +output_txt_filename = 'compiled_code.txt' + +allowed_extensions = [ + '.cpp', + '.h', + '.py', + '.ts', + '.html', + # '.scss', + # '.css', + '.js', + '.tex', + '.rst', +] +allowed_extensions = [ext.lower() for ext in allowed_extensions] + +excluded_folders_exact = [ + 'build', + 'lib', + '.git', + '.vscode', + 'node_modules', + 'dist', + # Add any other specific folder names to ignore by exact match +] + +# 5. Folders containing "env" (case-insensitive) will ALSO be excluded automatically. + +# 6. Customize the separator written between files in the output .txt +separator_template = "\n\n---=== File: {filepath} ===---\n\n" +# --- End of Configuration --- + + +# --- Script Logic --- + +def compile_code_to_txt(root_folder, output_txt, extensions, exclusions_exact, separator_fmt): + """ + Recursively finds files with specified extensions in root_folder, + excluding specified subfolders (by exact match or containing 'env'), + and compiles their relative path and content into a single text file. + """ + # --- Input Validation --- + if not os.path.isdir(root_folder): + print(f"Error: Input folder not found: '{root_folder}'") + return + + # Convert exact exclusions to a set for faster lookups + exclusion_set_exact = set(exclusions_exact) + # Convert extensions to a tuple for faster 'endswith' check + extension_tuple = tuple(extensions) + + found_files_count = 0 + processed_files_count = 0 + skipped_encoding_errors = 0 + + print(f"Starting scan in: '{root_folder}'") + print(f"Including extensions: {', '.join(extensions)}") + print(f"Excluding folders by exact match: {', '.join(exclusions_exact)}") + print(f"Excluding any folder containing 'env' (case-insensitive).") # Added clarification + print(f"Outputting to: '{output_txt}'") + + try: + with open(output_txt, 'w', encoding='utf-8') as outfile: + print(f"\nCompiling into '{output_txt}'...") + + for current_path, dirs, files in os.walk(root_folder, topdown=True): + + # --- Prune Excluded Directories --- + # Modify 'dirs' in-place to prevent os.walk from descending into them + # Exclude if name is in exclusion_set_exact OR if name contains "env" (case-insensitive) + dirs[:] = [d for d in dirs if d not in exclusion_set_exact and "env" not in d.lower()] + files.sort() + + for filename in files: + if filename.lower().endswith(extension_tuple): + found_files_count += 1 + file_path = os.path.join(current_path, filename) + relative_path = os.path.relpath(file_path, root_folder) + relative_path = relative_path.replace(os.sep, '/') + + print(f" Adding: {relative_path}") + + try: + content = "" + try: + with open(file_path, 'r', encoding='utf-8') as infile: + content = infile.read() + except UnicodeDecodeError: + try: + with open(file_path, 'r', encoding='latin-1') as infile: + content = infile.read() + except Exception as enc_err: + print(f" - Error: Could not decode file '{relative_path}'. Skipping. Error: {enc_err}") + skipped_encoding_errors += 1 + continue + + outfile.write(separator_fmt.format(filepath=relative_path)) + outfile.write(content) + processed_files_count += 1 + + except Exception as e: + print(f" - Error processing file '{relative_path}': {e}. Skipping this file.") + + print("\n--- Compilation Summary ---") + print(f"Scan complete.") + print(f"Total files found matching extensions: {found_files_count}") + print(f"Files successfully processed and added to TXT: {processed_files_count}") + if skipped_encoding_errors > 0: + print(f"Files skipped due to encoding errors: {skipped_encoding_errors}") + print(f"Output saved to '{output_txt}'") + if found_files_count == 0: + print("Warning: No files matching the specified extensions were found in the target folder (after exclusions).") + + except Exception as e: + print(f"\nFatal Error writing to output file '{output_txt}': {e}") + sys.exit(1) + +# --- Run the function --- +if __name__ == "__main__": + if input_folder_path == 'your_angular_project_folder' or not input_folder_path: + print("Error: Please update the 'input_folder_path' variable in the script!") + print(" Set it to the directory you want to scan.") + else: + # Renamed variable for clarity + compile_code_to_txt(input_folder_path, output_txt_filename, allowed_extensions, excluded_folders_exact, separator_template) \ No newline at end of file From 4dbe5069e5ad2e9e9edd8369661cb51cc4ee4415 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 29 Apr 2025 11:24:56 -0300 Subject: [PATCH 09/13] rm ai file --- tools/ai/compile.py | 131 -------------------------------------------- 1 file changed, 131 deletions(-) delete mode 100644 tools/ai/compile.py diff --git a/tools/ai/compile.py b/tools/ai/compile.py deleted file mode 100644 index ebb24eef..00000000 --- a/tools/ai/compile.py +++ /dev/null @@ -1,131 +0,0 @@ -import os -import sys - - -input_folder_path = '../../src' - -output_txt_filename = 'compiled_code.txt' - -allowed_extensions = [ - '.cpp', - '.h', - '.py', - '.ts', - '.html', - # '.scss', - # '.css', - '.js', - '.tex', - '.rst', -] -allowed_extensions = [ext.lower() for ext in allowed_extensions] - -excluded_folders_exact = [ - 'build', - 'lib', - '.git', - '.vscode', - 'node_modules', - 'dist', - # Add any other specific folder names to ignore by exact match -] - -# 5. Folders containing "env" (case-insensitive) will ALSO be excluded automatically. - -# 6. Customize the separator written between files in the output .txt -separator_template = "\n\n---=== File: {filepath} ===---\n\n" -# --- End of Configuration --- - - -# --- Script Logic --- - -def compile_code_to_txt(root_folder, output_txt, extensions, exclusions_exact, separator_fmt): - """ - Recursively finds files with specified extensions in root_folder, - excluding specified subfolders (by exact match or containing 'env'), - and compiles their relative path and content into a single text file. - """ - # --- Input Validation --- - if not os.path.isdir(root_folder): - print(f"Error: Input folder not found: '{root_folder}'") - return - - # Convert exact exclusions to a set for faster lookups - exclusion_set_exact = set(exclusions_exact) - # Convert extensions to a tuple for faster 'endswith' check - extension_tuple = tuple(extensions) - - found_files_count = 0 - processed_files_count = 0 - skipped_encoding_errors = 0 - - print(f"Starting scan in: '{root_folder}'") - print(f"Including extensions: {', '.join(extensions)}") - print(f"Excluding folders by exact match: {', '.join(exclusions_exact)}") - print(f"Excluding any folder containing 'env' (case-insensitive).") # Added clarification - print(f"Outputting to: '{output_txt}'") - - try: - with open(output_txt, 'w', encoding='utf-8') as outfile: - print(f"\nCompiling into '{output_txt}'...") - - for current_path, dirs, files in os.walk(root_folder, topdown=True): - - # --- Prune Excluded Directories --- - # Modify 'dirs' in-place to prevent os.walk from descending into them - # Exclude if name is in exclusion_set_exact OR if name contains "env" (case-insensitive) - dirs[:] = [d for d in dirs if d not in exclusion_set_exact and "env" not in d.lower()] - files.sort() - - for filename in files: - if filename.lower().endswith(extension_tuple): - found_files_count += 1 - file_path = os.path.join(current_path, filename) - relative_path = os.path.relpath(file_path, root_folder) - relative_path = relative_path.replace(os.sep, '/') - - print(f" Adding: {relative_path}") - - try: - content = "" - try: - with open(file_path, 'r', encoding='utf-8') as infile: - content = infile.read() - except UnicodeDecodeError: - try: - with open(file_path, 'r', encoding='latin-1') as infile: - content = infile.read() - except Exception as enc_err: - print(f" - Error: Could not decode file '{relative_path}'. Skipping. Error: {enc_err}") - skipped_encoding_errors += 1 - continue - - outfile.write(separator_fmt.format(filepath=relative_path)) - outfile.write(content) - processed_files_count += 1 - - except Exception as e: - print(f" - Error processing file '{relative_path}': {e}. Skipping this file.") - - print("\n--- Compilation Summary ---") - print(f"Scan complete.") - print(f"Total files found matching extensions: {found_files_count}") - print(f"Files successfully processed and added to TXT: {processed_files_count}") - if skipped_encoding_errors > 0: - print(f"Files skipped due to encoding errors: {skipped_encoding_errors}") - print(f"Output saved to '{output_txt}'") - if found_files_count == 0: - print("Warning: No files matching the specified extensions were found in the target folder (after exclusions).") - - except Exception as e: - print(f"\nFatal Error writing to output file '{output_txt}': {e}") - sys.exit(1) - -# --- Run the function --- -if __name__ == "__main__": - if input_folder_path == 'your_angular_project_folder' or not input_folder_path: - print("Error: Please update the 'input_folder_path' variable in the script!") - print(" Set it to the directory you want to scan.") - else: - # Renamed variable for clarity - compile_code_to_txt(input_folder_path, output_txt_filename, allowed_extensions, excluded_folders_exact, separator_template) \ No newline at end of file From 117efeeba2693a78609855c85630c8f449853418 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 29 Apr 2025 11:25:40 -0300 Subject: [PATCH 10/13] ignore ai folder --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 4e45b87f..3a481649 100644 --- a/.gitignore +++ b/.gitignore @@ -49,4 +49,4 @@ tests/python/log.txt tests/python/runROS.bash changeLicense.py httpConnectInfo.txt -compiled_code.txt +tools/ai From 4989883231897833203bf799f9561087dd47d346 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 29 Apr 2025 11:47:24 -0300 Subject: [PATCH 11/13] depth 1 only --- docs/source/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index d0a7e6ef..5212cd11 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,7 +9,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire - `Online Demo Simulator `_ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Getting Started getting_started/introduction @@ -18,7 +18,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire getting_started/running_the_example .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: User Guide user_guide/basic_configuration @@ -28,7 +28,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire user_guide/core_concepts .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Reference reference/commands From 77c94dc5daeac453282a9e979182371ded2a4303 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 29 Apr 2025 13:26:54 -0300 Subject: [PATCH 12/13] orange css --- docs/source/_static/custom.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css index 5f1efcc5..41a09d94 100644 --- a/docs/source/_static/custom.css +++ b/docs/source/_static/custom.css @@ -1,4 +1,8 @@ .wy-nav-side .wy-menu-vertical header, .wy-nav-side .wy-menu-vertical p.caption { color: #F86C23 !important; +} + +.wy-nav-side .wy-menu-vertical a:active { + background-color: rgba(248, 108, 35, 0.4) !important; } \ No newline at end of file From 109fd2cfa6894d622b4d822281acfe3e45814a75 Mon Sep 17 00:00:00 2001 From: antonio-leblanc Date: Tue, 29 Apr 2025 14:37:14 -0300 Subject: [PATCH 13/13] forefire repo name --- README.md | 6 +++--- bindings/python/README.md | 4 ++-- bindings/python/pyproject.toml | 4 ++-- docs/source/about/license.rst | 2 +- docs/source/getting_started/installation.rst | 4 ++-- docs/source/getting_started/quickstart.rst | 2 +- docs/source/index.rst | 2 +- 7 files changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 7d0a5380..aa78e237 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ --- -[![linuxCI](https://github.com/forefireAPI/firefront/actions/workflows/main.yml/badge.svg)](https://github.com/forefireAPI/firefront/actions/workflows/main.yml) -[![macOSCI](https://github.com/forefireAPI/firefront/actions/workflows/macos.yml/badge.svg)](https://github.com/forefireAPI/firefront/actions/workflows/macos.yml) +[![linuxCI](https://github.com/forefireAPI/forefire/actions/workflows/main.yml/badge.svg)](https://github.com/forefireAPI/forefire/actions/workflows/main.yml) +[![macOSCI](https://github.com/forefireAPI/forefire/actions/workflows/macos.yml/badge.svg)](https://github.com/forefireAPI/forefire/actions/workflows/macos.yml) [![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) @@ -45,7 +45,7 @@ The easiest way to get started is often using Docker and the interactive console ``` bash # Clone the repository - git clone https://github.com/forefireAPI/firefront.git + git clone https://github.com/forefireAPI/forefire.git cd firefront ``` diff --git a/bindings/python/README.md b/bindings/python/README.md index 4b1b65d3..883fa44f 100644 --- a/bindings/python/README.md +++ b/bindings/python/README.md @@ -115,5 +115,5 @@ This project is licensed under the terms specified in the `LICENSE` file. ## Project URLs -- **Homepage:** [https://github.com/forefireAPI/firefront](https://github.com/forefireAPI/firefront) -- **Repository:** [https://github.com/forefireAPI/firefront](https://github.com/forefireAPI/firefront) +- **Homepage:** [https://github.com/forefireAPI/forefire](https://github.com/forefireAPI/forefire) +- **Repository:** [https://github.com/forefireAPI/forefire](https://github.com/forefireAPI/forefire) diff --git a/bindings/python/pyproject.toml b/bindings/python/pyproject.toml index 5fd4d24c..ecfd9e1d 100644 --- a/bindings/python/pyproject.toml +++ b/bindings/python/pyproject.toml @@ -25,5 +25,5 @@ classifiers = [ ] [project.urls] -Homepage = "https://github.com/forefireAPI/firefront" -Repository = "https://github.com/forefireAPI/firefront" +Homepage = "https://github.com/forefireAPI/forefire" +Repository = "https://github.com/forefireAPI/forefire" diff --git a/docs/source/about/license.rst b/docs/source/about/license.rst index 19e3c06f..b24e62c6 100644 --- a/docs/source/about/license.rst +++ b/docs/source/about/license.rst @@ -3,4 +3,4 @@ License ForeFire is licensed under the **GNU General Public License v3.0 (GPLv3)**. -You can find the full license text in the `LICENSE `_ file in the root of the project repository. \ No newline at end of file +You can find the full license text in the `LICENSE `_ file in the root of the project repository. \ No newline at end of file diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index 8fb4dc5e..1f15cdf7 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -32,7 +32,7 @@ The repository provides a convenience script (`install-forefire.sh`) that automa .. code-block:: bash - git clone https://github.com/forefireAPI/firefront.git + git clone https://github.com/forefireAPI/forefire.git cd firefront 2. **Run the install script:** @@ -65,7 +65,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/firefront.git + git clone https://github.com/forefireAPI/forefire.git cd firefront 2. **Install Prerequisites Manually:** diff --git a/docs/source/getting_started/quickstart.rst b/docs/source/getting_started/quickstart.rst index 11e5f13a..8c3a59ae 100644 --- a/docs/source/getting_started/quickstart.rst +++ b/docs/source/getting_started/quickstart.rst @@ -15,7 +15,7 @@ Steps .. code-block:: bash - git clone https://github.com/forefireAPI/firefront.git + git clone https://github.com/forefireAPI/forefire.git 2. **Build the Docker image:** diff --git a/docs/source/index.rst b/docs/source/index.rst index 5212cd11..f4b68ad6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,7 +5,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire **Key Links:** -- `GitHub Repository `_ +- `GitHub Repository `_ - `Online Demo Simulator `_ .. toctree::