Fix/tub counter and terrame parity

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [Unreleased]
+
+- **Fix:** `Tub` kept its counter in `_step`, the attribute where dissmodel's
+  `Model` stores the interval between ticks, so the interval grew at every
+  execution (a run from t=1 to 30 executed 8 times). The counter is now
+  `_tick`; a test checks that every model executes once per tick.
+- Examples, notebooks, demo and docs use `Environment(start_time=1, end_time=N)`,
+  which runs N steps at t = 1..N like a TerraME `Timer` with `finalTime = N`.
+  The default `start_time=0` runs one step more and shifts the clock by one hour
+  in `RoomTemperature`. A note in the docs explains the convention.
+- `tests/test_terrame_parity.py` compares the full trajectory of each model
+  with a step-by-step transcription of the TerraME `sysdyn` package
+  (`terrame/sysdyn`, commit 9e671cb). Eleven models match within 1e-9.
+  Two known differences are kept as strict `xfail`: `MonoLake` (TerraME's
+  sampled Catmull-Rom spline vs scipy `CubicSpline`) and `Daisyworld`
+  (TerraME recomputes the planet albedo after updating the white area; same
+  equilibrium, different trajectory). `RandomWalk` is not compared.
+
 ## [0.1.1] — 2026-10-08
 
 First citable release. The `v0.1.0` tag was created before the release

demo/app.py

@@ -64,7 +64,7 @@
 # ---------------------------------------------------------------------------
 
 # 1. Environment
-env = Environment(start_time=0, end_time=steps)
+env = Environment(start_time=1, end_time=steps)
 
 # 2. Model
 model = ModelClass()

docs/architecture.md

@@ -76,7 +76,7 @@ class Decay(Model):
         self.amount -= decay
 
 # Running the simulation
-env = Environment(end_time=50)
+env = Environment(start_time=1, end_time=50)
 model = Decay()
 env.run()
 ```

docs/models.md

@@ -17,9 +17,16 @@ from dissmodel_sysdyn.models import SIR
 import matplotlib.pyplot as plt
 
 # Create the simulation environment
-env = Environment(end_time=60)
+env = Environment(start_time=1, end_time=60)
 ```
 
+!!! note "Counting steps as in TerraME"
+    `end_time` is inclusive. With `start_time=1, end_time=N` the model runs
+    N steps at t = 1, ..., N, like a TerraME `Timer` with `finalTime = N`.
+    The `Environment` default, `start_time=0`, runs one step more (t = 0, ..., N)
+    and shifts the clock by one, which matters for models that read `env.now()`,
+    such as `RoomTemperature`.
+
 ### Step 2: Model Configuration
 We instantiate the SIR model. We start with a nearly susceptible population and a small number of "Patient Zeros".
 
@@ -76,7 +83,7 @@ from dissmodel.core import Environment
 from dissmodel_sysdyn.models import PredatorPrey
 import matplotlib.pyplot as plt
 
-env = Environment(end_time=200)
+env = Environment(start_time=1, end_time=200)
 ```
 
 ### Step 2: Define Biological Parameters

docs/reference.md

@@ -29,7 +29,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import ChaoticGrowth
 
-env = Environment(end_time=100)
+env = Environment(start_time=1, end_time=100)
 model = ChaoticGrowth(pop=0.1, rate=3.9)
 env.run()
 ```
@@ -62,7 +62,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import Coffee
 
-env = Environment(end_time=30)
+env = Environment(start_time=1, end_time=30)
 coffee = Coffee(temperature=90, room_temperature=22, cooling_rate=0.15)
 env.run()
 ```
@@ -105,7 +105,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import Daisyworld
 
-env = Environment(end_time=200)
+env = Environment(start_time=1, end_time=200)
 model = Daisyworld(sun_luminosity=1.0)
 env.run()
 ```
@@ -138,7 +138,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import Homeostasis
 
-env = Environment(end_time=50)
+env = Environment(start_time=1, end_time=50)
 model = Homeostasis(stock=10, gain=5, rate=-0.2)
 env.run()
 ```
@@ -171,7 +171,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import LimitedGrowth
 
-env = Environment(end_time=100)
+env = Environment(start_time=1, end_time=100)
 model = LimitedGrowth(pop=10, rate=0.2, capacity=1000)
 env.run()
 ```
