3. Quick Start

This chapter describes how to get started with using pyCoilGen.

3.1. Calling the Application

pyCoilGen has a command line interface and a Python API.

3.1.1. Command Line Interface

To call pyCoilGen from the command line, provide the required parameters preceded with --:

pyCoilGen --parameter1 value1 --parameter2 value2 ....

For example:

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

3.1.2. 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 chapter.

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

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

3.2. Viewing Results

A quick and simple way to view the generated .stl mesh is to use a free online STL viewer.

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.

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:

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

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

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

3.3. Running the Examples

pyCoilGen also provides example scripts.

After installing pyCoilGen and the extra data package, the quickest way to run the examples is to clone the GitHub repository and run the examples in the pyCoilGen/examples directory.

3.3.1. Linux

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

3.3.2. Windows

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