########################################## **The field modules and programs** ########################################## **Module mag_dipole_line** ====================================== **Module : mag_field_line** **Purpose : single field line** .. class:: field_line_t A field line object type :param vr(:,:): xyz position along the field line; index 1: x, y, or z dimension, so values are 1:3, index 2: s dimension, so values are 1:n -- real(WP), allocatable :param s(:): the length along the field line -- real(WP), allocatable :param vB(:,:): magnetic field along the field line; index 1: x, y, or z dimension, so values are 1:3, index 2: s dimension, so values are 1:n -- real(WP), allocatable :param n: number of grids along field line -- integer :param i_0: zero-point index where forwards and backwards tracing along a field meet -- integer :param foot_N: boolean for the north magnetic foot point being on the star -- integer :param foot_S: boolean for the south magnetic foot point being on the star -- integer .. function:: init_fl (n) result (fl) Construct a field line space for type variables vr, s, vB is allocated; type variable n is set type variables foot_N and foot_S are initialized to .FALSE. function :param n: number of points on the field line -- integer, intent(in) :rtype fl: returned field line with vr, s, vB, and n initialized -- :class:`field_line_t` .. function:: init_fl_trace_point (pf, st, r_0, R_outer, ds, tol, max_steps) result (fl) Construct a field line by tracing from an arbitrary specified point calls trace_point function :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param r_0(:): the specified point -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, intent(in), optional :rtype fl: computed and returned field line -- :class:`field_line_t` .. function:: init_fl_trace_star (pf, st, theta_0, phi_0, R_outer, ds, tol, max_steps) result (fl) Construct a field line by tracing from a specified point on the star function :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param theta_0: polar coordinate for field line tracing to start -- real(WP), intent(in) :param phi_0: azimuthal coordinate for field line tracing to start -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, intent(in), optional :rtype fl: computed and returned field line -- :class:`field_line_t` .. function:: discrim_star (vr) result (D) Calculate the discriminant for r being outside the star D = st_m%D_surf(vr) function :param vr(:): position of discriminant calcualtion -- real(WP), intent(in) :rtype D: calculated and returned discrimant -- real(WP) .. function:: discrim_source (vr) result (D) Calculate the discriminant for r being outside the source surface D = NORM2(vr) - R_source_m function :param vr(:): position of discriminant calculation -- real(WP), intent(in) :rtype D: calculated and returned discrimant -- real(WP) .. function:: discrim_outer (vr) result (D) Calculate the discriminant for r being outside the outer boundary D = NORM2(vr) - R_outer_m function :param vr(:): position of discriminant calculation -- real(WP), intent(in) :rtype D: calculated and returned discriminant -- real(WP) .. function:: read_fl (hg, fl) Read various attributes of a field line reads n, i_0, foot_N, foot_S, vr, s, vB only if hdf5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fl: field line -- :class:`field_line_t` .. function:: write_fl (hg, fl) Write various assets of a field line writes n, i_0, foot_N, foot_S, vr, s, vB only if hdf5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fl: field line -- :class:`field_line_t`, intent(in) .. function:: bcast_fl (fl, root_rank) Broadcast a field line vr, s, vB, n, i_0, foot_N, foot_S are broadcasted only if MPI subroutine :param fl: field line to broadcast -- :class:`field_line_t`, intent(inout) :param root_rank: rank of root processor -- integer, intent(in) .. function:: trace_point (pf, st, r_0, R_outer, ds, tol, max_steps, fl) Construct a field line by tracing from a specified point does the calculation here; traces forwards and backwards, then puts the results together computes vr, s, vB, n, i_0, foot_N, foot_S for field line class subroutine :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param r_0(:): the specified point -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, intent(in), optional :rtype fl: computed and returned field line -- :class:`field_line_t`, intent(out) .. function:: trace_star (pf, st, theta_0, phi_0, R_outer, ds, tol, max_steps, fl) Construct a field line by tracing from a specified point on the star does the calculation here; traces forwards only since starting from the star computes vr, s, vB, n, i_0, foot_N, foot_S for field line class subroutine :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param theta_0: polar coordinate for field line tracing to start -- real(WP), intent(in) :param phi_0: aziumthal coordinate for field line tracing to start -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, intent(in), optional :rtype fl: computed and returned field line -- :class:`field_line_t`, intent(out) .. function:: trace_1 (s, vr, bound, vr_0, del_s, tol, max_steps) Trace from the specified point in one direction called by both trace_point and trace_star subroutine :rtype s(:): position along ray in ray coordinate system -- real(WP), allocatable, intent(out) :rtype vr(:,:): 3D position of loop; index 1 is dimension, index 2 is loop point -- real(WP), allocatable, intent(out) :rtype bound: notes whether inside the star, outside the calculation domain, or in a region to continue computing the loop -- integer, intent(out) :param vr_0(:): initial point -- real(WP), intent(in) :param del_s(:): change in physical distance along the loop -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along loop -- integer, intent(in), optional .. function:: trace_1_inside () Trace inside the source surface using ODEPACK part of trace_1 subroutine subroutine .. function:: trace_1_outside () Trace outside the source surface using radial extrapolation part of trace_1 subroutine subroutine .. function:: trace_1_dipole Trace a dipole field part of trace_1 subroutine subroutine .. function:: odepack_rhs (neq, s, vr, vdr_ds) Calculate the rhs vector for ODEPACK subroutine :param neq: number of first-order ODEs; hardwired to 3 -- integer, intent(in) :param s: initial value of the independent variable -- real(WP), intent(in) :param vr(neq): array of initial values -- real(WP), intent(in) :rtype vdr_ds(neq): v*dr/ds; computed from vB of potential field -- real(WP), intent(out) .. function:: odepack_dummy () Dummy subroutine subroutine .. function:: odepack_discrim (neq, s, vr, ng, g_out) Calculate the root discriminant for ODEPACK subroutine :param neq: number of first-order ODEs; hardwired to 3 -- integer, intent(in) :param s: initial value of the independent variable -- real(WP), intent(in) :param vr(neq): array of initial values -- real(WP), intent(in) :param ng: number of constraint functions; hardwired to 2 -- integer, intent(in) :rtype g_out(ng): output of root information -- real(WP), intent(out) .. function:: nudge (vr, discrim, outside) Nudge r in the radial direction, so it lies inside or outside the surface represented by the discriminant function discrim subroutine :param vr(:): point from where the nudge occurs -- real(WP), intent(inout) :param discrim: evaluate the discriminant -- function discrim (vr) result (D) :param vr(:): point for evaluating the discriminant; within funciton discrim -- real(WP), intent(in) :param D: discriminant; within function discrim -- real(WP) :param outside: outside the surface (true) or not (false) -- logical, intent(in) .. function:: expand_1 (a, n) Expand 1D array until it has a size of at least n subroutine :param a(:): the array to expand -- real(WP), allocatable, intent(inout) :param n: the minimum size of the expanded array -- integer, intent(in) .. function:: expand_2 (a, n) Expand 2D array in its last dimension until it has a size of at least n subroutine :param a(:,:): the array to expand -- real(WP), allocatable, intent(inout) :param n: the minimum size of the second dimension of the expanded array -- integer, intent(in) **Module mag_field_line** ====================================== **Module : mag_field_line** **Purpose : single field line** .. class:: field_line_t A field line object type :param vr(:,:): xyz position along the field line; index 1: x, y, or z dimension, so values are 1:3, index 2: s dimension, so values are 1:n -- real(WP), allocatable :param s(:): the length along the field line -- real(WP), allocatable :param vB(:,:): magnetic field along the field line; index 1: x, y, or z dimension, so values are 1:3, index 2: s dimension, so values are 1:n -- real(WP), allocatable :param n: number of grids along field line -- integer :param i_0: zero-point index where forwards and backwards tracing along a field meet -- integer :param foot_N: boolean for the north magnetic foot point being on the star -- integer :param foot_S: boolean for the south magnetic foot point being on the star -- integer .. function:: field_line_t_ (n) result (fl) Construct a field line space for type variables vr, s, vB is allocated; type variable n is set type variables foot_N and foot_S are initialized to .FALSE. function :param n: number of points on the field line -- integer, intent(in) :rtype fl: returned field line with vr, s, vB, and n initialized -- :class:`field_line_t` .. function:: field_line_t_trace_point_ (pf, st, vr_0, R_outer, ds, tol, max_steps, move_s0_foot) result (fl) Construct a field line by tracing from an arbitrary specified point calls trace_point function :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param vr_0(:): the specified point -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, optional, intent(in) :param move_s0_foot: enforce s=0 at northern end -- logical, optional, intent(in) :rtype fl: computed and returned field line -- :class:`field_line_t` .. function:: field_line_t_trace_star_ (pf, st, theta_0, phi_0, R_outer, ds, tol, max_steps) result (fl) Construct a field line by tracing from a specified point on the star function :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param theta_0: polar coordinate for field line tracing to start -- real(WP), intent(in) :param phi_0: azimuthal coordinate for field line tracing to start -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, intent(in), optional :rtype fl: computed and returned field line -- :class:`field_line_t` .. function:: discrim_star_ (vr) result (D) Calculate the discriminant for r being outside the star D = st_m%D_surf(vr) function :param vr(:): position of discriminant calcualtion -- real(WP), intent(in) :rtype D: calculated and returned discrimant -- real(WP) .. function:: discrim_source_ (vr) result (D) Calculate the discriminant for r being outside the source surface D = NORM2(vr) - R_source_m function :param vr(:): position of discriminant calculation -- real(WP), intent(in) :rtype D: calculated and returned discrimant -- real(WP) .. function:: discrim_outer_ (vr) result (D) Calculate the discriminant for r being outside the outer boundary D = NORM2(vr) - R_outer_m function :param vr(:): position of discriminant calculation -- real(WP), intent(in) :rtype D: calculated and returned discriminant -- real(WP) .. function:: read_ (hg, fl) Read various attributes of a field line reads n, i_0, foot_N, foot_S, vr, s, vB only if hdf5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fl: field line -- :class:`field_line_t` .. function:: write_ (hg, fl) Write various assets of a field line writes n, i_0, foot_N, foot_S, vr, s, vB only if hdf5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fl: field line -- :class:`field_line_t`, intent(in) .. function:: bcast_ (fl, root_rank) Broadcast a field line vr, s, vB, n, i_0, foot_N, foot_S are broadcasted only if MPI subroutine :param fl: field line to broadcast -- :class:`field_line_t`, intent(inout) :param root_rank: rank of root processor -- integer, intent(in) .. function:: trace_point_ (pf, st, vr_0, R_outer, ds, tol, fl, max_steps, move_s0_foot) Construct a field line by tracing from a specified point does the calculation here; traces forwards and backwards, then puts the results together computes vr, s, vB, n, i_0, foot_N, foot_S for field line class subroutine :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param vr_0(:): the specified point -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, optional, intent(in) :param move_s0_foot: enforce s=0 at northern end -- logical, optional, intent(in) :rtype fl: computed and returned field line -- :class:`field_line_t`, intent(out) .. function:: trace_star_ (pf, st, theta_0, phi_0, R_outer, ds, tol, max_steps, fl) Construct a field line by tracing from a specified point on the star does the calculation here; traces forwards only since starting from the star computes vr, s, vB, n, i_0, foot_N, foot_S for field line class subroutine :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param theta_0: polar coordinate for field line tracing to start -- real(WP), intent(in) :param phi_0: azimuthal coordinate for field line tracing to start -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, optional, intent(in) :rtype fl: computed and returned field line -- :class:`field_line_t`, intent(out) .. function:: trace_1_ (s, vr, bound, vr_0, del_s, tol, max_steps) Trace from the specified point in one direction called by both trace_point and trace_star subroutine :rtype s(:): position along ray in ray coordinate system -- real(WP), allocatable, intent(out) :rtype vr(:,:): 3D position of loop; index 1 is dimension, index 2 is loop point -- real(WP), allocatable, intent(out) :rtype bound: notes whether inside the star, outside the calculation domain, or in a region to continue computing the loop -- integer, intent(out) :param vr_0(:): initial point -- real(WP), intent(in) :param del_s(:): change in physical distance along the loop -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along loop -- integer, optional, intent(in) .. function:: trace_1_inside_ () Trace inside the source surface using ODEPACK part of trace_1 subroutine subroutine .. function:: trace_1_outside_ () Trace outside the source surface using radial extrapolation part of trace_1 subroutine subroutine .. function:: trace_1_dipole_ Trace a dipole field part of trace_1 subroutine subroutine .. function:: odepack_rhs_ (neq, s, vr, vdr_ds) Calculate the rhs vector for ODEPACK subroutine :param neq: number of first-order ODEs; hardwired to 3 -- integer, intent(in) :param s: initial value of the independent variable -- real(WP), intent(in) :param vr(neq): array of initial values -- real(WP), intent(in) :rtype vdr_ds(neq): v*dr/ds; computed from vB of potential field -- real(WP), intent(out) .. function:: odepack_dummy_ () Dummy subroutine subroutine .. function:: odepack_discrim_ (neq, s, vr, ng, g_out) Calculate the root discriminant for ODEPACK subroutine :param neq: number of first-order ODEs; hardwired to 3 -- integer, intent(in) :param s: initial value of the independent variable -- real(WP), intent(in) :param vr(neq): array of initial values -- real(WP), intent(in) :param ng: number of constraint functions; hardwired to 2 -- integer, intent(in) :rtype g_out(ng): output of root information -- real(WP), intent(out) .. function:: nudge_ (vr, discrim, outside) Nudge r in the radial direction, so it lies inside or outside the surface represented by the discriminant function discrim subroutine :param vr(:): point from where the nudge occurs -- real(WP), intent(inout) :param discrim: evaluate the discriminant -- function discrim (vr) result (D) :param vr(:): point for evaluating the discriminant; within funciton discrim -- real(WP), intent(in) :param D: discriminant; within function discrim -- real(WP) :param outside: outside the surface (true) or not (false) -- logical, intent(in) .. function:: expand_1_ (a, n) Expand 1D array until it has a size of at least n subroutine :param a(:): the array to expand -- real(WP), allocatable, intent(inout) :param n: the minimum size of the expanded array -- integer, intent(in) .. function:: expand_2_ (a, n) Expand 2D array in its last dimension until it has a size of at least n subroutine :param a(:,:): the array to expand -- real(WP), allocatable, intent(inout) :param n: the minimum size of the second dimension of the expanded array -- integer, intent(in) **Module mag_field_line_bin** ====================================== **Module : mag_field_line_bin** **Purpose : single field line** .. class:: field_line_t A field line object type :param vr(:,:): xyz position along the field line; index 1: x, y, or z dimension, so values are 1:3, index 2: s dimension, so values are 1:n -- real(WP), allocatable :param s(:): the length along the field line -- real(WP), allocatable :param vB(:,:): magnetic field along the field line; index 1: x, y, or z dimension, so values are 1:3, index 2: s dimension, so values are 1:n -- real(WP), allocatable :param n: number of grids along field line -- integer :param i_0: zero-point index where forwards and backwards tracing along a field meet -- integer :param foot_N: boolean for the north magnetic foot point being on the star -- integer :param foot_S: boolean for the south magnetic foot point being on the star -- integer .. function:: field_line_t_ (n) result (fl) Construct a field line space for type variables vr, s, vB is allocated; type variable n is set type variables foot_N and foot_S are initialized to .FALSE. function :param n: number of points on the field line -- integer, intent(in) :rtype fl: returned field line with vr, s, vB, and n initialized -- :class:`field_line_t` .. function:: field_line_t_trace_point_ (pf, st, vr_0, R_outer, ds, tol, max_steps, move_s0_foot) result (fl) Construct a field line by tracing from an arbitrary specified point calls trace_point function :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param vr_0(:): the specified point -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, optional, intent(in) :param move_s0_foot: enforce s=0 at northern end -- logical, optional, intent(in) :rtype fl: computed and returned field line -- :class:`field_line_t` .. function:: field_line_t_trace_star_ (pf, st, theta_0, phi_0, R_outer, ds, tol, max_steps) result (fl) Construct a field line by tracing from a specified point on the star function :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param theta_0: polar coordinate for field line tracing to start -- real(WP), intent(in) :param phi_0: azimuthal coordinate for field line tracing to start -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, intent(in), optional :rtype fl: computed and returned field line -- :class:`field_line_t` .. function:: discrim_star_ (vr) result (D) Calculate the discriminant for r being outside the star D = st_m%D_surf(vr) function :param vr(:): position of discriminant calcualtion -- real(WP), intent(in) :rtype D: calculated and returned discrimant -- real(WP) .. function:: discrim_source_ (vr) result (D) Calculate the discriminant for r being outside the source surface D = NORM2(vr) - R_source_m function :param vr(:): position of discriminant calculation -- real(WP), intent(in) :rtype D: calculated and returned discrimant -- real(WP) .. function:: discrim_outer_ (vr) result (D) Calculate the discriminant for r being outside the outer boundary D = NORM2(vr) - R_outer_m function :param vr(:): position of discriminant calculation -- real(WP), intent(in) :rtype D: calculated and returned discriminant -- real(WP) .. function:: read_ (hg, fl) Read various attributes of a field line reads n, i_0, foot_N, foot_S, vr, s, vB only if hdf5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fl: field line -- :class:`field_line_t` .. function:: write_ (hg, fl) Write various assets of a field line writes n, i_0, foot_N, foot_S, vr, s, vB only if hdf5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fl: field line -- :class:`field_line_t`, intent(in) .. function:: bcast_ (fl, root_rank) Broadcast a field line vr, s, vB, n, i_0, foot_N, foot_S are broadcasted only if MPI subroutine :param fl: field line to broadcast -- :class:`field_line_t`, intent(inout) :param root_rank: rank of root processor -- integer, intent(in) .. function:: trace_point_ (pf, st, vr_0, R_outer, ds, tol, fl, max_steps, move_s0_foot) Construct a field line by tracing from a specified point does the calculation here; traces forwards and backwards, then puts the results together computes vr, s, vB, n, i_0, foot_N, foot_S for field line class subroutine :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param vr_0(:): the specified point -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, optional, intent(in) :param move_s0_foot: enforce s=0 at northern end -- logical, optional, intent(in) :rtype fl: computed and returned field line -- :class:`field_line_t`, intent(out) .. function:: trace_star_ (pf, st, theta_0, phi_0, R_outer, ds, tol, max_steps, fl) Construct a field line by tracing from a specified point on the star does the calculation here; traces forwards only since starting from the star computes vr, s, vB, n, i_0, foot_N, foot_S for field line class subroutine :param pf: potential field -- :class:`pot_field_t`, target, intent(in) :param st: star -- :class:`star_t`, target, intent(in) :param theta_0: polar coordinate for field line tracing to start -- real(WP), intent(in) :param phi_0: azimuthal coordinate for field line tracing to start -- real(WP), intent(in) :param R_outer: outer radius for field-line calculation -- real(WP), intent(in) :param ds: step size along the field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along the field line -- integer, optional, intent(in) :rtype fl: computed and returned field line -- :class:`field_line_t`, intent(out) .. function:: trace_1_ (s, vr, bound, vr_0, del_s, tol, max_steps) Trace from the specified point in one direction called by both trace_point and trace_star subroutine :rtype s(:): position along ray in ray coordinate system -- real(WP), allocatable, intent(out) :rtype vr(:,:): 3D position of loop; index 1 is dimension, index 2 is loop point -- real(WP), allocatable, intent(out) :rtype bound: notes whether inside the star, outside the calculation domain, or in a region to continue computing the loop -- integer, intent(out) :param vr_0(:): initial point -- real(WP), intent(in) :param del_s(:): change in physical distance along the loop -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along loop -- integer, optional, intent(in) .. function:: trace_1_inside_ () Trace inside the source surface using ODEPACK part of trace_1 subroutine subroutine .. function:: trace_1_outside_ () Trace outside the source surface using radial extrapolation part of trace_1 subroutine subroutine .. function:: trace_1_dipole_ Trace a dipole field part of trace_1 subroutine subroutine .. function:: odepack_rhs_ (neq, s, vr, vdr_ds) Calculate the rhs vector for ODEPACK subroutine :param neq: number of first-order ODEs; hardwired to 3 -- integer, intent(in) :param s: initial value of the independent variable -- real(WP), intent(in) :param vr(neq): array of initial values -- real(WP), intent(in) :rtype vdr_ds(neq): v*dr/ds; computed from vB of potential field -- real(WP), intent(out) .. function:: odepack_dummy_ () Dummy subroutine subroutine .. function:: odepack_discrim_ (neq, s, vr, ng, g_out) Calculate the root discriminant for ODEPACK subroutine :param neq: number of first-order ODEs; hardwired to 3 -- integer, intent(in) :param s: initial value of the independent variable -- real(WP), intent(in) :param vr(neq): array of initial values -- real(WP), intent(in) :param ng: number of constraint functions; hardwired to 2 -- integer, intent(in) :rtype g_out(ng): output of root information -- real(WP), intent(out) .. function:: nudge_ (vr, discrim, outside) Nudge r in the radial direction, so it lies inside or outside the surface represented by the discriminant function discrim subroutine :param vr(:): point from where the nudge occurs -- real(WP), intent(inout) :param discrim: evaluate the discriminant -- function discrim (vr) result (D) :param vr(:): point for evaluating the discriminant; within funciton discrim -- real(WP), intent(in) :param D: discriminant; within function discrim -- real(WP) :param outside: outside the surface (true) or not (false) -- logical, intent(in) .. function:: expand_1_ (a, n) Expand 1D array until it has a size of at least n subroutine :param a(:): the array to expand -- real(WP), allocatable, intent(inout) :param n: the minimum size of the expanded array -- integer, intent(in) .. function:: expand_2_ (a, n) Expand 2D array in its last dimension until it has a size of at least n subroutine :param a(:,:): the array to expand -- real(WP), allocatable, intent(inout) :param n: the minimum size of the second dimension of the expanded array -- integer, intent(in) **Module mag_field_vol** ====================================== **Module : mag_field_vol** **Purpose : magnetosphere field data** .. class:: field_vol_t A field volume object type with contains that adds procedures type, extends (volume_t) :param pf: potential field -- :class:`pot_field_t` :param st: star -- :class:`star_t` :param field_mask(:,:,:): mask for field nodes; true if field line goes through the particular -- logical, allocatable :param star_mask(:,:,:): mask for star nodes; true if particular node is in the star -- logical allocatable :param build: loops over building, processing, and broadcasting nodes -- procedure :param build_node: build a single node -- procedure :param process_node: process a single node -- procedure :param bcast-nodes: broadcast nodes if MPI -- procedure .. function:: field_vol_t_ (vl, pf, st) result (fv) Construct the field_vol_t sets volume, potential field, and star; allocates space for field_mask and star_mask function :param vl: volume --- :class:`volume_t`, intent(in) :param pf: potential field --- :class:`pot_field_t`, intent(in) :param st: star --- :class:`star_t`, intent(in) :rtype fv: field volume --- :class:`field_vol_t` .. function:: read_ (hg, fv) Read the field_vol_t read variables are volume, potential field, star, field_mask, and star_mask only if HDF5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :rtype fv: field volume -- :class:`field_vol_t`, intent(out) .. function:: write_ (hg, fv) Write the field_vol_t written variables are volume, potential field, star, field_mask, and star_mask only if HDF5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fv: field volume -- :class:`field_vol_t`, intent(in) .. function:: build (this, R_outer, ds, tol, max_steps) Process, build, and broadcast the nodes subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param R_outer: outer radius -- real(WP), intent(in) :param ds: step size along field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along field line -- integer, optional, intent(in) .. function:: build_node (this, vi, R_outer, ds, tol, max_steps) Build the node subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param vi(:): node index -- integer, intent(in) :param R_outer: outer radius -- real(WP), intent(in) :param ds: step size along field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along field line -- integer, optional, intent(in) .. function:: process_node (this, vi, fl) Process the node checks that node index vi has size of 3 subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param vi(:): node index -- integer, intent(in) :param fl: field volume -- :class:`field_line_t`, intent(in) .. function:: bcast_ (fv, root_rank) Broadcast the field_vol_t only if MPI subroutine :param fv: field volume -- :class:`field_vol_t), intent(inout) :param root_rank: rank of root processor -- integer, intent(in) .. function:: bcast_nodes (this, vi_a, vi_b, root_rank) Broadcast the nodes with indices between vi_a and vi_b only if MPI subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param vi_a(:): lower limit of node indices -- integer, intent(in) :param vi_b(:): upper limit of node indices -- integer, intent(in) :param root_rank: rank of root processor -- integer, intent(in) **Module mag_field_vol_bin** ====================================== **Module : mag_field_vol_bin** **Purpose : magnetosphere field data** .. class:: field_vol_t A field volume object type with contains that adds procedures type, extends (volume_t) :param pf: potential field -- :class:`pot_field_t` :param st: star -- :class:`star_t` :param field_mask(:,:,:): mask for field nodes; true if field line goes through the particular -- logical, allocatable :param star_mask(:,:,:): mask for star nodes; true if particular node is in the star -- logical allocatable :param build: loops over building, processing, and broadcasting nodes -- procedure :param build_node: build a single node -- procedure :param process_node: process a single node -- procedure :param bcast-nodes: broadcast nodes if MPI -- procedure .. function:: field_vol_t_ (vl, pf, st) result (fv) Construct the field_vol_t sets volume, potential field, and star; allocates space for field_mask and star_mask function :param vl: volume --- :class:`volume_t`, intent(in) :param pf: potential field --- :class:`pot_field_t`, intent(in) :param st: star --- :class:`star_t`, intent(in) :rtype fv: field volume --- :class:`field_vol_t` .. function:: read_ (hg, fv) Read the field_vol_t read variables are volume, potential field, star, field_mask, and star_mask only if HDF5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :rtype fv: field volume -- :class:`field_vol_t`, intent(out) .. function:: write_ (hg, fv) Write the field_vol_t written variables are volume, potential field, star, field_mask, and star_mask only if HDF5 subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param fv: field volume -- :class:`field_vol_t`, intent(in) .. function:: build (this, R_outer, ds, tol, max_steps) Process, build, and broadcast the nodes subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param R_outer: outer radius -- real(WP), intent(in) :param ds: step size along field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along field line -- integer, optional, intent(in) .. function:: build_node (this, vi, R_outer, ds, tol, max_steps) Build the node subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param vi(:): node index -- integer, intent(in) :param R_outer: outer radius -- real(WP), intent(in) :param ds: step size along field line -- real(WP), intent(in) :param tol: tolerance -- real(WP), intent(in) :param max_steps: maximum steps along field line -- integer, optional, intent(in) .. function:: process_node (this, vi, fl) Process the node checks that node index vi has size of 3 subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param vi(:): node index -- integer, intent(in) :param fl: field volume -- :class:`field_line_t`, intent(in) .. function:: bcast_ (fv, root_rank) Broadcast the field_vol_t only if MPI subroutine :param fv: field volume -- :class:`field_vol_t`, intent(inout) :param root_rank: rank of root processor -- integer, intent(in) .. function:: bcast_nodes (this, vi_a, vi_b, root_rank) Broadcast the nodes with indices between vi_a and vi_b only if MPI subroutine :param this: field volume -- :class:`field_vol_t`, intent(inout) :param vi_a(:): lower limit of node indices -- integer, intent(in) :param vi_b(:): upper limit of node indices -- integer, intent(in) :param root_rank: rank of root processor -- integer, intent(in) **Module mag_harmonic** ====================================== **Module : mag_harmonic** **Purpose : spherical harmonics** .. function:: factorial (a) result (af) Calculate the factorial a! function :param a: input variable -- integer, intent(in) :rtype af: factorial of input variable -- real(WP) .. function:: Y_lm_tableaux (theta, phi, Y_lm, grad_Y_lm_theta, grad_Y_lm_phi) Create a tableaux of spherical harmonics Y_lm(theta, phi) for m >= 0 subroutine :param theta: polar coordinate -- real(WP), intent(in) :param phi: azimuthal coordinate -- real(WP), intent(in) :rtype Y_lm(0:,0:): spherical harmonic table -- complex(WP), intent(out) :rtype grad_Y_lm_theta(0:,0:): gradients in the theta direction -- complex(WP), intent(out), optional :rtype grad_Y_lm_phi(0:,0:): gradients in the phi direction -- complex(WP), intent(out), optional **Module mag_pot_field** ====================================== **Module : mag_pot_field** **Purpose : force-free potential fields** .. class:: pot_field_t .. function:: pot_field_t_ (l_max) result (pf) Construct the pot_field_t allocates G_lm, a_lm, and b_lm in pf class function :param l_max: truncate G_lm to level l_max; array size is {0:l_max,-l_max:l_max} -- integer, intent(in) :rtype pf: potential field -- :class:`pot_field_t` .. function:: pot_field_t_coeffs_ (G_lm, va) result (pf) Construct the pot_field from the expansion coefficients function :param G_lm(:,:): spherical harmonic coefficients to set -- complex(WP), intent(in) :param va(:): center of magnetic-centered frame -- real(WP), intent(in) :rtype pf: potential field -- :class:`pot_field_t` .. function:: is_dipole_ (this) result (is_dipole) Determine whether the potential represents a pure dipole function :param this: potential field -- :class:`pot_field_t`, intent(in) :param is_dipole: is the field a dipole or not -- logical .. function:: vB_ (this, vr, outside_source) result (vB) Evaluate the magnetic field at vr Calculate the spherical-polar coordinates in the magnetic-centered frame function :param this: potential field -- :class:`pot_field_t`, intent(in) :param vr(:): location of magnetice-field evaluation -- real(WP), intent(in) :param outside_source: outside the source or not -- logical, intent(in), optional :rtype vB(3): magnetic field -- real(WP) .. function:: read_ (hg, pf) Read the pot_field_t read variables are l_max, R_source, va, G_lm subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :rtype pf: potential field -- :class:`pot_field_t`, intent(out) .. function:: write_ (hg, pf) Write the pot_field_t written variables are l_max, R_source, va, G_lm subroutine :param hg: hdf5 data set -- :class:`hgroup_t`, intent(inout) :param pf: potential field -- :class:`pot_field_t`, intent(in) .. function:: get_R_source_ (this, R_source) Get the source-surface radius subroutine :param this: potential field -- :class:`pot_field_t`, intent(in) :rtype R_source: source radius -- real(WP), intent(out) .. function:: set_R_source_ (this, R_source) Set the source-surface radius to R_source subroutine :param this: potential field -- :class:`pot_field_t`, intent(inout) :param R_source: source radius -- real(WP), intent(in) .. function:: dipole_params_ (this, B_pole, beta, gamma, va) Calculate the parameters of the dipole component of the field subroutine :param this: potential field -- :class:`pot_field_t`, intent(in) :rtype B_pole: magnetic field at the pole -- real(WP), optional, intent(out) :rtype beta: angle between rotation axis and magnetic axis; rotation axis is z axis -- real(WP), optional, intent(out) :rtype gamma: azimuthal angle of magnetic axis; measured from x-axis to y-axis -- real(WP), optional, intent(out) :rtype va(:): magnetic center of star -- real(WP), optional, intent(out) .. function:: bcast_ (pf, root_rank) Broadcast the pot_field_t only if MPI subroutine :param pf: potential field to broadcast -- :class:`pot_field_t`, intent(inout) :param root_rank: rank of root processor -- integer, intent(in) **Module build_field_line** ====================================== **Module build_field_lines** ====================================== **Program : build_field_lines** **Purpose : build field_lines** .. function:: random () Calculates a random number from [0,1) via the built-in fortran function RANDOM_NUMBER :rtype real(WP) random: computed and returned random number **Module build_field_map** ====================================== **Program : build_field_map** **Purpose : build & analyze a surface map of the field** **Module build_pot_field** ====================================== **Program : build_pot_field** **Purpose : build force-free potential fields** .. function:: pf_oblique_dipole (beta, gamma, va, B_d_pole) result (pf) .. function:: pf_oblique_diquad (beta, gamma, va, B_d_pole, B_q_pole) result (pf) .. function:: pf_invers10 (map_file, l_max, flip_lat, flip_lon) result (pf) .. function:: pf_donati (map_file, l_max, flip_lat, flip_lon) result (pf) .. function:: pf_invers10_read (map_file, n_lat, n_lon, lat, lon, B_r) .. function:: pf_donati_read (map_file, n_lat, n_lon, lat, lon, B_r) .. function:: pf_lat_lon_expand (pf, l_max, n_lat, n_lon, lat, lon, B_r) **Module calc_b_z** ====================================== **Program : calc_b_z** **Purpose : calculate longitudinal field strength** .. function:: init_pot_field (unit, pf) .. function:: init_star (unit, st, inc, u_limb, grav_dark) .. function:: init_geom (unit, x, y, phase) .. function:: init_output (unit, map_prefix, int_filename) **Module dipole_params** ====================================== **Program : dipole_params** **Purpose : extract dipole parameters from a potential field** **Module measure_loops** ====================================== **Program : measure_loops** **Purpose : measure properties of closed field loops** .. function:: random () **Module test_mag_harmonic** ====================================== **Module : test_mag_harmonic** **Purpose : test mag_harmonic module**