fieldkit package

fieldkit.analyze	Functions to analyze a field (identify domains, compute isosurfaces, etc)
fieldkit.field	Defines the main Field class object
fieldkit.fileio	Functions to read/write fields to files
fieldkit.initialize	Functions to help set the value of fields
fieldkit.manipulate	Functions to manipulate fields
fieldkit.plot	Plot fields using matplotlib

fieldkit.analyze module

Functions to analyze a field (identify domains, compute isosurfaces, etc)

fieldkit.analyze.calc_domain_stats(field, density_threshold, plotMesh=False, outputMesh=False, add_periodic_domains=False, applyPBC=True)

calculate properties of domains using a mesh Adapted from domaintools.py

fieldkit.analyze.identify_discrete_domains(field, density_threshold)

Identify all discrete domains present within a field given a density threshold

Uses the “burning algorithm”. Adapted from domaintools.py Also sets (1) image_flags (which PBC a domain belongs to) and (2) isborder (whether a grid is adjacent to a domain) Though these are not currently used outside of this function

Parameters:

• field – field to identify domains of

• density_threshold – threshold used to define domains

Returns:

the number of discrete domains domainID: a ndarray of shape equal to field.data containing the index of that domain. If domainID == 0, it is the continuous domain. Points with domainID == i, correspond to the ith domain imageflags: imageflags in each dimension

Return type:

ndomains

fieldkit.field module

Defines the main Field class object

class fieldkit.field.Field(npw=None, data=None, h=None)

Bases: object

Class for Field object used to model 1D, 2D, 3D structures.

npw

number of grid points in each dimension

npw_total

total number of grid points for all dimensions

dim

dimension of field

data

stored values of field at each grid point

h

a cell tensor, in which the columns are box vectors that describe the coordinate system

is_real_space

tells if Fourier transform has been used

coords

stores x,y,z coordinates of each grid point

CoordsFromH()

Compute coordinates of field from current “h” box vector.

hvoxel()

is_complex()

return if field is complex or not

is_cubic()

is cell of this field cubic or not

is_orthorhombic()

set_coords(coords)

User can manually set coords.

set_data(data)

Sets data based on size.

set_h(h)

Checks that h is square and sets coords.

volume()

calculate volume of cell tensor

fieldkit.fileio module

Functions to read/write fields to files

fieldkit.fileio.get_PolyFTS_to_VTK_IdxMap(M, Nx)

fieldkit.fileio.read_from_file(filename)

Reads from textfile and output a list of Field objects. Adapted from iotools.py.

Parameters:

filename – String for name of file to be read through this function.

Returns:

A list of Fields objects.

Return type:

field_list

fieldkit.fileio.write_to_VTK(filename, fields)

Creates a VTK file based on the fields variable. Adapted from FTS-tools/plot/PolyFTS_to_VTK.py.

Parameters:

• filename – String for name of file to be written through this function.

• fields – A list of Fields objects.

Returns:

A VTK file based on fields.

fieldkit.fileio.write_to_file(filename, fields)

Creates a text file based on the fields variable. Adapted from iotools.py.

Parameters:

• filename – String for name of file to be written through this function.

• fields – A list of Fields objects.

Returns:

A text file based on fields.

Raises:

TypeError – if fields is not a list, than make it a one element list.

fieldkit.initialize module

Functions to help set the value of fields

fieldkit.initialize.add_ellipse(field, center, axis_lengths, smoothing_width=0.05, height=1, units='scaled')

adds an elipse

Parameters:

• field – field to add ellipse to (edited in place)

• center – center of ellipse (in scaled [0-1])

• axis_lengths – lengths of ellipse axis in each dimension (in scaled [0-1])

• smoothing_width – sigma to use for smoothing gaussian filter

• height – height of ellipse

Returns:

field edited in place

Return type:

field

Raises:

None currently. –

fieldkit.initialize.add_gaussian(field, center, sigma, height=1)

add a gaussian to a field.

