.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "gallery/02_stack_mesh_mixin/p03_fieldlines.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_gallery_02_stack_mesh_mixin_p03_fieldlines.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_gallery_02_stack_mesh_mixin_p03_fieldlines.py:


Plotting Magnetic Fieldlines
=============================

This example demonstrates :meth:`~pyvisual.core.mixins.StackMeshMixin.add_fieldlines`
— the method for rendering traced magnetic fieldlines as spline bundles using
:mod:`mapflpy`, the PSI library for integrating along magnetic field data on
spherical grids.

:func:`~mapflpy.scripts.run_forward_tracing` and
:func:`~mapflpy.scripts.run_fwdbwd_tracing` return a
:class:`~mapflpy.globals.Traces` named tuple whose ``geometry`` array has shape
:math:`(M, 3, N)`:

- :math:`M` — the per-fieldline point buffer (NaN-padded to a uniform length).
- :math:`3` — spherical coordinate components :math:`(r,\,\theta,\,\phi)`.
- :math:`N` — the number of fieldlines.

:func:`numpy.moveaxis` transposes this to :math:`(3, M, N)` so that unpacking
with ``*`` feeds the three coordinate arrays directly into ``add_fieldlines``.

.. GENERATED FROM PYTHON SOURCE LINES 22-29

.. code-block:: Python


    import numpy as np
    from mapflpy.scripts import run_forward_tracing, run_fwdbwd_tracing
    from mapflpy.utils import get_fieldline_polarity
    from pyvisual import Plot3d
    from pyvisual.utils.data import fetch_datasets








.. GENERATED FROM PYTHON SOURCE LINES 30-37

Random Coloring
---------------

The simplest coloring strategy assigns a unique random hue to each fieldline
via ``coloring='random'``.  When no ``launch_points`` are supplied,
:mod:`mapflpy` places :math:`n = 128` seed points quasi-uniformly at
:math:`r = 1.01\,R_\odot` using the Fibonacci lattice algorithm.

.. GENERATED FROM PYTHON SOURCE LINES 37-50

.. code-block:: Python


    mag_field = fetch_datasets("cor", ["br", "bt", "bp"])
    traces = run_forward_tracing(*mag_field, context='fork')
    r, t, p = np.moveaxis(traces.geometry, 1, 0)

    plotter = Plot3d()
    plotter.show_axes()
    plotter.add_sun()
    plotter.add_fieldlines(r, t, p, coloring='random', line_width=2, show_scalar_bar=False)
    plotter.observer_focus = 0, 0, 0
    plotter.observer_fov_view = 10
    plotter.show()








.. tab-set::



   .. tab-item:: Static Scene



            
     .. image-sg:: /gallery/02_stack_mesh_mixin/images/sphx_glr_p03_fieldlines_001.png
        :alt: p03 fieldlines
        :srcset: /gallery/02_stack_mesh_mixin/images/sphx_glr_p03_fieldlines_001.png
        :class: sphx-glr-single-img
     


   .. tab-item:: Interactive Scene



       .. offlineviewer:: /Users/rdavidson/MHDweb/pyvisual/docs/source/gallery/02_stack_mesh_mixin/images/sphx_glr_p03_fieldlines_001.vtksz






.. GENERATED FROM PYTHON SOURCE LINES 51-71

Polarity Coloring
-----------------

A more informative visualization classifies each fieldline by its
open/closed magnetic connectivity via ``coloring='polarity'``.
:func:`~mapflpy.utils.get_fieldline_polarity` evaluates the radial positions
of the trace endpoints against the inner (:math:`r = 1\,R_\odot`) and outer
(:math:`r = 30\,R_\odot`) domain boundaries, assigning one of five
:class:`~mapflpy.globals.Polarity` states to each line:

- ``R0_R1_POS`` — open, :math:`B_r > 0` at the inner footpoint.
- ``R0_R1_NEG`` — open, :math:`B_r < 0` at the inner footpoint.
- ``R0_R0`` — closed, both endpoints anchored at the inner boundary.
- ``R1_R1`` — disconnected, both endpoints at the outer boundary.
- ``ERROR`` — unclassified (trace did not reach a boundary).

Combined forward-and-backward traces from
:func:`~mapflpy.scripts.run_fwdbwd_tracing` are required so that every
fieldline has endpoints on both boundaries, enabling unambiguous polarity
assessment.

.. GENERATED FROM PYTHON SOURCE LINES 71-82

.. code-block:: Python


    traces = run_fwdbwd_tracing(*mag_field, context='fork')
    polarity = get_fieldline_polarity(1, 30, mag_field.cor_br, traces)
    r, t, p = np.moveaxis(traces.geometry, 1, 0)

    plotter = Plot3d()
    plotter.show_axes()
    plotter.add_sun()
    plotter.add_fieldlines(r, t, p, polarity, coloring='polarity', line_width=2)
    plotter.observer_focus = 0, 0, 0
    plotter.observer_fov_view = 10
    plotter.show()






.. tab-set::



   .. tab-item:: Static Scene



            
     .. image-sg:: /gallery/02_stack_mesh_mixin/images/sphx_glr_p03_fieldlines_002.png
        :alt: p03 fieldlines
        :srcset: /gallery/02_stack_mesh_mixin/images/sphx_glr_p03_fieldlines_002.png
        :class: sphx-glr-single-img
     


   .. tab-item:: Interactive Scene



       .. offlineviewer:: /Users/rdavidson/MHDweb/pyvisual/docs/source/gallery/02_stack_mesh_mixin/images/sphx_glr_p03_fieldlines_002.vtksz







.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 2.512 seconds)


.. _sphx_glr_download_gallery_02_stack_mesh_mixin_p03_fieldlines.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: p03_fieldlines.ipynb <p03_fieldlines.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: p03_fieldlines.py <p03_fieldlines.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: p03_fieldlines.zip <p03_fieldlines.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_