Commit f0f4a7bc authored by Olivier Lantsoght's avatar Olivier Lantsoght
Browse files

[Ctypes] mainly documentation

parent 6f51872f
......@@ -190,6 +190,11 @@ python3 -m twine upload --repository-url https://test.pypi.org/legacy/ --skip-ex
```
### Install (test pip server, or local)
```
python -m pip install --index-url https://test.pypi.org/simple/ --no-deps MBsysPy
python3 -m pip3 install --index-url https://test.pypi.org/simple/ --no-deps MBsysPy
python -m pip install --index-url https://test.pypi.org/simple/ --no-deps MBsysPy --user
python3 -m pip3 install --index-url https://test.pypi.org/simple/ --no-deps MBsysPy --user
```
### Upgrade (test pip server, or local)
```
python -m pip install --index-url https://test.pypi.org/simple/ --no-deps MBsysPy --upgrade -- user
python3 -m pip3 install --index-url https://test.pypi.org/simple/ --no-deps MBsysPy --upgrade --user
```
......@@ -19,30 +19,93 @@ import numpy as np
# importing libraries
from .mbsysc_loader.loadlibs import libutilities
def set_output(var , file_name):
def set_output(value, label):
"""
Function to save a value during time integration.
file_name_c = file_name.encode('utf-8')
libutilities.set_output_ext(var, file_name_c)
Parameters
----------
value : float
Value to be saved.
label : str
The name of the output, also used as part as the output filename.
"""
label_c = label.encode('utf-8')
libutilities.set_output_ext(value, label_c)
def callback_undefined(function_name=None):
"""
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.
print("undefined functions: "+function_name)
"""
print("undefined function: "+function_name)
return
def define_output_vector(label, size):
"""
Function initializing 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.
"""
label_c = label.encode('utf-8')
libutilities.define_output_vector_ext(label_c, size)
def set_output_vector(vec, label):
"""
Function to 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()'.
"""
label_c = label.encode('utf-8')
for i in range(np.size(vec)):
libutilities.set_output_value(vec[i], i+1, label_c)
return
def set_output_value(value, val_index, label):
"""
Function to 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()'.
"""
label_c = label.encode('utf-8')
libutilities.set_output_value(value, val_index, label_c)
return
......
......@@ -248,7 +248,7 @@ class MbsData(object):
Example
-------
>>> mbs_data = robotran.MbsData("../dataR/UExampleProject.mbs")
>>> mbs_data = MBsysPy.MbsData("../dataR/UExampleProject.mbs")
>>> mbs_data.user_model["MyUserModel"]["MyScalar"] = 3.0
>>> print(mbs_data.user_model["MyUserModel"]["MyScalar"])
3.0
......@@ -286,18 +286,26 @@ class MbsData(object):
symbolic_path : str, optionnal
The path to the folder containing the symbolic functions if the
default project structure are not used.
prj_functions_c : None or str
prj_functions_c : None or str, optionnal
Option to load some of the project functions from the project C
library. Accepted values are:
- None : All project function are defined in python
- "symbolic_only" or "S" : Symbolic function comes from C library
- "symbolic_and_user" or "SU" : Symbolic and user functions come from C library
default is None
prj_lib_path : None or str
prj_lib_path : None or str, optionnal
Required if 'prj_functions_c' is not None
Give the location of the folder containing "symbolicR/" and, or
"userfctR/". Each one of the subfolder have to contain the corresponding
library (ie: libProject_symbolic.so for linux).
- In Linux, it gives the location of the folder containing the
"symbolicR/" and, or "userfctR/" folders. Each one of the subfolder
have to contain the corresponding library (ie: libProject_symbolic.so).
- In Windows, it gives the location of the folder containing the project
libraries (Project_symbolic.dll and/or Project_userfct.dll).
- In MacOs the expected behavior is the same as Linux. It must be tested.
default is None
Returns
-------
A loaded mbs file in a MbsData instance.
"""
# Retrieve prj_functions_c value
if prj_functions_c is None:
......@@ -494,6 +502,13 @@ class MbsData(object):
- user_JointForces (from joint_forces.py)
- user_LinkForces (from link_forces.py)
- user_Link3DForces (from link3D_forces.py)
Parameters
----------
user_path : str or None, optionnal
The path to the folder containing the user functions if the default
project structure are not used.
default is None
"""
template_path = os.path.join(__MODULE_DIR__,'../templates/user')
project_path = self.project_path
......@@ -585,6 +600,13 @@ class MbsData(object):
- sensor (from mbs_sensor_MBSNAME.py)
- link (from mbs_link_MBSNAME.py)
- link3D (from mbs_link3D_MBSNAME.py)
Parameters
----------
symbolic_path : str, optionnal
The path to the folder containing the symbolic functions if the
default project structure are not used.
defult is None
"""
mbs_name = self.mbs_name
......@@ -881,11 +903,26 @@ class MbsData(object):
def set_nb_userc(self, nb):
""" Set the number of user constraints. """
"""
Set the number of user constraints.
Parameters
----------
nb : int
The number of user constraints.
"""
libutilities.mbs_set_nb_userc(self.mbs_data_ptr, nb)
def set_qu(self, indices):
""" Set the specified joints as independent. """
"""
Set the specified joints as independent.
Parameters
----------
indices : int, list or numpy.ndarray
The ids of the joints to set as independent.
"""
if isinstance(indices,(list,np.ndarray)):
for index in indices:
libutilities.mbs_set_qu(self.mbs_data_ptr, index)
......@@ -893,7 +930,14 @@ class MbsData(object):
libutilities.mbs_set_qu(self.mbs_data_ptr, indices)
def set_qv(self, indices):
""" Set the specified joints as dependent. """
"""
Set the specified joints as dependent.
Parameters
----------
indices : int, list or numpy.ndarray
The ids of the joints to set as dependent.
"""
if isinstance(indices,(list,np.ndarray)):
for index in indices:
libutilities.mbs_set_qv(self.mbs_data_ptr, index)
......@@ -901,7 +945,18 @@ class MbsData(object):
libutilities.mbs_set_qv(self.mbs_data_ptr, indices)
def set_qa(self, indices):
""" Set a variable to actuated partition. """
"""
Set the specified joints as actuated.
Actuated joints are only used by equilibrium analysis (in some cases)
and inverse dynamics. Actuated joint are also member of one of the other
partition (independent or dependent).
Parameters
----------
indices : int, list or numpy.ndarray
The ids of the joints to set as actuated.
"""
if isinstance(indices,(list,np.ndarray)):
for index in indices:
libutilities.mbs_set_qa(self.mbs_data_ptr, index)
......@@ -909,7 +964,14 @@ class MbsData(object):
libutilities.mbs_set_qa(self.mbs_data_ptr, indices)
def unset_qa(self, indices):
""" Unset a variable from the actuated partition. """
"""
Remove the specified joints from the actuated joints.
Parameters
----------
indices : int, list or numpy.ndarray
The ids of the joints to be removed from the actuated list.
"""
if isinstance(indices,(list,np.ndarray)):
for index in indices:
libutilities.mbs_unset_qa(self.mbs_data_ptr, index)
......@@ -926,7 +988,26 @@ class MbsData(object):
if __DEBUG__ : print("DEBUG>> MbsData pointer deleted")
def reset(self,verbose=False):
""" Reset mbs_data to its inital value."""
"""
Reset mbs_data fields to its inital value.
The following fields are resetted according to the values storied in the
field in parentheses:
- MbsData.q (MbsData.q0)
- MbsData.qd (MbsData.qd0)
- MbsData.qdd (MbsData.qdd0)
- MbsData.ux (MbsData.ux0)
- MbsData.Qq (filled with 0)
- MbsData.Qa (filled with 0)
- MbsData.Qc (filled with 0)
- MbsData.tsim (MbsData.t0)
Parameters
----------
verbose : bool, optional
Set to 'True' to print resetting validation.
default is False
"""
libutilities.mbs_reset_data(self.mbs_data_ptr)
if verbose :
print("mbs_data reseted to initial value")
......@@ -1058,13 +1139,10 @@ class MbsData(object):
mbs_part = MbsPart(self)
mbs_part.set_options(verbose=False, rowperm = True)
mbs_part.run()
mbs_dirdyn = MbsDirdyn(self)
mbs_dirdyn.set_options(**kwargs)
results = mbs_dirdyn.run()
else:
mbs_dirdyn = MbsDirdyn(self)
mbs_dirdyn.set_options(**kwargs)
results = mbs_dirdyn.run()
mbs_dirdyn = MbsDirdyn(self)
mbs_dirdyn.set_options(**kwargs)
results = mbs_dirdyn.run()
return results
......@@ -1346,7 +1424,7 @@ class _UserModelDict(dict):
tab[0][0] = value
elif type(value) is int:
tab = self.__getarray__(key)
tab[0][0] = int(value)
tab[0][0] = float(value)
else :
print("UserModel "+self._parent_key+"."+key+" is a float, "+str(type(value))+" was given")
elif self._type[key] == 7:
......@@ -1397,9 +1475,10 @@ class _UserModelDict(dict):
return dict.__getitem__(self, key)
else :
if key in self.keys():
if self._type[key] == 1 or self._type[key] == 7 :
return dict.__getitem__(self, key)[0][0]
if self._type[key] == 1:
return float(dict.__getitem__(self, key)[0][0])
elif self._type[key] == 7:
return int(dict.__getitem__(self, key)[0][0])
else:
return dict.__getitem__(self, key)[0]
else:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment