Migration Guide from v0.4.x to 0.5.x

Sparse Tensor

Input Keywords

Abbreviated keywords to complete keywords.

import MinkowskiEngine as ME

...

# v0.4.x
sinput = ME.SparseTensor(feats, coords=coords)
manager = sinput.coords_man
key = sinput.coords_key
# v0.5.x
# all of the following initializations are valid
# sinput = ME.SparseTensor(feats, coords)
# sinput = ME.SparseTensor(feats, coordinates=coords)
sinput = ME.SparseTensor(features=feats, coordinates=coords)
manager = sinput.coordinate_manager
key = sinput.coordinate_map_key
sinput2 = ME.SparseTensor(feats, coordinate_map_key=key, coordinate_manager=manager)

CUDA acceleration

In v0.4, the CUDA acceleration was supported for matrix multiplication (convolution), but from v0.5.0a, we provide CUDA backends for kernel map generation. However, to use the CUDA acceleration, you must provide coordinates as a CUDA tensor.

# v0.4.x
sinput = ME.SparseTensor(feats, coords=coords).to(0)
# v0.5.x
# sinput = ME.SparseTensor(feats, coordinates=coords).to(0) # throws an error. Not supported to prevent unnecessary CPU/GPU coordinate map construction
sinput = ME.SparseTensor(feats.to(0), coordinates=coords.to(0))
# The device keyword will override all input tensor device
sinput = ME.SparseTensor(feats, coordinates=coords, device=0)
sinput = ME.SparseTensor(feats.cpu(), coordinates=coords.cpu(), device=0)  # still on GPU 0
sinput = ME.SparseTensor(feats.cuda(), coordinates=coords.cpu(), device=0)  # still on GPU 0
sinput = ME.SparseTensor(feats.cpu(), coordinates=coords.cuda(), device=0)  # still on GPU 0
sinput = ME.SparseTensor(feats.cuda(), coordinates=coords.cuda(), device=0)  # still on GPU 0
sinput = ME.SparseTensor(feats, coords, device=feats.device)

force creation, allow duplicate coords

From v0.5, a new sparse tensor with the same tensor stride, will automatically be created without force_creation=True argument. Instead, a coordinate map key is a pair of tensor stride and a random string, which will be automatically populated to create a new coordinate map.

Similarly, allow duplicates are no longer required since the duplicates will be automatically resolved using quantization_mode.

# v0.4
sinput = ME.SparseTensor(feats, coords=coordinates)
sinput2 = ME.SparseTensor(new_feats,
                          coords=new_coordinates,
                          force_create=True,  # deprecated
                          coords_man=sinput.coordinate_manager)
# v0.5
sinput = ME.SparseTensor(feats, coordinates=coordinates)
sinput2 = ME.SparseTensor(new_feats,
                          coordinates=new_coordinates,
                          coordinate_manager=sinput.coordinate_manager)

Algorithm

From v0.5, we introduce an option to choose the backend algorithm. When you create a sparse tensor, provide the minkowski_algorithm. When you select ME.MinkowskiAlgorithm.SPEED_OPTIMIZED, the ME will consume more GPU memory and will be faster. By default, it is ME.MinkowskiAlgorithm.MEMORY_EFFICIENT.

stensor = ME.SparseTensor(
    features=features,
    coordinates=coordinates,
    minkowski_algorithm=ME.MinkowskiAlgorithm.SPEED_OPTIMIZED,
    # minkowski_algorithm=ME.MinkowskiAlgorithm.MEMORY_EFFICIENT,
    device=device,
)

Convolution / ConvolutionTranspose

Keywords

Use the standard pytorch keywords.

# v0.4.x
conv = ME.MinkowskiConvolution(,... has_bias=False)
# v0.5.x
conv = ME.MinkowskiConvolution(,... bias=False)

GenerativeConvolutionTranspose

To use the generative convolution transpose proposed in the Generative Sparse Detection Networks for 3D Single-shot Object Detection, ECCV'20, spotlight, use the new layer

# v0.4.3
convtr = ME.MinkowskiConvolutionTranspose(..., generate_new_coords=True)
# v0.5.x
convtr = ME.MinkowskiGenerativeConvolutionTranspose(...)

TensorField

A new data structure introduced in v0.5. The TensorField is a data structure for continuous samples in the high-dimensional space. For fluid conversion to and from SparseTensor, the MinkowskiEngine provides a few utility functions.

in_tfield = ME.TensorField(feats, coords, device=device)
# conversion to the SparseTensor
in_stensor = in_tfield.sparse()
# Feed forward
out_stensor = model(in_stensor)
# To field
out_tfield = out_stensor.slice(in_tfield)

Please refer to examples/indoor.py for more information.

MinkowskiToSparse