isrlab / stedy Goto Github PK

The connectivity matrix used in STEDY currently places the bars before the cables: [Cb; Cs].

Usually, it's done the other way around, [Cs; Cb], in the form-finding literature for tensegrities. See for example, Tran and Lee 2010, Advanced Form-Finding of Tensegrity Structures. I believe Skelton does it this way in his book, as does Motro, and Sultan, and Mirats-Tur.

Not a big deal, just worth noting so people don't accidentally make mistakes when coming in to use your software.

One of JOSS's review criteria seems to be the API: https://joss.readthedocs.io/en/latest/review_criteria.html

Three points to raise about the documentation in its current state. I would currently rate the library straddles the line between the two review options of

"OK: Core API functionality is documented
Bad (not acceptable): API is undocumented"

Three suggestions.

1. There are undocumented functions. For example, lagTensegrityDynamics.m, which seems to be very important. Would need to specify, for example, what exactly the state 'x' is here (full rigid body system state? nodal positions/velocities?)

2. It would be best if MATLAB's inherent 'help' function outputs the API at the top of each file. Example,

help antimateTenseg

only returns the license right now. Adding a % where each empty newline is currently will make the 'help' function return that contiguous block. (Add this to line 5 in animateTenseg, for example, and related places throughout.)

3. Though not necessarily required, some document that outlines what each file/function is used for would be incredibly helpful. A minimum example would be a text file that outlined the folder structure and the files within them. This could go in the README. Better would describe each function and when/how it's used throughout the simulation. Best would be to provide MATLAB-style suggested inputs and their corresponding expected outputs: example, >>help linprog.

As it currently stands, a user needs to dig around in the example to see where each file in ~/Main comes in.

To meet the "OK: Core API functionality is documented", I would suggest the authors address points 1 and 2, and include the minimum example from 3. Should be minimal changes.

An error is thrown in the Template_Dbar.m example, when the video is written using VideoWriter. May be related to #3 .

Error:

Error using VideoWriter/writeVideo (line 344)
Frame must be 912 by 911

Error in animateTenseg (line 95)
writeVideo(vidObj,im2frame(F.cdata));

Error in Template_DBar (line 153)
animateTenseg(t,y,tData,time_loc,filename,formatSpec,frameRate,AZ, EL,axLims);

I still get a .avi file produced, but it's only got a small number of frames.

A quick google search suggests something like
https://www.mathworks.com/matlabcentral/answers/327160-error-using-videowriter-writevideo-line-344-frame-must-be-434-by-343

For reference, I'm using Ubuntu 18.04 with MATLAB R2017b.

Can you please work on adding community guidelines by adding a CONTRIBUTING.md file (and by linking to it in your readme)? See also this link for more information: https://help.github.com/articles/setting-guidelines-for-repository-contributors/

I also recommend adding a CODE_OF_CONDUCT.md file (to which you can link in the contributing file).

You can get a template for the code of conduct file from here: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

You can also check out how my personal project uses a contibuting and coc file:
https://github.com/gibbonCode/GIBBON

Let me know if you have questions.

1. Please link to contributing guidelines and code of conduct in your README.
2. For the startup instructions it seems one flow is 1, 2, 3, 6, if no error occurs and all steps if an error does occur. This does not seem so clear. Perhaps rename step 6 to 4 and add a note to step 3 to say that if an error occurs please do steps 3b and 3c below. Or change this in a similar way to clarify the two processes.
3. Please consider splitting the startup section into two sections, e.g. 1) Installation and setup instructions, 2) Getting started.

This is a minor point, and might just be my misunderstanding, so please correct me or point to a place this is discussed.

All the structures and examples in STEDY use bars that are pinned with respect to each other. But, that doesn't actually cover all tensegrity structures, and doesn't actually cover even type-1 structures. There are some robots where the bars are rigidly attached in groups and don't move with respect to each other, but still move in the world frame. See for example Friesen's 2014 ICRA paper, Brian Mirletz' 2015 papers in IROS and Soft Robotics, or my own ACC 2017 paper on a tensegrity spine robot.

A traditional example of such a structure is Snelson's "X-Cross" in chapter 1 of Skelton's book.

Is there a way to capture this behavior in your system? Example, is it possible to pin a joint in all 3 degrees of freedom so it becomes built-in but still moves freely? Does STEDY have the ability to do the X-cross?

If not - again, that's fine, it should just be noted that this is a limitation. The software is very extensive as it is, and is a great contribution to the community.

About Template_DBar.m

