Use MATLAB duration Types with Python

These examples show how MATLAB^® converts between MATLAB duration values and Python^® timedelta or NumPy timedelta64 values.

Pass MATLAB duration Scalar to Python Function

When you pass a MATLAB duration object, the interface converts it to a Python timedelta object. For example, create a scalar MATLAB duration object. This value is precise enough to include microseconds.

mwd = duration("01:02:34.56789",...
      "Format","hh:mm:ss.SSSSS")

mwd = 
  duration
   01:02:34.56789

Then pass it as an argument to a Python function, such as the list constructor. When you pass a MATLAB duration object as an argument to a Python function, the interface converts it to a Python timedelta object.

pyListOfTimedelta = py.list({mwd})

pyListOfTimedelta = 
  Python list with values:

    [datetime.timedelta(seconds=3754, microseconds=567890)]

Handle Python duration Scalar Returned from Python Function

When a Python function returns a timedelta object, convert it to a MATLAB duration object by calling the duration function. The converted duration object always has the default format. To change its format, set its Format property. In this example, set the format to display microseconds.

mwdConverted = duration(pyListOfTimedelta{1});
mwdConverted.Format = "hh:mm:ss.SSSSS"

mwdConverted = 
  duration
   01:02:34.56789

Pass timedelta Arrays

To store a MATLAB a duration array as a list of Python timedelta values, first convert it to a cell array.

mwd = duration(1:2,2,34);
mwd = num2cell(mwd)

mwd =
  1×2 cell array
    {[01:02:34]}    {[02:02:34]}

Then pass the cell array as an argument to a Python function. The interface converts the cell array to a list of Python timedelta values.

py.print(mwd)

(datetime.timedelta(seconds=3754), datetime.timedelta(seconds=7354))

Pass NumPy duration Arrays

You can convert between MATLAB duration arrays and NumPy timedelta64 arrays. For example, create a MATLAB duration array.

mwd = duration(1:2,2,34)

mwd = 
  1×2 duration array
   01:02:34   02:02:34

If you have NumPy installed, then the interface converts the array to a NumPy timedelta64 array.

py.print(mwd)

[[3754000000 7354000000]]

py.print(py.type(mwd))

<class 'numpy.ndarray'>

To convert a NumPy timedelta64 array to a MATLAB duration array, use the duration function.

pyTimedeltas = py.numpy.array(mwd)

pyTimedeltas = 
  Python ndarray with properties:

           T: [1×1 py.numpy.ndarray]
        base: [1×1 py.NoneType]
      ctypes: [1×1 py.numpy.core._internal._ctypes]
       dtype: [1×1 py.numpy.dtype[timedelta64]]
       flags: [1×1 py.numpy.core.multiarray.flagsobj]
        flat: [1×1 py.numpy.flatiter]
        imag: [1×1 py.numpy.ndarray]
    itemsize: [1×1 py.int]
      nbytes: [1×1 py.int]
        ndim: [1×1 py.int]
        real: [1×1 py.numpy.ndarray]
       shape: [1×2 py.tuple]
        size: [1×1 py.int]
     strides: [1×2 py.tuple]
    [[3754000000 7354000000]]

mwdConverted = duration(pyTimedeltas)

mwdConverted = 
  1×2 duration array
   01:02:34   02:02:34

Handle Multiple Python timedelta Objects Returned from Python Function

A Python function might return multiple timedelta objects as a list or a tuple of Python timedelta objects. Use the MATLAB duration function to convert the list or tuple to a MATLAB duration array. The list or tuple must contain Python datetime.timedelta types only.

Suppose that a function returns a list, ptdList. For the purpose of this example, create ptdList with this code:

td1 = py.datetime.timedelta(hours=25, seconds=2);
td2 = py.datetime.timedelta(days=50, hours=21, seconds=22);
ptdList = py.list({td1, td2})

ptdList = 
  Python list with values:

    [datetime.timedelta(days=1, seconds=3602), datetime.timedelta(days=50, seconds=75622)]

    Use string, double, duration or cell function to convert to a MATLAB array.

Calculate the elapsed time between the timedelta objects:

mwtdList = duration(ptdList);
D = mwtdList(1) + mwtdList(2)

D = 
   1246:00:24