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:
- When you pass a MATLAB
datetime
value with nanosecond precision to Python, the MATLAB engine truncates the value because Pythondatetime
objects support only microsecond precision. - You cannot pass MATLAB
datetime
scalars with the special time zoneUTCLeapSeconds
to Python. - You cannot pass MATLAB
datetime
scalars with a value ofNaT
to Python.
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.