magoptlib.synthetic_measurement
===============================

.. py:module:: magoptlib.synthetic_measurement


Functions
---------

.. autoapisummary::

   magoptlib.synthetic_measurement.fibonacci_lattice
   magoptlib.synthetic_measurement.simulate_magnetic_measurement


Module Contents
---------------

.. py:function:: fibonacci_lattice(n_theta, n_phi)

   Generate Fibonacci lattice points on a sphere.
   Returns arrays of spherical coordinates theta and phi.


.. py:function:: simulate_magnetic_measurement(n_theta: int = 10, n_phi: int = 10, radius: float = 50, noise_level: float = 0.01, noise: bool = False, magnet: magpylib.magnet.Cuboid | None = None)

   Simulate synthetic magnetic field measurements using a Fibonacci lattice.
   :param n_theta: Discretisation of the Fibonacci lattice in polar and azimuthal direction.
   :param n_phi: Discretisation of the Fibonacci lattice in polar and azimuthal direction.
   :param radius: Radius of the spherical surface of the measurement sphere.
   :param noise_level: Relative standard deviation of the Gaussian noise.
   :param noise: If ``True`` Gaussian noise is added independently to each field component.
   :param magnet: Optional `magpylib` magnet object. Default is a 12 mm cubic magnet with
                  a polarisation of ``(0, 0, 1390)`` [mT].

   :returns: Arrays ``Bx``, ``By`` and ``Bz`` of shape ``(n_points,)`` containing the
             magnetic field at each lattice point, as well as the polar coordinates
             ``theta_values`` and ``phi_values`` used to construct the lattice.
   :rtype: tuple of ``numpy.ndarray``

   .. rubric:: Examples

   The function returns one-dimensional arrays that can easily be promoted to
   the ``(n_magnets, n_points)`` shape used by the GPU-accelerated routines.

   >>> Bx, By, Bz, theta, phi = simulate_magnetic_measurement(n_theta=10, n_phi=10)

   Repeating the measurement in a loop and concatenating along the first axis
   yields the demanded structure:

   >>> measurements = [
   ...    simulate_magnetic_measurement(n_theta=10, n_phi=10)
   ...    for _ in range(16)
   ...]
   >>> Bx, By, Bz, theta, phi = (
   ...    np.stack([fields[idx] for fields in measurements], axis=0)
   ...    for idx in range(5)
   ... )
   >>> assert Bx.shape == By.shape == Bz.shape == (16, 100)