Init Joss preparation #76

CITATION.cff

@@ -0,0 +1,50 @@
+cff-version: 1.2.0
+message: "If you use ForeFire in your work, please cite it using the metadata below."
+
+authors:
+  - given-names: Jean-Baptiste
+    family-names: Filippi
+    # orcid: https://orcid.org/XXXX-XXXX-XXXX-XXXX # TODO: Add J-B's ORCID (use the full URL format)
+    affiliation: "SPE, UMR 6134, CNRS, University of Corsica Pascal Paoli, Corte, France" # TODO: Verify exact affiliation name
+
+  # TODO: Add any other major contributors who should be listed as authors of the software
+
+title: "ForeFire: An Open-Source C++ Engine for High-Performance Wildfire Simulation"
+
+# version: Use the version number that is being submitted/reviewed.
+version: "2.0.0"
+
+# doi: Uncomment and add the software DOI after archiving the reviewed version on Zenodo/Figshare.
+# Do NOT use the DOI of the 2014 paper here.
+# doi: 10.5281/zenodo.XXXXXXX
+
+# date-released: Set this to the date of the release corresponding to the 'version'.
+date-released: 2025-04-29
+
+url: "https://github.com/forefireAPI/forefire"
+license: GPL-3.0-only
+
+keywords:
+  - C++
+  - Python
+  - wildfire simulation
+  - fire behavior modeling
+  - high-performance computing
+  - fire-atmosphere coupling
+  - numerical modeling
+
+# Optional: Add preferred-citation once the JOSS paper is accepted/published
+# preferred-citation:
+#   type: article
+#   authors:
+#     # List authors of the JOSS paper here, matching paper.md
+#     - given-names: Jean-Baptiste
+#       family-names: Filippi
+#       # orcid: https://orcid.org/XXXX-XXXX-XXXX-XXXX
+#       affiliation: "SPE, UMR 6134, CNRS, University of Corsica Pascal Paoli, Corte, France"
+#   title: "ForeFire: An Open-Source C++ Engine for High-Performance Wildfire Simulation" # Title of the JOSS paper
+#   journal: "Journal of Open Source Software"
+#   # volume: X # JOSS will assign
+#   # issue: Y # JOSS will assign
+#   # year: ZZZZ # Year JOSS paper published
+#   doi: "10.21105/joss.XXXXX" # TODO: Add the JOSS paper DOI once assigned

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at filippi_j@univ-corse.fr.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to ForeFire
+
+First off, thank you for considering contributing to ForeFire! We welcome contributions from the community, whether it's reporting bugs, suggesting enhancements, improving documentation, or submitting code changes.
+
+This document provides guidelines for contributing to the project.
+
+## How Can I Contribute?
+
+*   [Reporting Bugs](#reporting-bugs)
+*   [Suggesting Enhancements](#suggesting-enhancements)
+*   [Contributing Code](#contributing-code)
+*   [Improving Documentation](#improving-documentation)
+
+## Reporting Bugs
+
+If you encounter a bug while using ForeFire, please help us by reporting it! Good bug reports are essential for improving the software.
+
+1.  **Check Existing Issues:** Before submitting a new issue, please search the [GitHub Issues](https://github.com/forefireAPI/forefire/issues) to see if the bug has already been reported.
+2.  **Gather Information:** If the bug hasn't been reported, please gather the following information:
+    *   ForeFire version (`forefire -v`).
+    *   Operating System (e.g., Ubuntu 22.04, macOS Sonoma, WSL on Windows 11).
+    *   Compiler used (if built from source).
+    *   A clear and concise description of the bug.
+    *   Steps to reproduce the bug reliably. Include relevant parts of your `.ff` script file, input data details, or a minimal example if possible.
+    *   What you expected to happen.
+    *   What actually happened (include any error messages or incorrect output).
+3.  **Submit the Issue:** Create a new issue on the [GitHub Issues](https://github.com/forefireAPI/forefire/issues) page, providing the information gathered above. Use a descriptive title.
+
+## Suggesting Enhancements
+
+We are open to suggestions for new features or improvements to existing functionality.
+
+1.  **Check Existing Issues/Discussions:** Search the [GitHub Issues](https://github.com/forefireAPI/forefire/issues) (look for "enhancement" or "feature request" labels) and potentially [GitHub Discussions](https://github.com/forefireAPI/forefire/discussions) (if enabled) to see if your idea has already been discussed.
+2.  **Submit the Suggestion:** If your idea is new, create a new issue on the [GitHub Issues](https://github.com/forefireAPI/forefire/issues) page.
+    *   Use a clear and descriptive title.
+    *   Explain the enhancement you would like to see.
+    *   Describe the motivation or use case for the enhancement (why it would be valuable).
+    *   Provide examples or details on how you envision the feature working, if applicable.
+
+## Contributing Code
+
+We welcome code contributions, from bug fixes to new features.
+
+1.  **Discuss First (for major changes):**
+
+    If you plan to implement a significant new feature or make major changes to the architecture, please open an issue first to discuss your proposal with the development team. This helps ensure your contribution aligns with the project's goals and avoids duplicated effort. For smaller bug fixes, feel free to proceed directly to a Pull Request.
+
+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)*
+
+3.  **Fork the Repository:**
+
+    Create your own fork of the `forefireAPI/forefire` repository on GitHub.
+
+4.  **Create a Branch:**
+
+    Create a new branch in your fork for your changes. Use a descriptive name (e.g., `fix-rothermel-bug`, `feature-add-new-model`).
+    ```bash
+    git checkout -b my-feature-branch
+    ```
+5.  **Make Changes:**
+
+    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.
+    ```bash
+    # Example command to run tests (adjust as needed)
+    cd tests && bash run.bash
+    ```
+7.  **Commit Changes:**
+
+    Commit your changes with clear and concise commit messages.
+    ```bash
+    git add .
+    git commit -m "feat: Implement new flux model calculation"
+    ```
+8.  **Push to Your Fork:**
+
+    Push your branch to your GitHub fork.
+    ```bash
+    git push origin my-feature-branch
+    ```
+9.  **Open a Pull Request (PR):**
+
+    Go to the `forefireAPI/forefire` repository on GitHub and open a Pull Request from your branch to the `dev` branch (or `master` if that's the target).
+    *   Provide a clear description of the changes in the PR.
+    *   Link any relevant issues (e.g., "Fixes #123").
+    *   Ensure the CI checks pass on your PR. The maintainers will review your code, provide feedback, and merge it once approved.
+
+## Improving Documentation
+
+Good documentation is crucial! If you find errors, areas that are unclear, or sections that could be expanded, please help improve it.
+
+*   Documentation source files are located in the `docs/source/` directory.
+*   They are written in reStructuredText (`.rst`).
+*   You can follow the same Fork -> Branch -> Edit -> Pull Request workflow as for code contributions to suggest changes to the documentation files.
+
+## Code of Conduct
+
+All contributors are expected to adhere to the project's [Code of Conduct](CODE_OF_CONDUCT.md). Please be respectful and considerate in all interactions.
+
+Thank you for contributing to ForeFire!

README.md

@@ -13,7 +13,7 @@
 [![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) <!-- Or use Zenodo DOI if available -->
 
 
-**ForeFire** is an open-source **wildfire simulation engine** written in C++. Developed by CNRS at the [Université de Corse Pascal Paoli](https://www.univ-corse.fr/), it is used for research and operational forecasting. The engine implements various fire behavior models, handles complex geospatial data, and enables high-fidelity coupled fire-atmosphere simulations.
+**ForeFire** is an open-source **wildfire simulation engine** written in C++. Developed by CNRS at the [Université de Corse Pascal Paoli](https://www.univ-corse.fr/), it is used for research and operational forecasting. The engine implements various fire behavior models and enables high-fidelity coupled fire-atmosphere simulations, aiming to improve wildfire prediction and understanding for complex environments.
 
 
 **Key Links:**
@@ -46,7 +46,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/forefire.git
-    cd firefront
+    cd forefire
     ```
 
 2. Build the Docker image 
@@ -93,11 +93,17 @@ See the Full Documentation for more details on building from source with the `in
 ForeFire provides Python bindings for easier scripting and integration. See the Python Bindings [./bindings/python/README.md](./bindings/python/README.md) for details.
 
 ## Contributing
-Contributions are welcome! Whether it's reporting a bug, suggesting an enhancement, or submitting code changes. We especially appreciate help with:
+
+We welcome contributions to ForeFire! We especially appreciate help with:
+
 - Improving documentation and tutorials.
 - Python bindings
 - Enhancing packaging (Docker, Pip, etc.) and cross-platform compatibility.
 
+ Please read our **[Contributing Guidelines](CONTRIBUTING.md)** to learn how you can help, including how to report bugs, suggest features, and submit code changes.
+
+All contributors are expected to adhere to our **[Code of Conduct](CODE_OF_CONDUCT.md)**.
+
 
 ## License
 ForeFire is licensed under the GNU General Public License v3.0. See [LICENSE](./LICENSE) for full details.

docs/source/about/statement_of_need.rst

@@ -0,0 +1,33 @@
+.. _about-statement-of-need:
+
+Statement of Need
+=================
+
+**The Problem:** 
+
+Wildfires pose significant environmental, economic, and societal risks globally. Understanding and predicting their behavior requires sophisticated simulation tools capable of handling complex interactions between fire, fuel, weather, and terrain. While various wildfire models exist, challenges remain in areas such as computational performance for large domains, accurate representation of specific physical processes (like fire-atmosphere coupling), and providing flexible platforms for research and operational use.
+
+**ForeFire's Contribution:**
+
+ForeFire was developed by CNRS at the Université de Corse Pascal Paoli to address these needs. It is an open-source (GPLv3) wildfire simulation engine designed for both research and operational applications.
+
+Key motivations and contributions include:
+
+*   **High-Performance Core:** Implemented in C++ with MPI support for efficient parallel execution, enabling large-scale simulations and faster-than-real-time forecasting capabilities essential for operational scenarios.
+*   **Physics-Based Modeling:** Incorporates established Rate of Spread (ROS) models (e.g., Rothermel, Balbi) and provides a framework for researchers to implement and test new or custom models.
+*   **Fire-Atmosphere Coupling:** Explicitly designed with interfaces (via the core C++ library) to enable two-way coupling with atmospheric models like MesoNH. This allows for capturing critical feedback mechanisms where the fire influences local weather (wind, turbulence) which, in turn, affects fire spread.
+*   **Geospatial Data Handling:** Natively utilizes NetCDF for complex landscape and weather inputs, aligning with common scientific data formats.
+*   **Flexible Interfaces:** Offers multiple ways to interact with the engine: a command-line interpreter for scripting (`.ff` files) and interactive use, direct C++ library linking for integration into other systems, and Python bindings for scripting and analysis convenience.
+*   **Open Source Platform:** Provides a transparent, extensible, and community-driven platform for advancing wildfire science and simulation technology.
+
+**Target Audience:**
+
+ForeFire is intended for:
+
+*   **Wildfire Researchers:** Investigating fire behavior, model development, sensitivity analyses, fire-atmosphere interactions.
+*   **Operational Agencies:** Use in forecasting systems (potentially via ensemble simulations), risk assessment, and post-fire analysis.
+*   **Students and Educators:** A tool for learning about wildfire dynamics and simulation techniques.
+
+**Context:**
+
+ForeFire aims to complement and extend the capabilities of other existing wildfire simulation tools by focusing on high-performance computing, advanced physics coupling, and providing a flexible open-source C++ core. *(Mention specific limitations of other tools that ForeFire addresses, if appropriate, and potentially cite 1-2 key alternative tools for comparison).*

docs/source/index.rst

@@ -41,6 +41,7 @@ Welcome to the official documentation for ForeFire — the open-source wildfire
 
    about/license
    about/citation
+   about/statement_of_need
 
 
 .. Indices and tables (Keep these standard Sphinx features)

paper/paper.bib

@@ -0,0 +1,16 @@
+@article{article,
+author = {Filippi, Jean-Baptiste and Bosseur, Frédéric and Grandi, Damien},
+year = {2014},
+month = {11},
+pages = {},
+title = {ForeFire: open-source code for wildland fire spread models},
+isbn = {9789892608846},
+doi = {10.14195/978-989-26-0884-6_29}
+}
+
+% --- PLACEHOLDERS ---
+% J-B Filippi should add other relevant references here, for example:
+% - Key dependencies (e.g., NetCDF library paper, MPI implementation)
+% - Foundational papers describing the physics/models implemented (Rothermel, Balbi, etc.)
+% - Papers describing related/alternative software mentioned in Statement of Need (e.g., FARSITE, WRF-Fire)
+% - Any other papers that have used or cited ForeFire for scientific results.