Coarse Graining User-interface

This module provides functionality for coarse graining particle data from discrete element method (DEM) simulations. It includes methods for loading particle data, calculating particle size statistics, generating coarse-grained grids, computing macroscopic fields, handling particle phases, and writing output data.

class pysammos.coarse_graining.CoarseGraining(particle_path, contacts_path, output_path, start_timestep, end_timestep, dt_time_step, DEM_keymap, grid_info, weight_function, fields_to_export, ignore_phases, vkthdf_output=True, h5_output=True, search_sampling_factor=1000, velocity_gradient_method='finite_difference')

Bases: object

Encapsulates the coarse graining process, including initialization, configuration, data sampling, phase identification, grid generation, and field computation.

Inputs

particle_pathstr

Path to the particle data files.

contacts_pathstr

Path to the contact data files.

output_pathstr

Path where the output files will be saved.

start_timestepint

The starting timestep for the simulation.

end_timestepint

The ending timestep for the simulation.

dt_time_stepint

The time step interval for the simulation.

DEM_keymapdict

Mapping DEM data keys to their variable names.

grid_infodict

Grid information such as dimensions, axes, and ranges.

weight_functionstr

Type of weight function to use for coarse graining. It can be one of the following: 'Gaussian', 'Lucy', 'HeavySide'.

fields_to_exportdict

Fields to be exported.

ignore_phasesbool

Whether to ignore particle phases.

vkthdf_outputbool, optional

Whether to output VTKHDF files. Default is True.

h5_outputbool, optional

Whether to output H5 files. Default is True.

search_sampling_factorint, optional

Factor to control the sampling rate for neighbor search. It is the factor that divides the first significant figure of the search space. Default is 1000. For a roubust benchmarking at different w/d ratios, use a higher value like 10'000.

velocity_gradient_methodstr, optional

Method to calculate velocity gradient. It can be either "finite_difference" or "least_squares". Default is "finite_difference". The "finite_difference" method calculates the velocity gradient using finite difference approximations, while the "least_squares" method uses a least squares approach to fit a velocity gradient tensor to the velocity field.

data_sampling()

Load the particle data for the first time step to obtain particle data.

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray, ndarray]

Outputs

BoundsData_t0np.ndarray, shape (3, 2)

The bounds of the particle data for the first time step.

Diameter_t0np.ndarray, shape (N,)

The diameters of the particles for the first time step.

Density_t0np.ndarray, shape (N,)

The densities of the particles for the first time step.

Mass_t0np.ndarray, shape (N,)

The masses of the particles for the first time step.

GlobalID_t0np.ndarray, shape (N,)

The global IDs of the particles for the first time step.

It generates the following attributes:

BoundsData_t0np.ndarray, shape (3, 2)

The bounds of the particle data for the first time step.

file_typestr

The file type of the particle data files.

fields_in_time()

Calculate coarse-grained fields over time steps. This method performs the following steps for each time step:

1. Load particle and contact data for the current time step, using the _load_data() method.

2. Compute coarse-grained fields based on the loaded data, using the _fields_single_time() method.

3. Write the computed results to .h5 and .VTKHDF files, using the _write_results() method.

generate_grid()

Generate the CG grid based on the provided grid information. It takes into account the smoothing length calculated in set_resolution().

It generates the following attributes:

GridPointsnp.ndarray, shape (N, 3)

The grid points coordinates for the coarse graining.

Nodesnp.ndarray, shape (D1, D2, D3)

The grid nodes, where D1, D2, and D3 are the number of nodes in each dimension of the grid.

Spacingnp.ndarray, shape (3,)

The spacing between grid points in each dimension.

Rangesnp.ndarray, shape (3, 2)

The ranges of the grid in each dimension, calculated from the bounds of the particle data.

get_particle_phases(diameter_t0, density_t0, global_id, n_max_phases=6, plot=True)

Obtain particle phases based on diameter and density of a given time step (e.g., 0).

Inputs

diameter_t0np.ndarray, shape (N,)

The particle diameters. Sorted by global ID.

density_t0np.ndarray, shape (N,)

The particle densities. Sorted.

global_idnp.ndarray, shape (N,)

The global IDs of the particles. Sorted by global ID.

n_max_phasesint, optional

The maximum number of phases to find. Default is 6.

plotbool, optional

Whether to plot the phases. Default is True.

It generates the following attributes:

phasesnp.ndarray, shape (M, 2)

The identified phases, each represented by a tuple of (diameter, density).

Phase_Arraynp.ndarray, shape (N,)

An array indicating the phase of each particle (e.g., [0, 1, 2, ...]).

cg_calc_modestr

The coarse graining calculation mode, either "Monodisperse" or "Polydisperse".

get_particle_size_statistics(diameter_t0, mass_t0)

Calculate particle size statistics based on particle diameter and mass.

Return type:

Tuple[float, float]

Inputs

diameter_t0np.ndarray, shape (N,)

The particle diameters.

mass_t0np.ndarray, shape (N,)

The particle masses.

It generates the following attributes:

d43float

The volume-weighted mean diameter.

d32float

The surface-weighted mean diameter.

dmaxfloat

The maximum particle diameter.

drmsfloat

The root mean square diameter.

d50float

The median particle size.

run()

Execute the full coarse-graining workflow.

This method performs the following steps:

1. Samples initial particle data and computes particle size statistics (data_sampling() and get_particle_size_statistics()).

2. Identifies particle phases (get_particle_phases()).

