From 15f310714b07e5add74c69b18fab3d73fcc98834 Mon Sep 17 00:00:00 2001
From: antonio-leblanc <antonioleblanc@poli.ufrj.br>
Date: Wed, 3 Sep 2025 17:36:26 -0300
Subject: [PATCH] update pyforefire example with filippi suggestion on #103

---
 bindings/python/README.md | 48 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 45 insertions(+), 3 deletions(-)

diff --git a/bindings/python/README.md b/bindings/python/README.md
index f109a48a..64c5e8cc 100644
--- a/bindings/python/README.md
+++ b/bindings/python/README.md
@@ -65,7 +65,9 @@ You can build and install the package into your current Python interpreter in ed
 
 ## Usage
 
-After installation, you can use PyForeFire in your Python code as follows:
+### Verifying the Installation
+
+The first step is to confirm that the PyForeFire library was installed and linked correctly. The following code creates a `ForeFire` instance and defines a simulation domain.
 
 ```python
 import pyforefire as forefire
@@ -80,9 +82,49 @@ myCmd = "FireDomain[sw=(0.,0.,0.);ne=(%f,%f,0.);t=0.]" % (sizeX, sizeY)
 
 # Execute the command
 ff.execute(myCmd)
+print("PyForeFire installed and domain created successfully.")
+```
+
+If this script runs without an `ImportError` or linking error, your installation is working. *Note: You may see warnings about missing fuel tables, which is expected at this stage.*
+
+### Running a Simple Simulation
+
+To see a simulation in action, this example starts a fire in the center of a domain and runs it for 1000 seconds.
+
+```python
+import pyforefire as forefire
+
+ff = forefire.ForeFire()
+
+# 1. Define a 10km x 10km simulation domain
+sim_shape = (10000, 10000)
+ff.execute(f'FireDomain[sw=(0,0,0);ne=({sim_shape[0]},{sim_shape[1]},0);t=0]')
+
+# 2. Set a simple propagation model (isotropic, i.e., a perfect circle)
+ff.addLayer("propagation", "Iso", "propagationModel")
+
+# 3. Start a fire in the center of the domain
+ff.execute(f'startFire[loc=({sim_shape[0]/2},{sim_shape[1]/2},0.0)]')
+
+# 4. Run the simulation forward by 1000 seconds
+ff.execute("step[dt=1000]")
+
+# 5. Print the state of the fire front to the console
+print(ff.execute("print[]"))
 ```
 
-Additionally, helper modules are provided which make use of NumPy and Matplotlib for data processing and visualization.
+This will produce text output describing the location of the fire front nodes.
+
+To generate a `circle.kml` file for visualization in Google Earth, you can set the `dumpMode` parameter before the final print command:
+```python
+# Optional: Set output mode to KML and save to a file
+ff["dumpMode"] = "kml"
+ff.execute("print[circle.kml]")
+```
+
+### More Advanced Examples
+
+For more complex examples that use real-world data (like fuel, topography, and wind), please see the scripts located in the `tests/python/` directory of the main repository.
 
 ---
 
@@ -119,4 +161,4 @@ This project is licensed under the terms specified in the `LICENSE` file.
 ## Project URLs
 
 - **Homepage:** [https://github.com/forefireAPI/forefire](https://github.com/forefireAPI/forefire)
-- **Documentation:** [https://forefire.readthedocs.io/en/latest/](https://forefire.readthedocs.io/en/latest/)
+- **Documentation:** [https://forefire.readthedocs.io/en/latest/](https://forefire.readthedocs.io/en/latest/)
\ No newline at end of file