callbacks docs update

Author: JoseAntFer

.doctrees/architecture.doctree

@@ -2,7 +2,7 @@
 
 STARK's public API is straightforward.
 Users work through a single entry point, `Simulation`, which exposes all physics subsystems.
-Internally, `core::Stark` orchestrates time stepping and uses SymX's Newton solves.
+Internally, `Stark` orchestrates time stepping and uses SymX's Newton solves.
 
 ## Component Map
 
@@ -34,7 +34,7 @@ flowchart TD
 Constructing it with a `Settings` object is all that is needed to start a simulation:
 
 ```cpp
-stark::core::Settings settings;
+stark::Settings settings;
 settings.output.directory = "./output";
 settings.simulation.max_time_step_size = 0.01;
 
@@ -123,9 +123,9 @@ See [Presets](presets.md) for the full list.
 
 ---
 
-## `core::Stark`: The Solver Engine
+## `Stark` class
 
-`core::Stark` is the engine that drives the simulation.
+`Stark` is the engine that drives the simulation.
 
 Its key components are:
 
@@ -134,7 +134,7 @@ Its key components are:
 - **`EventDrivenScript`** — fires lambdas at specified simulation times or on solver events.
 - **`Settings`** — output paths, time step size, Newton tolerances, contact parameters, and more.
 
-Under normal use you do not interact with `core::Stark` directly.
+Under normal use you do not interact with `Stark` directly.
 When writing a custom energy model that extends STARK, you access it through `simulation.get_stark()`.
 See [Extending STARK](extending.md) for a worked example.
 

.doctrees/environment.pickle

@@ -32,7 +32,7 @@ This is incorporated to the rest of the physical effects and piped into the opti
 The following is the energy definition
 
 ```cpp
