:py:mod:`aces.utilities.emsim.coord`
====================================

.. py:module:: aces.utilities.emsim.coord

.. autoapi-nested-parse::

   Coordinate transformations



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


Functions
~~~~~~~~~

.. autoapisummary::

   aces.utilities.emsim.coord.move_main_beam_from_z_to_x
   aces.utilities.emsim.coord.rotate_field_z_to_x
   aces.utilities.emsim.coord.rotate_xyz_about_x
   aces.utilities.emsim.coord.xyz_to_rtp
   aces.utilities.emsim.coord.cartesian_to_spherical_basis
   aces.utilities.emsim.coord.project_field_slow
   aces.utilities.emsim.coord.project_field



.. py:function:: move_main_beam_from_z_to_x(xyz)

   Convert cartesian (x,y,z) with main beam at positive z to cartesian (x,y,z) with main beam at positive x.  This is 
   equivalent to a 90 degree rotation about the y axis.

   Args:
       xyz (`numpy.ndarray`): matrix of cartesian coordinates with one row per point (N_POINTS, 3)
       
   Returns:
       rotated_xyz (`numpy.ndarray`): xyz rotated 90 deg about the Y axis so that the main beam is at positive x 
       instead of positive z


.. py:function:: rotate_field_z_to_x(e_field)

   Convert pattern with main beam at positive z to pattern with main beam at positive x.  This is 
   equivalent to a 90 degree rotation about the y axis.

   Args:
       e_field (`numpy.ndarray`): matrix of e_field components in cartesian coordinates with one row per point 
           (N_POINTS, 3)
       
   Returns:
       rotated_e_field (`numpy.ndarray`): e_field rotated 90 deg about the Y axis so that the main beam is at positive 
       x instead of positive z


.. py:function:: rotate_xyz_about_x(xyz, theta)

   Rotate coordinate system (x,y,z) about x axis by theta radians

   Args:
       xyz (`numpy.ndarray`): matrix of cartesian coordinates with one row per point (N_POINTS, 3)
       theta (float): angle of rotation in radians
       
   Returns:
       rotated_xyz (`numpy.ndarray`): xyz rotated by theta radians about the x axis


.. py:function:: xyz_to_rtp(xyz)

   Convert cartesian (x,y,z) coordinates to spherical (r, theta, phi)

   Args:
       xyz (`numpy.ndarray`): matrix of cartesian coordinates with one row per point (N_POINTS, 3)

   Returns:
       rtp: spherical coordinates (r,theta,phi) in radians


.. py:function:: cartesian_to_spherical_basis(xyz)

   Calculate spherical coordinate basis for given direction in cartesian basis

   Args:
       xyz (`numpy.ndarray`): matrix of cartesian coordinates with one row per point (N, 3)
       
   Returns:
       a_r (`numpy.ndarray`): matrix of a_r (radius) basis vectors in cartesian coordinates (N, 3) corresponding to 
           each direction (row) in xyz
       a_t (`numpy.ndarray`): matrix of a_t (theta) basis vectors in cartesian coordinates (N, 3) corresponding to each
           direction (row) in xyz
       a_p (`numpy.ndarray`): matrix of a_p (phi) basis vectors in cartesian coordinates (N, 3) corresponding to each
           direction (row) in xyz


.. py:function:: project_field_slow(e_field, a_1, a_2, a_3)

   Project electric field (pattern) onto given basis

   Args:
       e_field (`numpy.ndarray`): (M,N,3) complex valued electric field with 3 vector components (columns) evaluated at 
           N points (rows) for M ports
       a_1 ():  (N,3) coordinate system basis vector a_1 for each of N points (directions)
       a_2 ():  (N,3) coordinate system basis vector a_2 for each of N points (directions)
       a_3 ():  (N,3) coordinate system basis vector a_3 for each of N points (directions)



.. py:function:: project_field(e_field, a_1, a_2, a_3)

   Project electric field (pattern) onto given basis

   Args:
       e_field (`numpy.ndarray`): (M,N,3) complex valued electric field with 3 vector components (columns) evaluated at 
           N points (rows) for M ports
       a_1 ():  (N,3) coordinate system basis vector a_1 for each of N points (directions)
       a_2 ():  (N,3) coordinate system basis vector a_2 for each of N points (directions)
       a_3 ():  (N,3) coordinate system basis vector a_3 for each of N points (directions)