3. Sets the coarse-graining resolution (set_resolution()).

4. Generates the grid (generate_grid()).

5. Iterates over each time step to compute and write coarse-grained fields (_fields_single_time() and _write_results()).

set_resolution(average_diameter, w_mult=0.75)

Set the resolution for coarse graining based on the average particle diameter.

Inputs

average_diameterfloat

The average particle diameter. Can be any representative diameter: d50, d32, d43, or drms.

w_multfloat, optional

The multiplier for the half-width of the smoothing kernel. Default is 0.75.

It generates the following attributes:

wfloat

The half-width of the smoothing kernel.

cfloat

The cutoff distance for the smoothing kernel.

sweep_CG_widths(w_d, center)

Perform a sweep over different coarse-graining resolutions (w values) for a specified time step. This method iterates over a range of w values, computes the coarse-grained fields for each w, and writes the results to output files. The input w values are provided as an array of multiples of the characteristic particle diameter (here d43). It does not consider different particle phases; all particles are treated as belonging to a single phase.

Inputs:

w_dnp.ndarray

An array of w/d values to sweep over, where w is the coarse-graining half-width and d is the characteristic particle diameter measure of choice

centernp.ndarray

A 3-element array specifying the center point around which to generate the grid of points.

Subpackages

• Data Handle
  • Contacts
    • Complete
      • Branch Vectors module
      • Coordination Number module
    • Quality Check
      • Duplicates module
    • Particle Mapper module
      • map_contact_data()
  • Particles
    • Particle Statistics module
      • d50_calc()
• Data Read
  • Mfix
    • Cell Data module
      • contacts()
      • get_file_type()
      • reader()
      • ContactData__JP()
      • Reader_vtm()
      • contacts()
      • extract_all_polydata()
      • particles()
      • get_bounds()
      • get_point_data_variable()
• Data Write
  • h5
    • Writer module
      • H5XarrayManager
  • Vtkhdf
    • Core module
      • c2f_reshape()
      • create_adaptive_chunks()
      • create_cell_dataset()
      • create_field_dataset()
      • create_point_dataset()
      • dimensions2extent()
      • extent2dimensions()
      • f2c_reshape()
      • get_cell_array()
      • get_cell_data_shape()
      • get_cell_dataset()
      • get_data_order()
      • get_field_array()
      • get_field_dataset()
      • get_point_array()
      • get_point_data_shape()
      • get_point_dataset()
      • get_point_tensor()
      • get_point_vector()
      • initialize()
      • is_tensor_data()
      • is_vector_data()
      • point2cell_dimensions()
      • point2cell_extent()
      • read_slice()
      • read_vtkhdf()
      • set_point_4d_tensor()
      • set_point_scalar()
      • set_point_symmetric_tensor()
      • set_point_tensor()
      • set_point_vector()
      • validate_imagedata_consistency()
      • write_multicomponent_slice()
      • write_scalar_slice()
      • write_vector_slice()
      • write_vtkhdf()
    • Writer module
      • VTKHDFWriter
• Grid Generation
  • Regular Cuboid module
    • Grid_Generation
      • Grid_Generation.Automatic_Range()
      • Grid_Generation.Create_grid_points()
      • Grid_Generation.Generate()
• Macroscopic Fields
  • Gridded
    • Dispatcher module
      • kinetic_tensor()
      • scalar()
      • tensor()
      • vector()
    • Scalars module
      • mean_grainsize()
      • scalar_monodisperse()
      • scalar_monodisperse_scaled()
      • scalar_polydisperse()
      • scalar_polydisperse_scaled()
      • scalar_x_volume()
    • Vectors module
      • vector_monodisperse()
      • vector_monodisperse_scaled()
      • vector_polydisperse()
      • vector_polydisperse_scaled()
    • Tensors module
      • kinetic_tensor_interpolation_monodisperse()
      • kinetic_tensor_interpolation_polydisperse()
      • tensor_monodisperse()
      • tensor_monodisperse_scaled()
      • tensor_polydisperse()
      • tensor_polydisperse_scaled()
    • Secondary module
      • bulk_fabric_tensor_Sun2015()
      • compute_deviatoric_tensor()
      • compute_granular_temperature()
      • compute_inertial_number()
      • compute_pressure()
      • compute_second_invariant()
      • compute_shear_rate_tensor()
      • compute_vector_bulk_gradient()
      • compute_velgrad_leastsquares()
  • Sliced
    • Granular Temperature module
      • calc_slices()
      • granular_temperature()
    • Utils module
      • Wm()
      • area()
      • particles_band()
  • get_fields_to_compute()
• Neighbour Search
  • Grid Particle Search module
    • calc_displacement()
    • particle_node_match()
• Particle Phase
  • Clustering module
    • find_phases()
    • plot_phases()
• Post Averaging
  • Profiles module
    • VerticalIntegrator
      • VerticalIntegrator.get_area_factor()
      • VerticalIntegrator.get_position_data()
      • VerticalIntegrator.integration()
• Spatial Weights
  • Hashtable Search module
    • hash_table_search()
    • hash_table_search_1d()
    • hash_table_search_2d()
    • make_hash_table()
  • Kernels module
    • gaussian()
    • h()
    • heavySide()
    • lucy()
  • Resolution module
    • calc_cutoff()
    • calc_half_width()
    • compute_dist_along_branch()
    • first_significant_figure_position()
    • integration_scalar()
    • trapezoidal_integration()