Add list of references

[moorepants]

From: https://github.com/openjournals/joss-reviews/issues/300#issuecomment-325696614

A list of key references including a link to the software archive - References are not rendered in the paper.md file - No link to software archive - Other than Betts2010, the other citations appear to be just for dependencies. The paper should include citations to other software for direct colocation, and a comparison of feature sets, etc.

• [x] finish up the table of comparisons

[moorepants]

• Casadi
• Gpops
• http://www.psopt.org/ https://github.com/PSOPT/psopt

[moorepants]

@tvdbogert If you have any to add to this list here, feel free to. I'm not sure I'm that equipped to do a feature comparison, as I haven't used the other software. But I'll give it a shot.

[moorepants]

@tvdbogert Your paragraph looks good. Let's add in the references.

[tvdbogert]

References were added in paper.bib. How can I get the rendered version of the list of references?

The comparison table still has gaps. Which ones should I try to fill?

[moorepants]

I'm not sure how they render the references. I would suggest using a reference manager like jabref, zotero, mendely, etc to export the references to see if they look ok.

[moorepants]

Also, can you help me fill out the table in paper.md. You might know some of the things off hand or where the answer is more quickly.

[moorepants]

I added a paper.tex file that can be compiled to check the bib entry renderings. I also opened paper.bib in jabref and let it format things and fixed a few errors.

[tvdbogert]

Thanks. Github's rendering of paper.md ends with the heading "References" and I was expecting to see the list of references there. I don't even know what a .md file is supposed to do.

[moorepants]

I think that the journal processes the md file and the bib file to create something like: http://joss.theoj.org/papers/050362b7e7691d2a5d0ebed8251bc01e

BTW, that paper is pretty thorough. I though you were just supposed to create an abstract of sorts.

[tvdbogert]

That paper is a couple of paragraphs longer maybe. I suggest we just address the reviewer comments and not get too ambitious. As I mentioned earlier, when you try to be thorough, the expectations will rise and you get more criticism.

[moorepants]

Agreed. I think the main remaining things are getting the one example working again (or removing it) and to add some of the mathematical description to the documentation.

[moorepants]

@tvdbogert We are only missing information for DYNOPT and GESOP. Do you have info or should I research them?

I also just found this: https://otis.grc.nasa.gov/

[moorepants]

Just came across this. It says is had symbolics and trajectory optimization: http://ayonga.github.io/frost-dev/pages/introduction.html

[tvdbogert]

Good find, should be cited. It's a good sign that these tools are popping up everywhere.

[moorepants]

BTW, I'm unlikely to finish this until xmas break. I've been working 60+ hr weeks to keep up with classes at the moment...

[moorepants]

@tvdbogert I added OTIS and FROST to the table. See the results here:

https://github.com/csu-hmc/opty/blob/master/paper.md

I moved the table to paper-table.rst and use rst2html to create the html that I then copy into paper.md, which renders correctly.

There are still gaps in the table, in particular for DYNOPT and GESOP. Can you have a look and see if you know any other particulars. If not, should we leave the caveat that I added about missing info or should we remove them from the table?

[tvdbogert]

I found some information about DYNOPT and GESOP, I added this with references in the table but I did that in paper.md which breaks your pipeline. Sorry about that, you may have to copy that back into the .rst file.

I was not sure how you distinguish between DAE and Implicit Dynamics. Aren't they the same? Those columns are the same except for DIDO and PSOPT. DYNOPT allows a mass matrix which is a subclass of DAE/Implicit dynamics.

[moorepants]

Yeah, I wanted to ask you about the DAE thing. In fact, I'm not completely sure that opty can handle DAEs or not. DAEs are differential equations with additional algebraic equations (like a kinematic constraint or something). I'm not sure I have all of the terminogoly precisely correct.

Here is how I have been defining things (which may not be correct);

Implicit First Order Ordinary Differential equation: f(y'(t), y(t), t) = 0

Explicit First Order Ordinary Differential equation: y'(t) = f(y(t), t)

Implicit First Order Differential Algebraic Equation: f(y'(t), y(t), t) = 0 and g(y(t), t) = 0

Explicit First Order Differential Algebraic Equation: y'(t) = f(y(t), t) and g(y(t), t) = 0

So I have implicit/explicit forms of both DEs and DAEs.

What should it be?

[moorepants]

There is also this form, which I forget what I've called it:

M y'(t) = f(y(t), t)

The "mass matrix form"?

[tvdbogert]

Yes, that's the mass matrix form. If M is non-invertible you effectively have a DAE.

The implicit form is a DAE if the mass matrix df/dxdot is non-invertible, otherwise it's an implicit ODE.

Opty can handle DAE (and I have done that, but not with opty) as long as one of these two conditions is true: (1) the Jacobian is such that the algebraic variables could be solved from the differential variables, or (2) the cost function ensures that the algebraic variables are uniquely solved. The latter is basically the same reason why the unknown control variables being in the cost function.

Maybe, for simplicity, we should not talk about DAE capability (then we have to get into index 1, 2, etc and be careful with terminology). I suggest we only say whether implicit formulation is supported. That's a simply a formulation and API issue, nothing to do with invertability. etc. Then we can say "yes" or "mass-matrix form" or "no" in the "implicit formulation" column.

Even an index-3 DAE (i.e. a multibody system with additional kinematic constraints) could be solved by opty if the cost function includes all of the (algebraic) reaction force variables. This is another confirmation that DAE capability has nothing to do with the software or algorithm. It also depends on the cost function.

[moorepants]

That all sounds fine. I will remove the DAE column.

As a side note, my thoughts were that it is worth describing the implicit/explicit form regardless of if you have a DAE or not because removing the need to both form the mass matrix and solve for the state derivatives removes a fairly large computational burden which is advantageous with ODEs and DAEs.

[tvdbogert]

Yes, that would be worth mentioning because opty has this capability and others don't.

Some of these tools have the limitation that they don't scale well to large problems or high-dimensional state spaces. But there is no way we can make specific statements. Maybe a general cautionary note.

[moorepants]

Ok, the DAE column is gone and I added an OTIS citation. I'm going to close this.