.. _sphx_glr_api_gallery_chaos_advanced:

Advanced: Building Custom Systems
---------------------------------

An example showing how to use the low-level, Numba-accelerated integrators
in :mod:`physicskit.chaos.core.integrators` directly -- either by subclassing
:class:`physicskit.chaos.core.base_system.DynamicalSystem` the same way the built-in
systems in :mod:`physicskit.chaos.systems.continuous` do, or by calling the
integrators on a hand-written right-hand-side function with no wrapper class
at all.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Every built-in continuous system in physicskit.chaos.systems.continuous follows the same recipe: a module-level Numba @njit right-hand-side function with signature rhs(state, t, params) -&gt; ndarray, wrapped by a physicskit.chaos.core.base_system.DynamicalSystem subclass whose trajectory() method calls physicskit.chaos.core.integrators.rk4_integrate. This example follows that same recipe to add a new system -- the Van der Pol oscillator -- that is not one of the built-ins, and then shows the even more low-level path of calling an integrator directly on a bare right-hand-side function with no wrapper class at all.">

.. only:: html

  .. image:: /api/gallery/chaos/advanced/images/thumb/sphx_glr_plot_custom_system_thumb.png
    :alt:

  :doc:`/api/gallery/chaos/advanced/plot_custom_system`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Building a Custom System with the Low-Level Integrators</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Matplotlib&#x27;s mplot3d axes project a 3D scene onto a 2D canvas with only an approximation of real depth (and no interactive rotation once a figure is saved as a static image). physicskit.chaos.visualizers.viewer3d.pyvista_trajectory renders the same kind of trajectory -- here, the Rossler attractor,">

.. only:: html

  .. image:: /api/gallery/chaos/advanced/images/thumb/sphx_glr_plot_pyvista_3d_thumb.png
    :alt:

  :doc:`/api/gallery/chaos/advanced/plot_pyvista_3d`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Interactive 3D Viewing with PyVista</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Long simulations (a fine basin-of-attraction grid, a long Lyapunov-spectrum integration, a large parameter sweep) are worth keeping around instead of recomputing. physicskit.chaos.utils.io provides two small, generic building blocks for this: save_system_config / load_system_config round-trip a system&#x27;s class and constructor parameters through JSON (using the same __init__ introspection that already powers every system&#x27;s repr()), and save_arrays / load_arrays save any named arrays (a trajectory, a basin grid, a Poincare section) to a plain .npz archive. The system used to demonstrate this is the Lorenz attractor,">

.. only:: html

  .. image:: /api/gallery/chaos/advanced/images/thumb/sphx_glr_plot_serialization_thumb.png
    :alt:

  :doc:`/api/gallery/chaos/advanced/plot_serialization`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Saving and Loading Results</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="For conservative (Hamiltonian) systems, the choice of integrator matters far more over long integration horizons than local per-step accuracy suggests. This example integrates a simple, exactly-solvable Kepler orbit with three integrators from physicskit.chaos.core.integrators -- RK4, the 2nd-order symplectic leapfrog, and the 4th-order symplectic Yoshida scheme -- and compares how their energy-conservation error behaves as the integration horizon grows. RK4&#x27;s error grows secularly (roughly proportional to integration time), while the symplectic integrators&#x27; error stays bounded regardless of how long you integrate, because they exactly preserve phase-space volume at every step: over a handful of orbits RK4 actually has the smallest error of the three, but by a few dozen orbits it has already grown past Yoshida4&#x27;s, and keeps growing indefinitely from there. A second figure makes the abstract &quot;energy drift&quot; number concrete: since a Kepler orbit&#x27;s specific energy fixes its semi-major axis, tracking the aphelion distance orbit by orbit shows RK4&#x27;s secular energy error directly shrinking the orbit over time, while Yoshida4&#x27;s bounded error keeps it flat.">

.. only:: html

  .. image:: /api/gallery/chaos/advanced/images/thumb/sphx_glr_plot_symplectic_integrators_thumb.png
    :alt:

  :doc:`/api/gallery/chaos/advanced/plot_symplectic_integrators`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Symplectic vs. Non-Symplectic Integrators: Long-Horizon Energy Drift</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /api/gallery/chaos/advanced/plot_custom_system
   /api/gallery/chaos/advanced/plot_pyvista_3d
   /api/gallery/chaos/advanced/plot_serialization
   /api/gallery/chaos/advanced/plot_symplectic_integrators