Magnetic Fields - All About¶

This is all about the types of magnetic fields that are available in OSCARS. This includes:

Uniform fields
Gaussian fields
Undulator Fields
Importing field data from files
Python function for magnetic field
Combining different fields

You can also rotate and translate any field easily as is shown in several of the examples.

There are several ways to import field data. For 2D and 3D grids the grid must be regular. For 1D spatial data you may import non-equidistant points.

# matplotlib plots inline
%matplotlib inline

# Import the OSCARS SR module
import oscars.sr

# Import OSCARS plots (matplotlib)
from oscars.plots_mpl import *

OSCARS v2.1.8 - Open Source Code for Advanced Radiation Simulation
Brookhaven National Laboratory, Upton NY, USA
http://oscars.bnl.gov
oscars@bnl.gov

# Create a new OSCARS SR object
osr = oscars.sr.sr()

Uniform Field¶

A uniform field can be specified for all space or in a given width. The width input list is like a vector representing the length and direction of the field. It will be centered at [0, 0, 0] unless translated

add_bfield_uniform can be thought of as a box where width are the dimensions. If any dimension is 0 it is infinite in that dimension.

# Clear any previous fields and add a constant magnetic field of 0.4 [T]
# in the negative Y-direction with a length of 1m in the Z-direction
osr.clear_bfields()
osr.add_bfield_uniform(bfield=[0, -0.4, 0], width=[0, 0, 0.5])

# Plot the field if you like
plot_bfield(osr)

# The same field as above, but translated in space
osr.clear_bfields()
osr.add_bfield_uniform(bfield=[0, -0.4, 0], width=[0, 0, 0.5], translation=[0, 0, 0.3])

# Plot the field if you like
plot_bfield(osr)

# The same field as above, but on a different axis
osr.clear_bfields()
osr.add_bfield_uniform(bfield=[0, 0, -0.4], width=[0, 0.5, 0])

# Plot the field if you like
plot_bfield(osr, axis='Y')

# You can also rotate the field and plot it as a function of a line through any two points
osr.clear_bfields()
osr.add_bfield_uniform(bfield=[0, 0, 4], width=[1, 2, 1], rotations=[0, 0, osr.pi()/4])

# Plot the field if you like
plot_bfield(osr, -2, 2, axis='Y')
plot_bfield(osr, between_two_points=[[-1, -1, 0], [1, 1, 0]])

Gaussian Field¶

This is a gaussian field in 3D. One can specify the 'sigma' in 1 2, or 3 dimensions

# This is a gaussian with one dimension specified.
osr.clear_bfields()
osr.add_bfield_gaussian(bfield=[0, 1, 0], sigma=[0, 0, 0.1], translation=[0, 0, 0.2])

# Plot the field if you like
plot_bfield(osr)

# This is a gaussian with 3 dimensions specified
osr.clear_bfields()
osr.add_bfield_gaussian(bfield=[1, 2, 3], sigma=[0.05, 0.05, 0.3])

# Plot the field if you like
plot_bfield(osr, axis='X')
plot_bfield(osr, axis='Y')
plot_bfield(osr, axis='Z')

# One can also rotate and translate the gaussian object
osr.clear_bfields()
osr.add_bfield_gaussian(bfield=[1, 2, 0], sigma=[0.05, 0.05, 0.3], rotations=[0, osr.pi()/2, 0], translation=[0, -0.2, 0])

# Plot the field if you like
plot_bfield(osr, axis='X', ylim=[-2, 2])
plot_bfield(osr, axis='Y', ylim=[-2, 2])
plot_bfield(osr, axis='Z', ylim=[-2, 2])

Undulator Field¶

It is simple to create a basic undulator field with termination using 'add_undulator'. You must specify the period (given as a vector), the number of periods, and the peak bfield

# This is the basic planer undulator field
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=21)

# Plot the field if you like
plot_bfield(osr, -1, 1, axis='Z')

# This is the basic planer undulator field where the axis is in an arbitrary direction
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0.050, 0, 0.050], nperiods=21)

# Plot the field if you like
plot_bfield(osr, between_two_points=[[-1, 0, -1], [1, 0, 1]])

# This is the field of an EPU.  Simply add two undulator fields offset in phase
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.100], nperiods=11, phase=-osr.pi()/4)
osr.add_bfield_undulator(bfield=[1, 0, 0], period=[0, 0, 0.100], nperiods=11, phase=+osr.pi()/4)

# Plot the field if you like
plot_bfield(osr)

# One can also rotat and translate an undulator field
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[1, 2, 3], period=[0, 0, 0.050], nperiods=21, rotations=[0, 0, osr.pi()/2.], translation=[0, 0, -0.3])

# Plot the field if you like
plot_bfield(osr)

# One can also create a tapered undulator field
# The 'taper' is input as percent per meter

# This is the basic planer undulator field with taper (highly exaggerated for display purposes)
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=21, taper=0.40)

# Plot the field if you like
plot_bfield(osr)

Importing Data¶

OSCARS supports several basic data formats for importing. We are interested in supporting more.

One basic format ('OSCARS1D') is where you have the magnetic field (1, 2, or 3D) given as a function of position and your file format lists rows of (for instance) 'Z Bx By Bz'. In this case, specify X, Y, or Z, and whichever of the B's you have in the format field: iformat='Z Bx By Bz'.

OSCARS format: Has 10 lines of header information, followed by lines consisting of 'Bx By Bz'. You must specify iformat='OSCARS'. The header is as follows:

Comment line
Initial X position
Step size in X
Number of points in X
Initial Y position
Step size in Y
Number of points in Y
Initial Z position
Step size in Z
Number of points in Z

OSCARS also supports iformat='SPECTRA' and iformat='SRW'

# To illustrate the basic 3D format let's create a data file, then import it.
# It will be plotted before and after the import

# Create an undulator field
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[1, 0, 0], period=[0, 0, 0.050], nperiods=11)
plot_bfield(osr, -1, 1, axis='Z')

# Now write the field to a file
osr.write_bfield(ofile='AAMagneticFields_OSCARS.dat', oformat='OSCARS', xlim=[-1, 1], nx=2, ylim=[-1, 1], ny=2, zlim=[-1, 1], nz=5000)
   

# Clear fields and import the field from the file created above
osr.clear_bfields()
osr.add_bfield_file(ifile='AAMagneticFields_OSCARS.dat', iformat='OSCARS')

plot_bfield(osr, -1, 1, axis='Z')

# To illustrate the basic 1D format let's create a data file, then import it.
# It will be plotted before and after the import

# Create an undulator field
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.05], nperiods=31)
plot_bfield(osr, -1, 1, axis='Z')

# Now write the field to a file
osr.write_bfield(ofile='AAMagneticFields_OSCARS1D.dat', oformat='OSCARS1D Z By Bx Bz', zlim=[-1, 1], nz=5000)   

# Clear fields and import the field from the file created above, additionally you can scale the input
osr.clear_bfields()
osr.add_bfield_file(ifile='AAMagneticFields_OSCARS1D.dat', iformat='OSCARS1D Z By Bx Bz', scale=[1, 0.1])

plot_bfield(osr, -1, 1, axis='Z')

# OSCARS supports import and exporting the SPECTRA format.
# It will be plotted before and after the import

# Make an undulator field
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=11)
plot_bfield(osr)

# Now write the field to a file
osr.write_bfield(ofile='AAMagneticFields_SPECTRA.dat', oformat='SPECTRA', xlim=[-1, 1], nx=2, ylim=[-1, 1], ny=2, zlim=[-1, 1], nz=5000)

# Clear fields and import the field from the file created above
osr.clear_bfields()
osr.add_bfield_file(ifile='AAMagneticFields_SPECTRA.dat', iformat='SPECTRA')

plot_bfield(osr)

# OSCARS supports import and exporting an SRW format.
# It will be plotted before and after the import

# Make an undulator field
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[1, 1, 0], period=[0, 0, 0.050], nperiods=11)
plot_bfield(osr)

# Now write the field to a file
osr.write_bfield(ofile='AAMagneticFields_SPECTRA.dat', oformat='SRW', xlim=[-1, 1], nx=2, ylim=[-1, 1], ny=2, zlim=[-1, 1], nz=5000)

# Clear fields and import the field from the file created above
osr.clear_bfields()
osr.add_bfield_file(ifile='AAMagneticFields_SPECTRA.dat', iformat='SRW')

plot_bfield(osr)

# One can also rotate and translate on importing a field file

# Create an undulator field
osr.clear_bfields()
osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=11)
plot_bfield(osr)

# Now write the field to a file.  If you don't require a dimension you can leave it off
osr.write_bfield(ofile='AAMagneticFields_OSCARS.dat', oformat='OSCARS', zlim=[-1, 1], nz=5000)

# Clear fields and import the field from the file created above
osr.clear_bfields()
osr.add_bfield_file(ifile='AAMagneticFields_OSCARS.dat', iformat='OSCARS', rotations=[0, 0, osr.pi()/4], translation=[0, 0, 0.4])

plot_bfield(osr)

Python Function for a Field¶

You can make your own python function and import it as a magnetic field. All you need is a function which has 4 arguments: x, y, z, t. t is not used at the moment but will be in future versions so it is required here for compatibility. The function must return the BField in 3-dimensions as a list [Bx, By, Bz]

# Define a field function for use with OSCARS
def MyField (x, y, z, t):
    """User defined magnetic field in python function.  Must return a list: [Bx, By, Bz]"""
    
    if z >= -0.75 and z < -0.50:
        return [0, 0, -1]
    elif z >= -0.50 and z < 0.50:
        return [0, 0, 4*z*z]
    elif z >= 0.50 and z < 0.75:
        return [0, 0, -1]
    return [0, 0, 0]

# Add the field function to oscars and plot it
osr.clear_bfields()
osr.add_bfield_function(MyField)
plot_bfield(osr, -1, 1, axis='Z')

Combined Fields¶

Add as many fields as you like to OSCARS

osr.clear_bfields()
osr.add_bfield_uniform(bfield=[0, 0, 4], width=[1, 2, 1])
osr.add_bfield_gaussian(bfield=[1, 2, 0], sigma=[0.05, 0.05, 0.03])
osr.add_bfield_gaussian(bfield=[1, 2, 0], sigma=[0.05, 0.05, 0.03], translation=[0, 0, -0.3])
osr.add_bfield_undulator(bfield=[1, 2, 3], period=[0, 0, 0.050], nperiods=5, translation=[0, 0, 0.4])

# Plot the field if you like
plot_bfield(osr, -1, 1, axis='X')
plot_bfield(osr, -1, 1, axis='Y')
plot_bfield(osr, -1, 1, axis='Z')