1. When I run this example I receive a question on the command prompt Enter output time-step:, please can you add a suggested sensible time-step? E.g. rephrase it as Enter output time-step (e.g. 1):
2. After entering 1 as the output time-step I get the following error message:

Error using animateTenseg (line 29)
The specified profile is not valid.

Error in Template_DBar (line 147)
animateTenseg(t,y,tData,time_loc,'DBar_Animation.mp4','MPEG-4',frameRate,AZ, EL,axLims);

I am using a 64-bit Ubuntu 18.04 machine with MATLAB R2018b.

The user guide refers to TemplateForUser_DBar.m, however this file does not exist. Perhaps this should be Template_DBar.m?

The file tensegEq.m is very interesting, but the underlying procedure doesn't seem to be really documented, doesn't appear in the author's corresponding preprint, and isn't anything that I've seen before in the literature.

I would suggest the following, so that users can verify why the equilibrium solver works as it does.

Equilibrium is a common problem in tensegrity structures (form-finding), and a great number of assumptions are made in tensegEq.m that need to be explained. Example – seems like a constraint satisfaction problem, no objective function, as opposed to an energy minimization problem. This code should be commented, and the approach should be compared to that of something such as the Tibert and Pellegrino paper “Review of Form-Finding Methods for Tensegrity Structures” from IJSS in 2003.

In particular - papers such as Friesen's 2014 ICRA paper on the DuCTT robot propose a quadratic program to solve this problem, so it's worth saying why you're doing a linear program (constraint satisfaction) instead.

Also, should be made explicit that equilibrium is posed in terms of force-densities (and for what reasons – there are good ones just needs explanation) and how those then become equilibrium inputs for the dynamics problem (e.g. how they’re transformed into forces, and maybe then into rest lengths?)

The documentation concerning the point masses is a bit confusing, and I'm a bit worried that I would be accidentally making wrong assumptions as the code currently stands.

The docs say "Keep in mind that point masses are added automatically to the structure depending on the connectivity matrices." Here are a few questions to answer about this.

1. Is there any way to turn this assumption off entirely? Does that break the dynamics solver?

2. It seems this says "point masses are automatically placed where cables connect, but no bar is present," as if the point masses were suspended within a cable net (cable net = tensegrity without bars.) Does this happen often, is it a useful feature, or is it necessary due to the dynamics formulation?

Lines 19/20 read:

% (0,+-1,+-phi), where phi is the golden ratio. The payload is then be
% origin.  In addition, we would like to have 3 nodes (node 1,2,9) laying

The sentence The payload is then be origin. is probably incorrect.

Currently, the documentation assumes a direction for its coordinate system, but I can't actually tell which axes go where. Answering the following questions in the documentation / user guide would be helpful.

1. Which direction is gravity assumed to act in, in the generic case? Your other examples include it as the third coordinate, but I'm unsure if that's assumed in general (example, if I was to add gravity to the Dbar example, what's "down?")

2. What is the coordinate system for your axes? Is there a frame that can be imposed on one of the images?

3. As a result, I can’t actually tell your node numbering in the example (Template_Dbar). Which nodes are which?

However, one significant potential question about the underlying coordinate system is its handed-ness. It would be worth addressing the following question relatively thoroughly.

4. The Dbar example seems to use the first and third coordinates for the in-plane example. Using “z” as “vertical” in two dimensions, with positive numbers in the first coordinate being "to the right of the origin", might actually imply a left-handed coordinate system – I’ve come across this issue in my own work, where keeping a right-handed coordinate system requires gravity in -z in three dimensions but -y in two dimensions. A left-handed system is fine, that’s what's used in Bullet Physics underlying NTRTsim, but that's a numerical solver instead of an analytic solution. This may have significant implications for the cross-products in Lagrange’s equations and should be discussed explicitly, especially if the handedness accidentally changes between the 2D and 3D case.

I noticed that I have to specify fixed nodes in the simulation code,

I try to delete all code related to fixed nodes,but if I didn't specify fixed nodes,it will remind me:

Optimization failed. Please check input parameters again.

After entering the time-step (I entered 0.01) I get the following error message for the example Arm.m and Ball.m:

Error using odearguments (line 21)
When the first argument to ode45 is a function handle, the tspan argument must have at least two elements.

Error in ode45m (line 115)
  odearguments(FcnHandlesUsed, solver_name, ode, tspan, y0, options, varargin);

Error in tensegSim (line 35)
    [t,y] = ode45m(@lagTensegrityDynamics,simTime,x0,options,tData);

Error in Ball (line 125)
[t,y] = tensegSim(x0,tEnd,tData,options);

System info:
MATLAB R2018b, Ubuntu 18.04 64-bit.