Build_pot_field

Introduction

Purpose: Create a file that contains a potential field object to use later on in other codes.

Example of other programs that use a potential field object: _______

The potential field object is defined here: Link to the class manual.

Background

A force-free field can be defined by a scalar potential such that \(\vec{B}=\nabla \Phi\). Because \(\nabla \times \vec{B}=0\), then we get a differential equation \(\nabla^2\Phi=0\) that we can solve with two boundaries conditions:

  • Inner: The field at the surface is known.

  • Outer: (1) The field \(\vec{B}(r \rarr \infty) = 0\) or (2) \(\vec{B}_{\theta,\phi}(r=R_s)=0\), where \(R_s\) is usually referred to as the source radius at which the field becomes entirely radial.

The solution is a summation of spherical harmonics with coefficients \(a_{lm}\) and \(b_{lm}\).

If the field at the inner boundary can itself be expressed as a sum of spherical harmonics \(G_{lm}\) (which is the case for e.g. a dipole, or a ZDI reconstruction in spherical harmonics), then the solutions for the coefficients \(a_{lm}\) and \(b_{lm}\) are also analytic.

The magnetic field at position (x,y,z) can be then determined by taking the gradient of the potential \(\vec{B}=\nabla \Phi\).

The purpose of a pot_field object is to store the spherical harmonics \(G_{lm}\) that are used at the inner boundary, provide a calculation of the \(a_{lm}\) and \(b_{lm}\) given a source radius \(R_s\), and provides a method that will return the magnetic field at a given coordinate.

Usage

The Build_pot_field program will create a pot_field objects for various types of pre-built boundary conditions for the surface field.

This program creates the pot_field object and save it to a file, but each subsequent call to the set_R_source function in other programs will re-evaluate the \(a_{lm}\) and \(b_{lm}\) coefficients. Sometimes the R_source also shows up as an option of the other program. Thus it not always necessary to create multiple pot_field files that only differ by their source radius. Need to keep an eye for that.

$PATH/mag/field/build_pot_field < input_file.in

The input file has the following options:

  • field_type_str [OBLIQUE_DIPOLE / OBLIQUE_DIQUAD / INVERS10 / DONATI ] Defined the type of boundary condition at the surface

    • OBLIQUE_DIPOLE: a dipole surface field

      • beta: angle with respect to the z axis (which is the rotation axis) and

      • gamma [0]: is defined from the x-axis to the y-axis CHECK THAT IN MY NOTES.

      • B_d_pole: field strength for the dipole

    • OBLIQUE_DIQUAD: a dipole + quadrupole (aligned with each other)

      • Same parameters as OBLIQUE_DIPOLE, plus:

      • B_q_pole: field strength for the quadrupole

    • INVERS10: a latitude/longitude map from Oleg’s Invers10 code

      • map_file: The name of the file containing the map

      • flip_lat [False]: Whether the map needs to be flipped to match the coordinate system defined in these codes.

      • flip_lon [False]: Same as flip_lat for for the longitude of the map.

  • l_max: Truncate the \(G_{lm}\) to level \(l\). The maps are ‘fitted’ with a sum of spherical harmonics (see Y_lm_tableaux). Thus the sum needs to be truncated somewhat.

  • va [0]: The center of the magnetic-centered frame (so that it is possible to decenter the dipole with respect to the star_t object reference frame.

  • R_source [infty]: See note above set_R_source function.

  • pf_file: The name of the output h5 file that will contain the potential field object. By convention, use *pf_**.*h5 as suffix.

Example of a input file for a centered dipole field

&params
	field_type_str = 'OBLIQUE_DIPOLE',
	va(1) = 0.0
	va(2) = 0.0
	va(3) = 0.0
	beta = 90.
  gamma = 90.
	B_d_pole = 1e3,
	pf_file = 'pf_beta90gamma90.h5',
/