-stark::core::Stark& stark_core = simulation.get_stark();
+stark::Stark& stark_core = simulation.get_stark();
 stark::PointDynamics* dyn = simulation.deformables->point_sets.get();
 
 stark_core.global_potential->add_potential("EnergyMagneticAttraction", magnetic_vertices,

.doctrees/extending.doctree

@@ -93,6 +93,7 @@ The simplified inner loop is:
 check initial state validity
 
 for each Newton iteration:
+    run before_step callbacks
     run before_energy_evaluation callbacks
     evaluate energy, gradient, and local Hessians
     compute residual
@@ -114,6 +115,7 @@ for each Newton iteration:
         backtrack until Armijo sufficient decrease holds
 
     run optional user convergence callbacks
+    run after_step callbacks
 
 check converged-state validity
 ```
@@ -197,6 +199,7 @@ Check the [original SymX docs](https://symx.physics-simulation.org/newtons_metho
 
 | Callback | When it runs | Purpose |
 |---|---|---|
+| `before_step` | at the very start of each Newton iteration | logging, resetting per-iteration state |
 | `before_energy_evaluation` | before each energy or gradient/Hessian evaluation | update collision sets, derived fields, or time-dependent data |
 | `is_initial_state_valid` | before Newton starts | reject invalid starting states |
 | `max_allowed_step` | before line-search backtracking | impose step limits, commonly from CCD |
@@ -205,6 +208,7 @@ Check the [original SymX docs](https://symx.physics-simulation.org/newtons_metho
 | `on_armijo_fail` | after too many Armijo backtracks | diagnostics or model adjustment |
 | `is_converged` | after a line-search update | add custom convergence criteria |
 | `is_converged_state_valid` | after Newton reports success | verify final constraints/contact tolerances |
+| `after_step` | at the end of each Newton iteration | per-iteration diagnostics, adaptive parameter updates |
 
 Boolean validity callbacks are combined with logical `AND`. All registered checks must pass.
 `max_allowed_step` callbacks are combined by taking the smallest returned step fraction.

.doctrees/simulation_loop.doctree

@@ -261,7 +261,7 @@
 <h1>Architecture<a class="headerlink" href="#architecture" title="Link to this heading">¶</a></h1>
 <p>STARK’s public API is straightforward.
 Users work through a single entry point, <code class="docutils literal notranslate"><span class="pre">Simulation</span></code>, which exposes all physics subsystems.
-Internally, <code class="docutils literal notranslate"><span class="pre">core::Stark</span></code> orchestrates time stepping and uses SymX’s Newton solves.</p>
+Internally, <code class="docutils literal notranslate"><span class="pre">Stark</span></code> orchestrates time stepping and uses SymX’s Newton solves.</p>
 <section id="component-map">
 <h2>Component Map<a class="headerlink" href="#component-map" title="Link to this heading">¶</a></h2>
 <pre  class="mermaid">
@@ -288,7 +288,7 @@ <h2>Component Map<a class="headerlink" href="#component-map" title="Link to this
 <h2><code class="docutils literal notranslate"><span class="pre">Simulation</span></code><a class="headerlink" href="#simulation" title="Link to this heading">¶</a></h2>
 <p><code class="docutils literal notranslate"><span class="pre">Simulation</span></code> is the single public entry point.
 Constructing it with a <code class="docutils literal notranslate"><span class="pre">Settings</span></code> object is all that is needed to start a simulation:</p>
-<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="nc">stark</span><span class="o">::</span><span class="nc">core</span><span class="o">::</span><span class="nc">Settings</span><span class="w"> </span><span class="n">settings</span><span class="p">;</span>
+<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="nc">stark</span><span class="o">::</span><span class="nc">Settings</span><span class="w"> </span><span class="n">settings</span><span class="p">;</span>
 <span class="n">settings</span><span class="p">.</span><span class="n">output</span><span class="p">.</span><span class="n">directory</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;./output&quot;</span><span class="p">;</span>
 <span class="n">settings</span><span class="p">.</span><span class="n">simulation</span><span class="p">.</span><span class="n">max_time_step_size</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.01</span><span class="p">;</span>
 
@@ -409,17 +409,17 @@ <h3><code class="docutils literal notranslate"><span class="pre">presets</span><
 </section>
 </section>
 <hr class="docutils" />
-<section id="core-stark-the-solver-engine">
-<h2><code class="docutils literal notranslate"><span class="pre">core::Stark</span></code>: The Solver Engine<a class="headerlink" href="#core-stark-the-solver-engine" title="Link to this heading">¶</a></h2>
-<p><code class="docutils literal notranslate"><span class="pre">core::Stark</span></code> is the engine that drives the simulation.</p>
+<section id="stark-class">
+<h2><code class="docutils literal notranslate"><span class="pre">Stark</span></code> class<a class="headerlink" href="#stark-class" title="Link to this heading">¶</a></h2>
+<p><code class="docutils literal notranslate"><span class="pre">Stark</span></code> is the engine that drives the simulation.</p>
 <p>Its key components are:</p>
 <ul class="simple">
 <li><p><strong><code class="docutils literal notranslate"><span class="pre">GlobalPotential</span></code></strong> — the SymX energy registry. Energy models call <code class="docutils literal notranslate"><span class="pre">global_potential-&gt;add_potential(...)</span></code> during construction to register their symbolic expression and the state variables it acts on.</p></li>
 <li><p><strong><code class="docutils literal notranslate"><span class="pre">Callbacks</span></code></strong> — hook points for injecting logic at fixed moments in the loop: <code class="docutils literal notranslate"><span class="pre">before_time_step</span></code>, <code class="docutils literal notranslate"><span class="pre">on_time_step_accepted</span></code>, <code class="docutils literal notranslate"><span class="pre">after_time_step</span></code>, and <code class="docutils literal notranslate"><span class="pre">write_frame</span></code>.</p></li>
 <li><p><strong><code class="docutils literal notranslate"><span class="pre">EventDrivenScript</span></code></strong> — fires lambdas at specified simulation times or on solver events.</p></li>
 <li><p><strong><code class="docutils literal notranslate"><span class="pre">Settings</span></code></strong> — output paths, time step size, Newton tolerances, contact parameters, and more.</p></li>
 </ul>
-<p>Under normal use you do not interact with <code class="docutils literal notranslate"><span class="pre">core::Stark</span></code> directly.
+<p>Under normal use you do not interact with <code class="docutils literal notranslate"><span class="pre">Stark</span></code> directly.
 When writing a custom energy model that extends STARK, you access it through <code class="docutils literal notranslate"><span class="pre">simulation.get_stark()</span></code>.
 See <a class="reference internal" href="extending.html"><span class="std std-doc">Extending STARK</span></a> for a worked example.</p>
 </section>
@@ -490,7 +490,7 @@ <h2><code class="docutils literal notranslate"><span class="pre">core::Stark</sp
 <li><a class="reference internal" href="#presets"><code class="docutils literal notranslate"><span class="pre">presets</span></code></a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#core-stark-the-solver-engine"><code class="docutils literal notranslate"><span class="pre">core::Stark</span></code>: The Solver Engine</a></li>
+<li><a class="reference internal" href="#stark-class"><code class="docutils literal notranslate"><span class="pre">Stark</span></code> class</a></li>
 </ul>
 </li>
 </ul>

_sources/architecture.md.txt

@@ -0,0 +1 @@
+Subproject commit 2a61ad2494d09fecb2e13322c1383342c299900d

_sources/extending.md.txt

@@ -283,7 +283,7 @@ <h2>Example: implicit magnetic attraction<a class="headerlink" href="#example-im
 <p>The force produced by this energy is attractive, and because the term is registered as a SymX potential, STARK also receives the corresponding Hessian contribution automatically.
 This is incorporated to the rest of the physical effects and piped into the optimization pipeline.</p>
 <p>The following is the energy definition</p>
-<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="nc">stark</span><span class="o">::</span><span class="nc">core</span><span class="o">::</span><span class="nc">Stark</span><span class="o">&amp;</span><span class="w"> </span><span class="n">stark_core</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">simulation</span><span class="p">.</span><span class="nf">get_stark</span><span class="p">();</span>
+<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="nc">stark</span><span class="o">::</span><span class="nc">Stark</span><span class="o">&amp;</span><span class="w"> </span><span class="n">stark_core</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">simulation</span><span class="p">.</span><span class="nf">get_stark</span><span class="p">();</span>
 <span class="nc">stark</span><span class="o">::</span><span class="nc">PointDynamics</span><span class="o">*</span><span class="w"> </span><span class="n">dyn</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">simulation</span><span class="p">.</span><span class="n">deformables</span><span class="o">-&gt;</span><span class="n">point_sets</span><span class="p">.</span><span class="nf">get</span><span class="p">();</span>
 
 <span class="n">stark_core</span><span class="p">.</span><span class="n">global_potential</span><span class="o">-&gt;</span><span class="nf">add_potential</span><span class="p">(</span><span class="s">&quot;EnergyMagneticAttraction&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">magnetic_vertices</span><span class="p">,</span>