@@ -211,7 +211,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import Lorenz
 
-env = Environment(end_time=5000)
+env = Environment(start_time=1, end_time=5000)
 model = Lorenz()
 env.run()
 ```
@@ -245,7 +245,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import MonoLake
 
-env = Environment(end_time=50)
+env = Environment(start_time=1, end_time=50)
 model = MonoLake(export=150)
 env.run()
 ```
@@ -279,7 +279,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import PopulationGrowth
 
-env = Environment(end_time=20)
+env = Environment(start_time=1, end_time=20)
 model = PopulationGrowth(population=100, growth=0.05, growth_change=1.1)
 env.run()
 ```
@@ -311,7 +311,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import PredatorPrey
 
-env = Environment(end_time=200)
+env = Environment(start_time=1, end_time=200)
 model = PredatorPrey()
 env.run()
 ```
@@ -347,7 +347,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import RandomWalk
 
-env = Environment(end_time=100)
+env = Environment(start_time=1, end_time=100)
 model = RandomWalk(prob=0.55, seed=42)
 env.run()
 ```
@@ -383,7 +383,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import RoomTemperature
 
-env = Environment(end_time=24)
+env = Environment(start_time=1, end_time=24)
 model = RoomTemperature()
 env.run()
 ```
@@ -420,7 +420,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import SIR
 
-env = Environment(end_time=60)
+env = Environment(start_time=1, end_time=60)
 sir = SIR(infected=5, probability=0.3)
 env.run()
 ```
@@ -454,7 +454,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import Tub
 
-env = Environment(end_time=50)
+env = Environment(start_time=1, end_time=50)
 tub = Tub(water=100, out_flow=2, in_flow=50, in_period=20)
 env.run()
 ```
@@ -486,7 +486,7 @@ def execute(self) -> None:
 from dissmodel.core import Environment
 from dissmodel_sysdyn.models import Yeast
 
-env = Environment(end_time=15)
+env = Environment(start_time=1, end_time=15)
 yeast = Yeast()
 env.run()
 ```

examples/cli/sysdyn_sir.py

@@ -26,7 +26,7 @@
 # ---------------------------------------------------------------------------
 
 # 1. Environment
-env = Environment()
+env = Environment(start_time=1, end_time=30)
 
 # 2. Model
 SIR(
@@ -44,4 +44,4 @@
 # ---------------------------------------------------------------------------
 # Run
 # ---------------------------------------------------------------------------
-env.run(30)
+env.run()

examples/notebooks/sysdyn_chaotic_growth.ipynb

@@ -65,7 +65,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=100)"
    ]
   },
   {
@@ -147,7 +147,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(100)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_coffee.ipynb

@@ -62,7 +62,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=50)"
    ]
   },
   {
@@ -147,7 +147,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(50)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_daisyworld.ipynb

@@ -65,7 +65,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=100)"
    ]
   },
   {
@@ -178,7 +178,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(100)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_homeostasis.ipynb

@@ -62,7 +62,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=30)"
    ]
   },
   {
@@ -147,7 +147,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(30)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_limited_growth.ipynb

@@ -62,7 +62,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=100)"
    ]
   },
   {
@@ -147,7 +147,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(100)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_lorenz.ipynb

@@ -64,7 +64,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=2000)"
    ]
   },
   {
@@ -150,7 +150,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(2000)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_mono_lake.ipynb

@@ -63,7 +63,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=50)"
    ]
   },
   {
@@ -156,7 +156,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(50)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_population_growth.ipynb

@@ -63,7 +63,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=20)"
    ]
   },
   {
@@ -142,7 +142,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(20)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_predator_prey.ipynb

@@ -63,7 +63,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=500)"
    ]
   },
   {
@@ -146,7 +146,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(500)"
+    "env.run()"
    ]
   },
   {

examples/notebooks/sysdyn_random_walk.ipynb

@@ -63,7 +63,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env = Environment()"
+    "env = Environment(start_time=1, end_time=100)"
    ]
   },
   {
@@ -145,7 +145,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "env.run(100)"
+    "env.run()"
    ]
   },
   {