How MATLAB Handles Datetime and Duration Types in Python - MATLAB & Simulink (original) (raw)

When you use MATLAB® functionality in Python® and work withdatetime or duration values, MATLAB Engine API for Python automatically converts your data between the equivalent MATLAB and Python data types.

Convert from MATLAB Data Type to Python Data Type

When you pass MATLABdatetime or duration values to Python, the MATLAB engine automatically converts the values to the equivalent Python data type, as shown in this table. An array contains either zero elements or more than one.

MATLAB Data Type Resulting Python Data Type
datetime scalar datetime.datetime object
duration scalar datetime.timedelta object
datetime array numpy.datetime64 arrayIf the NumPy package is not available in the Python environment, MATLAB converts the datetime array tomatlab.object.
duration array numpy.timedelta64 arrayIf the NumPy package is not available in the Python environment, MATLAB converts the duration array tomatlab.object.

Convert from Python Data Type to MATLAB Data Type

When you pass Python data to MATLAB in Python, the MATLAB engine automatically converts the data into the equivalent MATLAB data type, as shown in this table.

Python Data Type Resulting MATLAB Data Type
datetime.datetime scalar datetime scalar
datetime.timedelta scalar duration scalar
numpy.datetime64 scalar datetime scalar
numpy.timedelta64 scalar duration scalar
numpy.datetime64 array datetime array
numpy.timedelta64 array duration array

Use MATLAB Datetime Scalar in Python

First, import the datetime module and start the MATLAB engine in Python.

import datetime import matlab.engine eng = matlab.engine.start_matlab('-desktop')

Create a datetime value in MATLAB.

mwdt = datetime("2022-11-04 03:15:35.12345", ... Format="uuuu-MM-dd HH:mm:ss.SSSSS");

Then, in Python, pass the MATLABdatetime value as an argument to a Python function, such as the list constructor. The MATLAB engine converts the value to a Pythondatetime.datetime object.

pyldt = list(eng.workspace["mwdt"]) pyldt

[datetime.datetime(2022, 11, 4, 3, 15, 35, 123450)]

When a MATLAB function called from Python returns a datetime scalar, the MATLAB engine automatically converts the MATLAB function output to a datetime.datetime object in Python. For example, in Python, view the data type returned by the MATLABdateshift function.

type(eng.dateshift(eng.datetime('today'),'start','year'))

<class 'datetime.datetime'>

The MATLAB engine can convert MATLABdatetime scalar values with a time zone to Pythondatetime.datetime objects with the same time zone. On machines that do not have a system Internet Assigned Numbers Authority time zone database, such as Windows® computers, you can install the Python tzdata module from the Python Package Index.

Using MATLABdatetime scalar values in Python has these limitations:

Use MATLAB Duration Scalar in Python

Similarly, you can create a duration value in MATLAB and then pass the value to a function in Python. The MATLAB engine converts the value to a Pythondatetime.timedelta object. While MATLABduration values support millisecond precision, Pythontimedelta objects support microsecond precision.

For example, create a duration value in MATLAB.

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

Then, in Python, pass the MATLABduration value as an argument to a Python function, such as the list constructor. Then display the Python list.

pyld = list(eng.workspace["mwd"]) pyld

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

Use MATLAB Datetime Array in Python

You can access data in MATLABdatetime arrays in Python with or without the NumPy package.

With NumPy

If you have NumPy installed, you can convert between MATLABdatetime arrays and NumPy datetime64 arrays.

For example, create a MATLABdatetime array in MATLAB.

mwdtarr = datetime(2024,10:12,4,3,15,35);

In Python, import the NumPy package and pass the MATLABdatetime array to the Pythontype function. The MATLAB engine converts the data to a numpy.datetime64 array.

import numpy type(eng.workspace["mwdtarr"])

When the MATLAB engine converts a zoned MATLABdatetime array to a NumPy datetime64 array, it first converts the time zone to UTC and then removes the time zone before constructing the NumPy datetime64 array. For example, in MATLAB, create a zoned MATLABdatetime array.

mwdtarrtz = datetime(1984,12,07,2,59,0, ... TimeZone="America/Los_Angeles") ... + calyears(0:5);

Pass the MATLABdatetime array to Python and display it. The dates have been adjusted to UTC.

npdtarrtz = eng.workspace["mwdtarrtz"] npdtarrtz

array(['1984-12-07T10:59:00.000000000', '1985-12-07T10:59:00.000000000', '1986-12-07T10:59:00.000000000', '1987-12-07T10:59:00.000000000', '1988-12-07T10:59:00.000000000', '1989-12-07T10:59:00.000000000'], dtype='datetime64[ns]')

The MATLAB engine ignores the Pythondatetime.fold attribute.

Without NumPy

You can also pass MATLABdatetime arrays to Python without the NumPy package. In this case, the data converts to data of type matlab.object. However, if you want to store a MATLABdatetime array as a list of Pythondatetime values, you can first convert it to a cell array.

For example, in MATLAB, convert a MATLABdatetime array to a cell array.

mwdtcell = num2cell(mwdtarr);

Then, in Python, pass the cell array as an argument to a Python function. The MATLAB engine converts the cell array to a list of Pythondatetime values.

len(eng.workspace["mwdtcell"])

Use MATLAB Duration Array in Python

You can access data in MATLABduration arrays in Python with or without the NumPy package.

With NumPy

If you have NumPy installed, you can convert between MATLABduration arrays and NumPy timedelta64 arrays.

For example, create a MATLABduration array in MATLAB.

mwdarr = duration(1:2,2,34);

In Python, import the NumPy package and pass the MATLABduration array to the Pythontype function. The MATLAB engine converts the data to a numpy.timedelta64 array.

import numpy type(eng.workspace["mwdarr"])

You can convert a NumPy timedelta64 array to a MATLABduration array using the same method. In Python, pass the NumPy array back to MATLAB.

eng.workspace['mwdarr2'] = npdarr

In MATLAB, display the MATLAB array.

mwdarr2 =

1×2 duration array

01:02:34 02:02:34

Without NumPy

You can also pass MATLABduration arrays to Python without the NumPy package. To store a MATLABduration array as a list of Pythontimedelta values, first convert it to a cell array.

For example, in MATLAB, convert a MATLABduration array to a cell array.

mwdcell = num2cell(mwdarr);

Then, in Python, pass the cell array as an argument to a Python function. The MATLAB engine converts the cell array to a list of Pythontimedelta values.

len(eng.workspace["mwdcell"])

Pass Python Datetime Scalar to MATLAB

When you pass a Pythondatetime or NumPy datetime64 object to MATLAB, the MATLAB engine converts it to a MATLABdatetime value. For example, create a Pythondatetime object and pass it to MATLAB.

pydt = datetime.datetime(2019, 5, 18, 15, 17, 8, 132263) eng.workspace['mwdt2'] = pydt

In MATLAB, display the MATLABdatetime value.

mwdt2 =

datetime

2019-05-18T15:17:08.132Z

Pass Python Duration Scalar to MATLAB

When you pass a Pythontimedelta or NumPy timedelta64 object to MATLAB, the MATLAB engine converts it to a MATLABduration value. For example, create a Pythontimedelta object and pass it to MATLAB.

pyd = datetime.timedelta(15, 12, 31, 23, 59, 59, 1) eng.workspace['mwd2'] = pyd

In MATLAB, display the MATLABduration value.

mwd2 =

duration

587:59:12

When you pass a Pythontimedelta value with microsecond precision to MATLAB, the MATLAB engine truncates the value because MATLABduration values support only millisecond precision.

See Also

datetime | duration

Topics