MBsysPy.mbsyspy.utilities.lut module¶

Classes wrapping the MBsysC Look-up-tables.

Summary¶

The classes related to MBsysC LUT allows to work both with user functions that have been loaded either from a Python script or from a C-library.

class MBsysPy.mbsyspy.utilities.lut.MbsLut1D(name='', x=None, y=None, pointer=None)¶

Bases: object

Class for interpolate a variable from one input.

The instances of this class must be explicitly freed as the memory is allocated by the C-library. But the python instance may be deleted in Python (by the garbage collector) while the C-libraries still need to use the c-memory.

Variables

name (str) – Name of the look-up-table, if loaded from a file it is the absolute path to the file.
nx (int) – Number of value in the Table.
x (numpy.ndarray) – Array containing the input values. The first element x[0] is not used, but it should contain nx.
y (numpy.ndarray) – Array containing the output value to be interpolate values, y=f(x). The first element y[0] is not used, but it should contain nx.
id_x (int) – Index of the interval containing the last computed x value.

Examples

Here are some basic usages.

Loading a table with the value of y=x^2 at each integer between -5 and 5 included, then interpol it.

>>> my_lut = MbsLut1D("x_power_2.MbsLut1D")
>>> my_lut.linear_interpolation(1)
    1.0
>>> my_lut.linear_interpolation(1.5)
    2.5
>>> # Outside the lut domain linear extrapolation from last segment is done.
>>> my_lut.linear_interpolation(10)
    70.0

Setting the table in a MbsLut1D user model

>>> my_lut.set_user_model(mbs_data, "luts", "power_x_2")

Setting the Table in a MbsData

>>> my_lut.set_user_model(mbs_data, "luts", "power_x_2")
>>> # Or use the alternative:
>>> mbs_data.user_model["luts"]["power_x_2"] = my_lut

Retrieving and using the lut from the user model, for a MbsData using Python user functions (default mode)

>>> um_lut = mbs_data.user_model["luts"]["power_x_2"]
>>> # The memory is shared with my_lut
>>> my_lut.linear_interpolation(1.5)
    2.5

Retrieving and using the lut from the user model, for a MbsData using user functions loaded from a c-library (advanced mode)

>>> um_lut = MbsLut1D(pointer=mbs_data.user_model["luts"]["power_x_2"])
>>> # The memory is shared with my_lut
>>> my_lut.linear_interpolation(1.5)
    2.5

The content of the coordinates vector and function value vector can be modified:

>>> print(um_lut.x[7])
    1.0
>>> # um_lut.x[0] is the number of value at which the function has been computed
>>> print(um_lut.x[0])
    11.0
>>> um_lut.x[7] = 1.5  # Change coordinate
>>> print(um_lut.x[7])
    1.5
>>> print(my_lut.x[7])  # Memory is shared
    1.5
>>> um_lut.y[7] = 2.25  # Update function value
>>> um_lut.linear_interpolation(1.5)
    2.25
>>> my_lut.linear_interpolation(1.5)  # Memory is shared
    2.25

Freeing the memory, it is not required to do it for instances sharing the memory but it is safer

>>> my_lut.free()  # Free the C-memory, then set the pointer address in the instance to None (NULL in C).
>>> um_lut.free()  # Does not free any memory, it only set the pointers to None (NULL in C).

Attributes

id_x: Access to id_x (int) attribute (read-write).
name
nx: Access to nx attribute (read-only).
x: Access to x parameter, only value in the vector can be written.
y: Access to y parameter, only value in the vector can be written.

Methods

`free`(self)	Free the memory allocated by the C-libraries.
`linear_interpolation`(self, x)	Compute the table at the specified coordinate by a linear interpolation.
`linear_interpolation_by_step`(self, x)	Compute the table at the specified coordinate by a linear interpolation.
`set_user_model`(self, mbs_data, user_model, …)	Set the C-related structure in the specified user model parameter.

__init__(self, name='', x=None, y=None, pointer=None)¶

Create a 1D look-up-table from a file or arrays.

Parameters

name (str) – If x and y or pointer are not provided, this is the path to the file to load. Else it is the name of the look-up-table. The default is “”.
x (numpy.ndarray or list) – The coordinates of the data point of the look-up-table. If provided y must also be provided (same size). The default is None.
y (numpy.ndarray or list) – The values of the data point at the x coordinates of the look-up-table. If provided x must also be provided (same size). The default is None.
pointer (int, optional) – Memory address of the existing structure to be wrapped. If pointer is provided, the argument x and y cannot be provided. The default is None.

Returns

out – The look-up-table.

Return type

MBsysPy.MbsLut1D

free(self)¶

Free the memory allocated by the C-libraries.

Also redirect pointers address to None.

Returns
Return type: None.

property id_x¶: Access to id_x (int) attribute (read-write).

linear_interpolation(self, x)¶

Compute the table at the specified coordinate by a linear interpolation.

This function use a binary search in the table to locate x. The search starts from the last interval found (for the previous x value). To use binary search from start, set MbsLut1D.id_x to zero before calling.

Parameters

x (float) – The coordinate at which the value must be evaluated. The value must be in the table boundaries.

Returns

The interpolation of the table at x if computation is successful. Nan otherwhise after an error message. Failures are caused by:

x being out of the table range.

division by zero during x evaluation.

table not loaded.

Return type

float

linear_interpolation_by_step(self, x)¶

Compute the table at the specified coordinate by a linear interpolation.

This function looks for the correct interval by travelling from one to the next one. The first interval checked is the one found for the previous x value. This method is really effective for successive calls where x has a smooth or continuous evolution. To start interval from the first one, set MbsLut1D.id_x to zero before calling.

Parameters

x (float) – The coordinate at which the value must be evaluated. The value must be in the table boundaries.

Returns

The interpolation of the table at x if computation is successful. Nan otherwhise after an error message. Failures are caused by:

x being out of the table range.

division by zero during x evaluation.

table not loaded.

Return type

float

name¶

property nx¶: Access to nx attribute (read-only).

set_user_model(self, mbs_data, user_model, parameter)¶

Set the C-related structure in the specified user model parameter.

This function is only required for simulation using user functions from a c-library. The user model parameter type must be a MbsLut1D structure.

If using a pure Python mbs project, the class instance can be directly assigned in the user model.

Parameters

mbs_data (MBsysPy.MbsData) – Multibody system related to the computation.
user_model (str) – Name of the user model.
parameter (str) – Name of the parameter.

Returns

Return type

None

property x¶: Access to x parameter, only value in the vector can be written.

property y¶: Access to y parameter, only value in the vector can be written.

class MBsysPy.mbsyspy.utilities.lut.MbsLut2D(name='', x=None, y=None, z=None, pointer=None)¶

Bases: object

Class for interpolate a variable from two inputs.

The instances of this class must be explicitly freed as the memory is allocated by the C-library. But the python instance may be deleted in Python (by the garbage collector) while the C-libraries still need to use the c-memory.

Variables

name (str) – Name of the look-up-table, if loaded from a file it is the absolute path to the file.
nx (int) – Number of value along the first dimension of the Table.
ny (int) – Number of value along the second dimension of the Table.
x (numpy.ndarray) – Array containing the input values of the first dimension. The first element x[0] is not used, but it should contain nx.
y (numpy.ndarray) – Array containing the input values of the second dimension. The first element y[0] is not used, but it should contain ny.
z (numpy.ndarray) – Two-dimensionnal array containing the output value to be interpolate, z=f(x, y). The first row and column (z[0, :] and z[:, 0]) are not used.

Examples

Here are some basic usages.

Loading a table with the value of z=x^2+y at each integer between -5 and 5 included, then interpol it.

>>> my_lut = MbsLut1D("x_power_2_plus_y.MbsLut2D")
>>> my_lut.linear_interpolation(1, 1)
    2.0
>>> my_lut.linear_interpolation(1.5, 2.5)
    2.5
>>> # Outside the lut domain the behavior is undefined.

Setting the table in a MbsLut2D user model

>>> my_lut.set_user_model(mbs_data, "luts", "power_x_2_plus_y")

Setting the Table in a MbsData

>>> my_lut.set_user_model(mbs_data, "luts", "power_x_2_plus_y")
>>> # Or use the alternative:
>>> mbs_data.user_model["luts"]["power_x_2_plus_y"] = my_lut

Retrieving and using the lut from the user model, for a MbsData using Python user functions (default mode)

>>> um_lut = mbs_data.user_model["luts"]["power_x_2_plus_y"]
>>> # The memory is shared with my_lut
>>> my_lut.linear_interpolation(1.5, 2.5)
    2.5