Parameters:

• field – field to add ellipse to (edited in place)

• units – units to use for args center and sigma. units=’real’ is default currently and center must fall within h cell tensor of field

• center – center of Gaussian (in real units)

• height – height of Gaussian

fieldkit.initialize.add_hockney_eastwood_function(field, center, P, height=1)

add a Hockney Eastwood function of order P to field

Parameters:

• field – field to add Hockney Eastwood function to (edited in place) units=’real’ is default currently and center must fall within h cell tensor of field

• center – center of Hockney-Eastwood function (in real units). This is mapped into “index units” within function

• height – total integral of function TODO: probably better to rename this from “height” to something else

fieldkit.initialize.add_hockney_eastwood_functions_jit(data_array, npw, h, centers, types, P, height=1)

Add a Hockney Eastwood function of order P to field (numba/jit implementation)

This is basically a C-like restructured version of add_hockney_eastwood_function to avoid having to explicitly use a Field object (which numba does not like since it cannot determine its type). This function now explicitly loops over all particle centers. Simple benchmarking shows that this was about 100x faster over my initial python only implementation

Parameters:

• data_array – np.arrays of size ntypes*npw with the data that should be updated (note: updated IN PLACE)

• npw – number of grid points in each dimension

• h – cell tensor matrix (dim x dim)

• centers – particles centers to place H-E functions at and add to data_list

• types – type of each particle. All particles of same type will be grouped into same field

• P – order of assignment function

• height – total integral of function TODO: probably better to rename this from “height” to something else

fieldkit.initialize.hockney_eastwood_function_jit(xparticle, ngridpts, P)

Hockney-Eastwood Function as described in Deserno and Holm 1998

Parameters:

• xparticle – position of particle in each dimension. Note that xparticle is given in “index units” so that spacking between grid points is = 1

• ngridpts – the number of grid point that make up the total grid

• P – order of the assignment function

Returns:

a list of tuples (each tuple is of lengh dim) that describe the grid indicies updated by the function weights: the weight of the particle corresponding to each of those grid indicies

Return type:

grid_indicies

fieldkit.initialize.hockney_eastwood_function_orig(xparticle, ngridpts, P)

Hockney-Eastwood Function as described in Deserno and Holm 1998 :param xparticle: position of particle in each dimension. Note that xparticle is given in “index units” so that spacking between grid points is = 1 :param ngridpts: the number of grid point that make up the total grid :param P: order of the assignment function

Returns:

a list of tuples (each tuple is of lengh dim) that describe the grid indicies updated by the function weights: the weight of the particle corresponding to each of those grid indicies

Return type:

grid_indicies

fieldkit.initialize.initialize_phase(phase, npw, h)

Creates a list of Field objects for 3D phases with 2 or 3 species.

Adapted from FTS-tools/field/init_fields_3d_2spec.py and from FTS-tools/fields/ini_fields_3d_3spec.py. 2 species 3D phases implemented in this function: A15. C15, double-gyroid, single-diamond 3 species 3D phases implemented in this function: alt- diamond, alt-C15.

Parameters:

• phase – name of the phase (see description above for phases implemented in this function)

• npw – number of grid points for each dimension

• h – a cell tensor, in which the columns are box vectors that describe the coordinate system

Returns:

list of Field objects, each object for each species.

Return type:

field_list

Raises:

NotImplementedError – if phase is not a phases implemented in this function (see description above), the function will exit.

fieldkit.initialize.initialize_sphere_positions(phase, field, npw, magnitude)

fieldkit.initialize.particle_to_field(trjfile, topfile, frames_to_average, npw, P)

Initialize a field using a the particle coordinates and Hockney/Eastwood function

Parameters:

• trjfile – trajectory file. Any file format compatable with mdtraj should work.

• topfile – topology file. Any file format compatable with mdtraj should work.

• frames_to_average – frame indicies to average over when converting to field. list, or int (if single frame)

