# 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. 

```python
$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

```python
&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',
/
```