MBsysPy.mbsyspy.utilities.utilities module

Define utility functions for package MBsysPy.

Summary

Defines the functions that are not specific to a MBS analysis. Modify the C libraries to get a python compatible behavior.

MBsysPy.mbsyspy.utilities.utilities.bytes_to_str(message)

Convert bytes to str using ‘utf-8’ encoding.

Strings retrived from C-libraries are array of bytes. In python3 (2) strings type is ‘str’ (‘unicode’) with the ‘utf-8’ encoding. The conversion from bytes to str is required to get nice printing message or to compare string from C-libraries to string provided by the user from Python.

Parameters

message (str or bytes) – Message to be converted, if needed, in ‘str’ type.

Returns

Return type

The same message provided byt as a ‘str’ type with ‘utf-8’ encoding

MBsysPy.mbsyspy.utilities.utilities.callback_undefined(function_name=None)

Do nothing, shadow function.

Internal function called when a unloaded function is called.

This is required as calling a function who pointer is ‘None’ (or ‘NULL’ in C) leads to an undefined behavior.

Parameters

function_name (str) – The name of the function that was called.

MBsysPy.mbsyspy.utilities.utilities.convert_numpy_type_to_float(value)

Convert numpy floats type to float type.

This is required to ctypes set the C-memory.

Parameters

value (float-like) – Value that can be any numpy float, and must be converted to float.

Returns

value – Same value but in as float type.

Return type

float

MBsysPy.mbsyspy.utilities.utilities.convert_numpy_type_to_int(value)

Convert numpy intergers type to int type.

This is required to ctypes set the C-memory.

Parameters

value (int-like) – Value that can be any numpy integrer, and must be converted to int.

Returns

value – Same value but in as int type.

Return type

int

MBsysPy.mbsyspy.utilities.utilities.define_output_vector(label, size)

Initialize the memory for a vector as output.

This function must be called in the user init function dedicated to an analysis module. The value are defined during the computation thank to the function ‘set_output_vector()’ or ‘set_output_value()’

Parameters

  • label (str) – The name of the output. It is used as part of the filename and as identifier when filling the values in the output.

  • size (int) – The size of the output vector, which correspond to the maximum value to be saved at each time step.

  • Retuns

  • ——

  • status (int) – The status of the function, negative if an error occurs.

Notes

To shut down the current process initialization in case of error, you have to set ‘MbsData.flag_stop’ to 1. Otherwhise the current module will continue ignoring the output.

MBsysPy.mbsyspy.utilities.utilities.mbs_error(err, msg)

Print error message from C library in the same pipe than Python.

MBsysPy.mbsyspy.utilities.utilities.mbs_msg(msg)

Print message from C library in the same pipe than Python.

MBsysPy.mbsyspy.utilities.utilities.mbs_warning(msg)

Print warning message from C library in the same pipe than Python.

MBsysPy.mbsyspy.utilities.utilities.set_output(value, label)

Save a value during time integration.

Parameters

  • value (float) – Value to be saved.

  • label (str) – The name of the output, also used as part as the output filename.

  • Retuns

  • ——

  • status (int) – The status of the function, negative if an error occurs. A value of “-1” means that the output are currently disable.

Notes

To shut down the current process in case of error, you have to set ‘MbsData.flag_stop’ to 1. Otherwhise the current computation module will continue ignoring the output.

MBsysPy.mbsyspy.utilities.utilities.set_output_value(value, val_index, label)

Send a value at a specific location of an output vector.

Parameters

  • value (float) – Value to be saved.

  • val_index (int) – index in the output vector where the value must be saved. This index must be at least 1 and maximum equal to the size specified with the function ‘define_output_vector()’.

  • label (str) – The name of the output. It must have been defined with the function

  • ‘define_output_vector()’.

  • Retuns

  • ——

  • status (int) – The status of the function, negative if an error occurs. A value of “-1” means that the output are currently disable.

Notes

To shut down the current process computation in case of error, you have to set ‘MbsData.flag_stop’ to 1. Otherwhise the current module will continue ignoring the output.

MBsysPy.mbsyspy.utilities.utilities.set_output_vector(vec, label)

Send an entire vector as output.

The size of ‘vec’ must be equal to the size defined in the function ‘define_output_vector()’.

Parameters

  • vec (list or numpy.ndarray) – Value to be saved as a list or a numpy array.

  • label (str) – The name of the output. It must have been defined with the function

  • ‘define_output_vector()’.

  • Retuns

  • ——

  • status (int) – The status of the function, negative if an error occurs. A value of “-1” means that the output are currently disable.

Notes

To shut down the current process computation in case of error, you have to set ‘MbsData.flag_stop’ to 1. Otherwhise the current module will continue ignoring the output.

MBsysPy.mbsyspy.utilities.utilities.str_from_c_pointer(address, default_name=None)

Read the string at the provided address.

If the address is ‘NULL’ (‘None’ in Python), the default name is returned.

Parameters

  • address (int) – Value of the address.

  • default_name (str, optional) – The default name to return if the adress is invalid (None). The default is None.

Returns

The string at the address, or the default name.

Return type

str

MBsysPy.mbsyspy.utilities.utilities.str_to_bytes(message)

Convert str to bytes using ‘utf-8’ encoding.

In python3 strings type is ‘str’ while the memory in the C-libraries is an array of bytes. When setting a string in the C-memory from a string defined in Python we have to ensure to provide a string that have the type ‘bytes’.

In python2 the type of strings may be ‘str’ or ‘unicode’. A similar conversion is required.

Parameters

message (str or unicode or bytes) – Message to be converted, if needed, in ‘bytes’ type (or ‘str’ compatible with bytes in Python2).

Returns

  • The same message provided byt as a ‘bytes’ type with ‘utf-8’ encoding (or

  • ’str’ compatible with bytes in Python2)