• npw – dimension of grid for output field (note that the voxels must be approx. cubic to use current Hockney-Eastwood mapping function

• P – order of Hockney-Eastwood assignment function (see Deserno and Holm 1998 for more details)

fieldkit.initialize.particle_to_field_gsd(gsdfile, frames_to_average, npw, P, types=[], normalize=False, use_jit=True, verbose=True)

Initialize a field using a the particle coordinates and Hockney/Eastwood function

Parameters:

• gsdfile – trajectory file in gsd format

• frames_to_average – frame indicies to average over when converting to field. list, or int (if single frame)

• npw – dimension of grid for output field (note that the voxels must be approx. cubic to use current Hockney-Eastwood mapping function

• P – order of Hockney-Eastwood assignment function (see Deserno and Holm 1998 for more details)

• types – a list/array of length nparticles that will be used ot generate each field. If unspecified, will use atomtypes from the gsd file.

• normalize – whether or not to normalize densities by rho0

• use_jit – whether or not to use fast numba just-in-time compiled version. This should be enabled if possible.

• verbose – write lots of output

fieldkit.initialize.update_species_field_gaussians(field, centers, npw, magnitude, x, y, z)

fieldkit.initialize.update_species_field_levelset(phase, field, magnitude, originshift, x, y, z)

fieldkit.manipulate module

Functions to manipulate fields

fieldkit.manipulate.change_resolution(fields, npw_new)

For a list of Field objects, change the resolution of each Field object.

Parameters:

• field – a list of Field objects

• npw_new – a tuple that defines the new resolution of each Field object.

Returns:

a list of Field objects with each object set to a resolution of npw_new.

Return type:

field_new

fieldkit.manipulate.compress_dimension(fields, dims_to_compress)

Convert a field to one of a lower dimension (e.g. 1d to 2d or 3d)

Parameters:

• fields – list of field arguments

• dims_to_compress (list) – dimensions to compress

Returns:

a new list of fields with compressed dimension

Return type:

fields_new

fieldkit.manipulate.cubic_voxels(fields_old, tol=0.01)

For a list of Field objects, change the resolution of each Field object so that the voxels are approximately cubic

Parameters:

• field_old – a list of Field objects

• tol – tolerable error for how cubic you want the voxels to be

Returns:

a list of Field objects with each object set to a new resolution that is approximately cubic

Return type:

field_new

fieldkit.manipulate.expand_dimension(fields, dim_new, npw_new, boxl_new)

Convert a field to one of a higher dimension (e.g. 1d to 2d or 3d)

Parameters:

• fields – list of field arguments

• dim_new (list) – new dimension of fields (must be higher than input dimension)

• npw_new (list) – npw for each new dimension created

• boxl_new (list) – box length for each new dimension created

Returns:

a new list of fields with expanded dimension

Return type:

fields_new

fieldkit.manipulate.replicate_fields(fields, nreplicates)

For a list of Fields, replicate each Field object by nreplicates. Adapted from FTS-tools/replicate_fields.py and FTS-tools/lib/fieldtools.py.

Parameters:

• fields – a list of Field objects

• nreplicates – number of replicates

Returns:

a list of Field objects, in which each Field object is replicated by nreplicates amount of times.

Return type:

fields_list

fieldkit.manipulate.roll(fields, shift)

roll the fields across the PBC using shift

Parameters:

• fields – a list of Field objects

• shift – list of length dim. How much to roll the fields. In range [0-1].

Returns:

a list of Field objects, in which each Field object has been translated.

Return type:

fields_new

fieldkit.plot module

Functions to plot fields

fieldkit.plot.plot(fields, dpi=100, show=True, filename=None, imag=False)

Plot fields using matplotlib

Parameters:

• fields – a list of Field objects

• dpi – dpi (resolution) of specified image

• show – whether or not to show the plot

• filename – output filename for plotfile

• imag – whether to plot ‘real’ or ‘imag’ component of fields

Returns:

none