Retrieving and using the lut from the user model, for a MbsData using user functions loaded from a c-library (advanced mode)

>>> um_lut = MbsLut2D(pointer=mbs_data.user_model["luts"]["power_x_2_plus_y"])
>>> # The memory is shared with my_lut
>>> my_lut.linear_interpolation(1.5, 2.5)
    2.5

The content of the coordinates vector and function value vector can be modified:

>>> print(um_lut.x[7])
    1.0
>>> # um_lut.x[0] is the number of value at which the function has been computed
>>> print(um_lut.x[0])
    11.0
>>> um_lut.x[7] = 1.5  # Change coordinate
>>> print(um_lut.x[7])
    1.5
>>> print(my_lut.x[7])  # Memory is shared
    1.5
>>> um_lut.z[7, 1:] = [2.25 - 5, 2.25 - 4, 2.25 - 3, 2.25 - 2, 2.25 - 1, 2.25
...                    2.25 + 1, 2.25 + 2, 2.25 + 2, 2.25 + 4, 2.25 + 5]  # Update function value
>>> um_lut.linear_interpolation(1.5, 1)
    3.25
>>> my_lut.linear_interpolation(1.5, 1)  # Memory is shared
    3.25

Freeing the memory, it is not required to do it for instances sharing the memory but it is safer

>>> my_lut.free()  # Free the C-memory, then set the pointer address in the instance to None (NULL in C).
>>> um_lut.free()  # Does not free any memory, it only set the pointers to None (NULL in C).

Attributes

name
nx: Access to nx attribute (read-only).
ny: Access to ny attribute (read-only).
x: Access to x parameter, only value in the vector can be written.
y: Access to y parameter, only value in the vector can be written.
z: Access to z parameter, only value in the array can be written.

Methods

`free`(self)	Free the memory allocated by the C-libraries.
`linear_interpolation`(self, x, y)	Compute the table at the specified coordinate by a linear interpolation on both dimensions.
`set_user_model`(self, mbs_data, user_model, …)	Set the C-related structure in the specified user model parameter.

__init__(self, name='', x=None, y=None, z=None, pointer=None)¶

Create a 2D look-up-table from a file or arrays.

Parameters

name (str) – If x and y or pointer are not provided, this is the path to the file to load. Else it is the name of the look-up-table. The default is “”.
x (numpy.ndarray or list) – The coordinates of the data point along the first dimension of the look-up-table. If provided y and z must also be provided. The default is None.
y (numpy.ndarray or list) – The coordinates of the data point along the second dimension of the look-up-table. If provided x and z must also be provided. The default is None.
z (numpy.ndarray) – Two-dimensional array with the values of the function at the provided data points. The shape is [len(x), len(y)]. If provided x and y must also be provided. The default is None.
pointer (int, optional) – Memory address of the existing structure to be wrapped. If pointer is provided, the argument x, y and z cannot be provided. The default is None.

Returns

out – The look-up-table.

Return type

MBsysPy.MbsLut2D

free(self)¶

Free the memory allocated by the C-libraries.

Also redirect pointers address to None.

Returns
Return type: None.

linear_interpolation(self, x, y)¶

Compute the table at the specified coordinate by a linear interpolation on both dimensions.

If called outside the table boundaries, the behaviour is undefined.

Parameters

x (float) – The coordinate on the first dimension at which the value must be evaluated.
y (float) – The coordinate on the second dimension at which the value must be evaluated.

Returns

value – The interpolation of the table at (x,y). If the lut has not been loaded, Nan is returned after error message.

Return type

float

name¶

property nx¶: Access to nx attribute (read-only).

property ny¶: Access to ny attribute (read-only).

set_user_model(self, mbs_data, user_model, parameter)¶

Set the C-related structure in the specified user model parameter.

This function is only required for simulation using user functions from a c-library. The user model parameter type must be a MbsLut2D structure.

If using a pure Python mbs project, the class instance can be directly assigned in the user model.

Parameters

mbs_data (MBsysPy.MbsData) – Multibody system related to the computation.
user_model (str) – Name of the user model.
parameter (str) – Name of the parameter.

Returns

Return type

None

property x¶: Access to x parameter, only value in the vector can be written.

property y¶: Access to y parameter, only value in the vector can be written.

property z¶: Access to z parameter, only value in the array can be written.