# Quick Start

This chapter describes how to get started with using `pyCoilGen`.

## Calling the Application

`pyCoilGen` has a command line interface and a Python API.

### Command Line Interface

To call `pyCoilGen` from the command line, provide the [required parameters](./configuration.md) preceded with `--`:

```bash
pyCoilGen --parameter1 value1 --parameter2 value2 ....
```

For example:

```bash
pyCoilGen --coil_mesh_file cylinder_radius500mm_length1500mm.stl --field_shape_function 'y'
```

You can access the help with `-h`. All parameters are also described in detail in the [Configuration](./configuration.md) chapter. 

### Python API

`pyCoilGen` also has a Python API. You can define the values for parameters in a dictionary that is then passed to the `pyCoilGen` function to determine the solution. All parameters are described in detail in the [Configuration](./configuration.md) chapter. 

The following code snippet shows an example of a basic Python script:

```python
import logging 
from pyCoilGen.pyCoilGen_release import pyCoilGen
from pyCoilGen.sub_functions.constants import DEBUG_BASIC

log = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)

# Change the default values to suit your application
arg_dict = {
    'field_shape_function': 'y',    # definition of the target field ['x']
    'coil_mesh_file': 'create cylinder mesh',
    'cylinder_mesh_parameter_list': [0.8, 0.154, 30, 30, 0, 0, 1, 0],
    'min_loop_significance': 3,     # [1] Remove loops if they contribute less than 3% to the target field.
    'target_region_radius': 0.1,    # [0.15] in meter
    'pot_offset_factor': 0.25,      # [0.5] a potential offset value for the minimal and maximal contour potential
    'interconnection_cut_width': 0.025,  # [0.01] the width for the interconnections are interconnected; in meter
    # the length for which overlapping return paths will be shifted along the surface normals; in meter
    'normal_shift_length': 0.01,    # [0.001]
    'make_cylindrical_pcb': True,   # [False]

    'output_directory': 'images',   # [Current directory]
    'project_name': 'example_ygradient',
}

solution = pyCoilGen(log, arg_dict)         # Calculate the solution
```


## Viewing Results

A quick and simple way to view the generated `.stl` mesh is to use a [free online STL viewer](https://www.viewstl.com/).
```{figure} figures/mesh_example_gradient_3D.png
:scale: 100 %
:align: center
:alt: A 3D rendered view of the `.stl` swept output.

A 3D rendering of the `.stl` output for the `example_ygradient` code snippet.
```

The following code snippet shows an example of a basic Python script to view the results generated by the previous example.

```python
from os import makedirs

import matplotlib.pyplot as plt
from pyCoilGen.helpers.persistence import load
import pyCoilGen.plotting as pcg_plt

which = 'example_ygradient'
solution = load('debug', which, 'final')
save_dir = f'{solution.input_args.output_directory}'
makedirs(save_dir, exist_ok=True)

coil_solutions = [solution]

# Plot a multi-plot summary of the solution
pcg_plt.plot_various_error_metrics(coil_solutions, 0, f'{which}', save_dir=save_dir)

# Plot the 2D projection of stream function contour loops.
pcg_plt.plot_2D_contours_with_sf(coil_solutions, 0, f'{which} 2D', save_dir=save_dir)
pcg_plt.plot_3D_contours_with_sf(coil_solutions, 0, f'{which} 3D', save_dir=save_dir)
```

This creates 3 figures in the `images` directory:
```{figure} figures/plot_errors_example_ygradient.png
:scale: 50 %
:align: center
:alt: A plot of the various parameters for the example_ygradient.py code snippet.

A plot of the various parameters for the `example_ygradient` code snippet.
```

```{figure} figures/plot_example_ygradient_2D.png
:scale: 75 %
:align: center
:alt: A 2D plot of the stream function and computed contours for the example_ygradient.py code snippet.

A 2D plot of the stream function and computed contours for the `example_ygradient` code snippet.
```
```{figure} figures/plot_example_ygradient_3D.png
:scale: 100 %
:align: center
:alt: A 3D plot of the stream function and computed contours example_ygradient code snippet.

A 3D plot of the stream function and computed contours for the `example_ygradient` code snippet.
```


## Running the Examples

**pyCoilGen** also provides example scripts.

After [installing **pyCoilGen** and the extra data package](./installation.md#installation), the quickest way to run
the examples is to clone the GitHub repository and run the examples in the `pyCoilGen/examples` directory.

### Linux
```bash
$ git clone https://github.com/kev-m/pyCoilGen --depth=1
$ cd pyCoilGen/examples
$ python biplanar_xgradient.py
```

### Windows
```powershell
C:> git clone https://github.com/kev-m/pyCoilGen --depth=1
C:> cd pyCoilGen\examples
C:> python biplanar_xgradient.py
```