mapflpy 1.1.9__tar.gz → 1.2.0__tar.gz

{mapflpy-1.1.9 → mapflpy-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapflpy
-Version: 1.1.9
+Version: 1.2.0
 Summary: Fast field line tracing for spherical vector fields
 Keywords: solar physics,space physics,heliophysics,magnetohydrodynamic,science,mas,predsci,psi,modeling,fortran
 Author: Ryder Davidson, Cooper Downs, Andres Reyes, Asher Pembroke

{mapflpy-1.1.9 → mapflpy-1.2.0}/environment.yml

@@ -30,6 +30,7 @@ dependencies:
   - ruff
   - coverage
   - nox
+  - pre-commit
 
   # -------- Docs --------
   - sphinx

{mapflpy-1.1.9 → mapflpy-1.2.0}/mapflpy/globals.py

@@ -30,7 +30,7 @@ __all__ = [
 # It contains the geometry of the traces, their start and end positions,
 # and whether they were traced to a boundary.
 #------------------------------------------------------------------------------
-Traces = namedtuple('Traces', ['geometry', 'start_pos', 'end_pos', 'traced_to_boundary'])
+Traces = namedtuple('Traces', ['geometry', 'start_pos', 'end_pos', 'traced_to_boundary', 'integral'])
 Traces.__doc__ = (
     """Named tuple for storing magnetic fieldline trace information.
     
@@ -45,9 +45,39 @@ Traces.__doc__ = (
         Array of shape (N, 3) containing the ending positions of each fieldline.
     traced_to_boundary : ndarray
         Boolean array of shape (N,) indicating whether each fieldline was traced to a boundary.
+    integral : ndarray
+        Array of shape (N,) containing the field aligned integral. By default the integral
+        is just the field line length, but certain mapflpy options can change this behavior, 
+        currently `integrate_along_fl_`, `scalar_input_file_`, `weight_integral_by_area_`, and 
+        max_along_fl_`.
     """
 )
 
+# ------------------------------------------------------------------------------
+# Named tuple for storing mapping information produced by some of the mapping
+# scripts in `mapflpy.scripts`
+# ------------------------------------------------------------------------------
+Mapping = namedtuple('Mapping', ['r', 't', 'p', 'traced_to_boundary', 'integral'])
+Mapping.__doc__ = (
+    """Named tuple for storing magnetic fieldline mapping information.
+
+    Attributes
+    ----------
+    r : ndarray
+        Array containing the radial positions of the mapping endpoints [R_sun]).
+    t : ndarray
+        Array containing the theta (co-latitude) positions of the mapping endpoints [radians].
+    p : ndarray
+        Array containing the phi (longitude) positions of the mapping endpoints [radians].
+    traced_to_boundary : ndarray
+        Boolean array indicating whether each fieldline was traced to a boundary.
+    integral : ndarray
+        Array containing the values of the field line integral. By default the integral
+        is just the field line length, but certain mapflpy options can change this behavior, 
+        currently `integrate_along_fl_`, `scalar_input_file_`, `weight_integral_by_area_`, and 
+        `max_along_fl_`.
+    """
+)
 
 # ------------------------------------------------------------------------------
 # Type aliases for improved code readability.
@@ -182,6 +212,8 @@ DEFAULT_FIELDS = MappingProxyType({
 DEFAULT_PARAMS = MappingProxyType({
     'integrate_along_fl_': False,
     'scalar_input_file_': '',
+    'weight_integral_by_area_': False,
+    'max_along_fl_': False,
     'verbose_': False,
     'cubic_': False,
     'trace_fwd_': False,

{mapflpy-1.1.9 → mapflpy-1.2.0}/mapflpy/scripts.py

@@ -20,15 +20,16 @@ concatenation.
 
 """
 from __future__ import annotations
+import concurrent.futures
 import copy
 from contextlib import ExitStack
 from functools import partial
-from typing import Optional, Iterable, Tuple
+from typing import Optional, Iterable, Tuple, Callable
 
 import numpy as np
 from numpy.typing import NDArray, ArrayLike
 
-from mapflpy.globals import DEFAULT_BUFFER_SIZE, Traces, PathType, DirectionType
+from mapflpy.globals import DEFAULT_BUFFER_SIZE, Traces, Mapping, PathType, DirectionType, ContextType
 from mapflpy.tracer import TracerMP
 from mapflpy.utils import shift_phi_traces, shift_phi_lps, fetch_default_launch_points
 
@@ -180,6 +181,240 @@ def run_fwdbwd_tracing(br: PathType,
         return tracer.trace_fbwd(launch_points, buffer_size)
 
 
+def map_field_lines_in_parallel(trace_function: Callable,
+                                r_in: ArrayLike,
+                                t_in: ArrayLike,
+                                p_in: ArrayLike,
+                                nproc: int = 4):
+    """Map field lines from r, t, p positions in parallel using a given tracing script.
+
+    The `trace_function` is a callable function that wraps the desired mapflpy script that uses TracerMP in
+    the background. It must only accept one argument (`launch_points`) and otherwise wraps a tracing
+    script that is defined with any specific keywords that determine how the trace is done.
+    Currently only :func:`run_forward_tracing`, :func:`run_backward_tracing` make sense to wrap here.
+
+    The r,t,p input arrays can be any shape (1D, 2D, 3D, etc.) as long as it is consistent.
+
+    .. warning::
+       The wrapped trace function should specify the `buffer_size` keyword to a small number (e.g. 3)
+       since the trace geometry is not used anyway. This is essential for keeping the memory footprint
+       small and for the mapping to compute as quickly as possible.
+
+    Parameters
+    ----------
+    trace_function : Callable
+        A function that wraps the mapflpy forward or backwards tracing script to call in parallel
+        (:func:`run_forward_tracing`, :func:`run_backward_tracing`) and sets the desired parameters to
+        run the wrapped script with.
+        Only the endpoints are used, so only one of forward or backwards mapping makes sense.
+    r_in : ArrayLike
+        An N-Dimensional array of radial positions to map from.
+    t_in : ArrayLike
+        An N-Dimensional array of theta positions to map from (shape must match `r_in`).
+    p_in : ArrayLike
+        An N-Dimensional array of phi positions to map from (shape must match `r_in`).
+    nproc : int, optional
+        The number of processes to spawn. This should be equal to or less than the number of threads
+        that can be used on the machine.
+
+    Returns
+    -------
+    mapping : :class:`~mapflpy.globals.Mapping`
+        A namedtuple containing the mapping results (:class:`mapflpy.globals.Mapping`).
+
+    See Also
+    --------
+    :func:`map_pt_forward`
+    :func:`map_pt_backward`
+    :func:`run_forward_tracing`
+    :func:`run_backward_tracing`
+    """
+
+    # convert the r,t,p positions to a list of launchpoints split into nproc chunks
+    r1d = r_in.ravel()
+    t1d = t_in.ravel()
+    p1d = p_in.ravel()
+    lp_all = np.stack([r1d, t1d, p1d], axis=0)
+    lp_chunks = np.array_split(lp_all, nproc, axis=1)
+
+    # run the mapping function on nprocs
+    with concurrent.futures.ThreadPoolExecutor(max_workers=nproc) as executor:
+        results = list(executor.map(trace_function, lp_chunks))
+
+    # collect the results back into one array
+    end_pos_1d = np.concatenate([result.end_pos for result in results], axis=1)
+    traced_to_boundary_1d = np.concatenate([result.traced_to_boundary for result in results])
+    integral_1d = np.concatenate([result.integral for result in results])
+
+    # reshape and return the Mapping object
+    r_out = np.reshape(end_pos_1d[0, :], r_in.shape)
+    t_out = np.reshape(end_pos_1d[1, :], t_in.shape)
+    p_out = np.reshape(end_pos_1d[2, :], p_in.shape)
+    traced_to_boundary = np.reshape(traced_to_boundary_1d, r_in.shape)
+    integral = np.reshape(integral_1d, r_in.shape)
+
+    return Mapping(r_out, t_out, p_out, traced_to_boundary, integral)
+
+
+def map_pt_forward(br: PathType,
+                   bt: PathType,
+                   bp: PathType,
+                   p1d: ArrayLike,
+                   t1d: ArrayLike,
+                   radius: float = 1.0,
+                   timeout: float = 3600.,
+                   context: Optional[ContextType] = 'fork',
+                   nproc: int = 4,
+                   **mapfl_params):
+    """Map field lines forwards on a phi, theta grid at constant radius.
+
+    The inputs are similar to instantiating a Tracer class except one also
+    specifies 1D arrays that define a grid in phi, theta and a radius to map from.
+
+    Currently the mapping radius defaults to 1.0 or must be set. In the future
+    this will default to the inner radius of the main mesh of the B files.
+
+    Notes
+    -----
+    This is a very specific helper function for a common task. Generic mappings
+    can be built by following this as an example for wrapping :func:`map_field_lines_in_parallel`.
+
+    Parameters
+    ----------
+    br : PathType
+        Path to the Br magnetic field file.
+    bt : PathType
+        Path to the Bt magnetic field file.
+    bp : PathType
+        Path to the Bp magnetic field file.
+    p1d : ArrayLike
+        A 1D numpy array of phi (longitude) positions in radians that will be used to
+        build the mapping grid.
+    t1d : ArrayLike
+        A 1D numpy array of theta (co-latitude) positions in radians that will be used to
+        build the mapping grid.
+    radius : float, optional
+        Radius to map forward from. Default 1.0.
+    timeout : float, optional
+        Timeout in seconds for interprocess communication. Default is 3600 seconds.
+    context : ContextType, optional
+        The multiprocessing context to use when spawning the subprocess. Since many
+        processes are launched, generally 'fork' is recommended. Behavior may depend
+        on the system architecture. Default is 'fork'.
+    nproc : int, optional
+        The number of processes to spawn. This should be equal to or less than the number of threads
+        that can be used on the machine.
+    **mapfl_params : dict
+        Additional tracing parameters passed to the subprocess.
+
+    Returns
+    -------
+    mapping : :class:`~mapflpy.globals.Mapping`
+        A namedtuple containing the mapping results (:class:`mapflpy.globals.Mapping`).
+
+    See Also
+    --------
+    :func:`map_field_lines_in_parallel`
+    """
+
+    # build a 2D grid of p and t locations from the input 1D arrays
+    p2d, t2d = np.meshgrid(p1d, t1d)
+    # the r locations are on the specified radius
+    r2d = np.ones_like(p2d)*radius
+
+    # define the wrapped trace function
+    def trace_function(launch_points):
+        traces = run_forward_tracing(br, bt, bp, launch_points=launch_points,
+                                     buffer_size=3, context=context, timeout=timeout,
+                                     **mapfl_params)
+        return traces
+
+    # compute the mapping
+    mapping = map_field_lines_in_parallel(trace_function, r2d, t2d, p2d, nproc=nproc)
+
+    return mapping
+
+
+def map_pt_backward(br: PathType,
+                    bt: PathType,
+                    bp: PathType,
+                    p1d: ArrayLike,
+                    t1d: ArrayLike,
+                    radius: float = 30.0,
+                    timeout: float = 3600.,
+                    context: Optional[ContextType] = 'fork',
+                    nproc: int = 4,
+                    **mapfl_params):
+    """Map field lines backwards on a phi, theta grid at constant radius.
+
+    The inputs are similar to instantiating a Tracer class except one also
+    specifies 1D arrays that define a grid in phi, theta and a radius to map from.
+
+    Currently the mapping radius defaults to 30 or must be set. In the future
+    this will default to the outer radius of the main mesh of the B files.
+
+    Notes
+    -----
+    This is a very specific helper function for a common task. Generic mappings
+    can be built by following this as an example for wrapping :func:`map_field_lines_in_parallel`.
+
+    Parameters
+    ----------
+    br : PathType
+        Path to the Br magnetic field file.
+    bt : PathType
+        Path to the Bt magnetic field file.
+    bp : PathType
+        Path to the Bp magnetic field file.
+    p1d : ArrayLike
+        A 1D numpy array of phi (longitude) positions in radians that will be used to
+        build the mapping grid.
+    t1d : ArrayLike
+        A 1D numpy array of theta (co-latitude) positions in radians that will be used to
+        build the mapping grid.
+    radius : float, optional
+        Radius to map backwards from. Default 30.0.
+    timeout : float, optional
+        Timeout in seconds for interprocess communication. Default is 3600 seconds.
+    context : ContextType, optional
+        The multiprocessing context to use when spawning the subprocess. Since many
+        processes are launched, generally 'fork' is recommended. Behavior may depend
+        on the system architecture. Default is 'fork'.
+    nproc : int, optional
+        The number of processes to spawn. This should be equal to or less than the number of threads
+        that can be used on the machine.
+    **mapfl_params : dict
+        Additional tracing parameters passed to the subprocess.
+
+    Returns
+    -------
+    mapping : :class:`~mapflpy.globals.Mapping`
+        A namedtuple containing the mapping results (:class:`mapflpy.globals.Mapping`).
+
+    See Also
+    --------
+    :func:`map_field_lines_in_parallel`
+    """
+
+
+    # build a 2D grid of p and t locations from the input 1D arrays
+    p2d, t2d = np.meshgrid(p1d, t1d)
+    # the r locations are on the specified radius
+    r2d = np.ones_like(p2d)*radius
+
+    # define the wrapped trace function
+    def trace_function(launch_points):
+        traces = run_backward_tracing(br, bt, bp, launch_points=launch_points,
+                                      buffer_size=3, context=context, timeout=timeout,
+                                      **mapfl_params)
+        return traces
+
+    # compute the mapping
+    mapping = map_field_lines_in_parallel(trace_function, r2d, t2d, p2d, nproc=nproc)
+
+    return mapping
+
+
 def inter_domain_tracing(br_cor: PathType,
                          bt_cor: PathType,
                          bp_cor: PathType,

{mapflpy-1.1.9 → mapflpy-1.2.0}/mapflpy/tracer.py

@@ -54,9 +54,6 @@ _BS0 = np.zeros(3, order='F').astype(np.float64)
 _BS1 = np.zeros(3, order='F').astype(np.float64)
 """Sentinel array for :meth:`mapfl.trace` **bs1** parameter."""
 
-_S = np.zeros(1, order='F').astype(np.float64)
-"""Sentinel array for :meth:`mapfl.trace` **s** parameter."""
-
 
 def state_modifier(method):
     """
@@ -289,19 +286,20 @@ def _mapflpy_trace_listener(pipe):
             traces = np.full((buffer_size, *lps.shape), np.nan, order='F').astype(np.float64)
             s1 = np.zeros(lps.shape, np.float64, order='F')
             mask = np.full((1, lps.shape[1]), False, order='F')
+            integral = np.full((1, lps.shape[1]), 0.0, order='F')
             for i in range(lps.shape[1]):
                 trace_args = dict(
                     s0=lps[:, i],
                     s1=s1[:, i],
                     bs0=_BS0,
                     bs1=_BS1,
-                    s=_S,
+                    s=integral[:,i],
                     traced_to_r_boundary=mask[:, i],
                     svec=traces[:, :, i],
                     svec_n=buffer_size
                 )
                 mapfl.trace(**trace_args)
-            return Traces(traces, lps, s1, mask[0, :])
+            return Traces(traces, lps, s1, mask[0, :], integral[0,:])
 
         while True:
             method, *args = pipe.recv()
@@ -866,27 +864,29 @@ class Tracer(_Tracer):
             Structured container with traced fieldline geometry, starting points, ending points,
             and whether the fieldlines reached the radial boundary of the provided mesh.
         """
-        # `traces`, `s1`, and `mask` are initialized to Fortran-contiguous arrays
-        # and are used to store the traced fieldlines, their end points, and boundary masks.
+        # `traces`, `s1`, `mask`, and `integral` are initialized to Fortran-contiguous arrays
+        # and are used to store the traced fieldlines, their end points, boundary masks, and
+        # the scalar field integral along the field line (length by default).
         # `mapflpy_fortran` alters these arrays in-place during tracing.
         # Each array must have a dimensionality > 1 so that a numpy view is passed.
         traces = np.full((buff, *lps.shape), np.nan, order='F').astype(np.float64)
         s1 = np.zeros(lps.shape, np.float64, order='F')
         mask = np.full((1, lps.shape[1]), False, order='F')
+        integral = np.full((1, lps.shape[1]), 0.0, order='F')
 
-        # Since the parameters _bs0, _bs1, and _s are discarded after the trace,
-        # we can use the globals `_BS0`, `_BS1`, and `_S` as placeholders to avoid having
+        # Since the parameters _bs0 and _bs1 are discarded after the trace,
+        # we can use the globals `_BS0` and `_BS1` as placeholders to avoid having
         # to repeatedly create and destruct arrays.
         for i in range(lps.shape[1]):
             self._mapfl.trace(s0=lps[:, i],
                               s1=s1[:, i],
                               bs0=_BS0,
                               bs1=_BS1,
-                              s=_S,
+                              s=integral[:,i],
                               traced_to_r_boundary=mask[:, i],
                               svec=traces[:, :, i],
                               svec_n=buff)
-        return Traces(traces, lps, s1, mask[0, :])
+        return Traces(traces, lps, s1, mask[0, :], integral[0,:])
 
 
 class TracerMP(_Tracer):

{mapflpy-1.1.9 → mapflpy-1.2.0}/mapflpy/utils.py

@@ -220,7 +220,8 @@ def combine_fwd_bwd_traces(fwd_traces: Traces,
                                              fwd_traces.geometry]),
                              bwd_traces.end_pos,
                              fwd_traces.end_pos,
-                             fwd_traces.traced_to_boundary & bwd_traces.traced_to_boundary)
+                             fwd_traces.traced_to_boundary & bwd_traces.traced_to_boundary,
+                             fwd_traces.integral + bwd_traces.integral)
     return combined_traces
 
 
@@ -423,7 +424,8 @@ def trim_fieldline_nan_buffer(traces: Traces | np.ndarray) -> List[np.ndarray]:
 
 def combine_and_pad_fieldlines(arrs: list | tuple,
                                to_trace: bool = False,
-                               traced_to_boundary: Optional[NDArray[np.bool_]] = None
+                               traced_to_boundary: Optional[NDArray[np.bool_]] = None,
+                               integral: Optional[NDArray[np.bool_]] = None
                                ) -> np.ndarray | Traces:
     """
     NaN-pad a list of variable-length 3D point arrays into a single dense array.
@@ -499,7 +501,7 @@ def combine_and_pad_fieldlines(arrs: list | tuple,
             geometry[:a.shape[1], :, i] = a.T   # (3, ni) -> (ni, 3)
             start_pos[:, i] = a[:,0]
             end_pos[:, i] = a[:, -1]
-        return Traces(geometry, start_pos, end_pos, traced_to_boundary)
+        return Traces(geometry, start_pos, end_pos, traced_to_boundary, integral)
 
 
 

{mapflpy-1.1.9 → mapflpy-1.2.0}/meson.build

@@ -47,8 +47,16 @@ fortranobject_c = f2py_inc_dir / 'fortranobject.c'
 
 # ---- HDF5 dependencies
 hdf5_c = dependency('hdf5', required : true)
-hdf5f = declare_dependency(link_args : ['-lhdf5_fortran'], dependencies : [hdf5_c])
-hdf5f_hl = declare_dependency(link_args : ['-lhdf5hl_fortran'], dependencies : [hdf5_c])
+
+# On Linux, meson resolves pkg-config deps to absolute library paths, which
+# drops the -L flag from the link command.  Bare -lhdf5_fortran then fails
+# because the conda env's lib/ is never on the search path.  Use find_library
+# with an explicit dir (taken from the HDF5 pkg-config libdir) so both macOS
+# and Linux get a resolved path, not a bare -l flag.
+_hdf5_libdir = hdf5_c.get_variable(pkgconfig : 'libdir', default_value : '')
+_hdf5_dirs   = _hdf5_libdir != '' ? [_hdf5_libdir] : []
+hdf5f    = cc.find_library('hdf5_fortran',    dirs : _hdf5_dirs, required : true)
+hdf5f_hl = cc.find_library('hdf5_hl_fortran', dirs : _hdf5_dirs, required : true)
 
 # Optional: OpenMP
 # omp_dep = dependency('openmp', required : false)
@@ -110,9 +118,19 @@ configure_file(
 install_subdir(
   'mapflpy',
   install_dir : py.get_install_dir(),
+  exclude_directories : ['fortran'],
   exclude_files: [
     '_version.py.in',
     '__pycache__',
     '*.pyc',
   ]
 )
+
+# Install mapflpy/fortran/__init__.py separately, so that the install_subdir
+# above can exclude the entire fortran/ directory.  Without this exclusion,
+# any compiled .so left in the source tree (e.g. from a dev install) would
+# be bundled into every wheel produced by "python -m build".
+install_data(
+  'mapflpy/fortran/__init__.py',
+  install_dir : py.get_install_dir() / 'mapflpy' / 'fortran',
+)

{mapflpy-1.1.9 → mapflpy-1.2.0}/noxfile.py

@@ -70,7 +70,23 @@ def _build_env(session: nox.Session) -> Path:
         *pyproject["tool"][PROJECT_NAME].get("conda", []),
         channel="conda-forge"
     )
-    session.env.update(_darwin_sdk_env())
+    env_dir = Path(session.env_dir).resolve()
+    lib_dir = str(env_dir / "lib")
+    # Override CONDA_PREFIX so conda-forge gfortran's spec file uses this env's
+    # lib dir for its implicit library search paths, not the active outer env.
+    env = {"CONDA_PREFIX": str(env_dir)}
+    env.update(_darwin_sdk_env())
+    if platform.system() == "Darwin":
+        # Pass an explicit rpath so delocate-wheel can bundle deps even when
+        # meson would otherwise embed a @loader_path-relative path.
+        env["LDFLAGS"] = (env.get("LDFLAGS", "") + f" -Wl,-rpath,{lib_dir}").strip()
+        # conda-forge's ld64_osx-64 linker may be invoked from the micromamba
+        # pkgs cache path (hard-linked), so @loader_path/../lib/libtapi.dylib
+        # resolves against the cache dir rather than the installed env.  Set a
+        # fallback so dyld finds libtapi.dylib in the env's lib/ dir instead.
+        existing = os.environ.get("DYLD_FALLBACK_LIBRARY_PATH", "")
+        env["DYLD_FALLBACK_LIBRARY_PATH"] = f"{lib_dir}:{existing}".strip(":")
+    session.env.update(env)
 
 
 def _dist_env(session: nox.Session) -> Path:

{mapflpy-1.1.9 → mapflpy-1.2.0}/pyproject.toml

@@ -16,7 +16,7 @@ requires = [
 # ----------------
 [project]
 name = "mapflpy"
-version = "1.1.9"
+version = "1.2.0"
 description = "Fast field line tracing for spherical vector fields"
 authors = [
   {name = "Predictive Science Inc.", email = "webmaster@predsci.com"},
@@ -296,4 +296,4 @@ conda = [
   "pkg-config",
   "hdf5",
   "zlib"
-]
+]