Changes v2.4.0 to v3.0.0

jgillis edited this page Jun 16, 2016 · 21 revisions

New calling syntax

Until now, the principle for calling a CasADi Function has been that the Python user passes either a list or a dictionary in and gets the same type back:

[r] = F([a,b])
[s,t] = G([a,b,c])
q = G({'a':a, 'b':b, 'c':c})

Or in MATLAB, the same but with cell arrays and structs:

v = F({a,b});
r = v{1};
v = G({a,b,c});
s = v{1};
t = v{2};
q = G(struct('a', a, 'b', b, 'c', c));

This syntax is has now been deprecated and replaced with a more natural calling syntax, using variable number of inputs and outputs. In Python:

r = F(a,b)
s,t = G(a,b,c)
q = G(a=a, b=b, c=c)

And in MATLAB:

r = F(a,b);
[s,t] = G(a,b,c);
q = G('a', a, 'b', b, 'c', c);

Since it's not always practical to work with variable number of inputs/outputs, the old calling syntax is still available, but has been renamed "call". In Python:

[r] = F.call([a,b])
[s,t] = G.call([a,b,c])
q = G.call({'a':a, 'b':b, 'c':c})

Or in MATLAB:

v = F.call({a,b});
r = v{1};
v = G.call({a,b,c});
s = v{1};
t = v{2};
q = G.call(struct('a', a, 'b', b, 'c', c));

Concatenation takes a variables number of inputs in Python

Vertical, horizontal and diagonal concatenation now takes a variable number of arguments in Python:

# Old syntax
x = vertcat([x1, x2])
# New syntax
x = vertcat(x1, x2)
# Or, if you already have a list:
v = [x1, x2]
x = vertcat(*v)

The same applies to horzcat and diagcat. In MATLAB there is no change (it was already variable number of inputs). In C++, the functions will continue to take a vector.

New QP solver syntax

Quadratic programs (QPs) can now be formulated using the same syntax as nonlinear programs (NLPs). Cf. #1590. For an demonstration of the new syntax, a simple example is available in C++ and in Python.

Interfaces

  • An interface to the GUROBI for solving mixed-integer QPs has been added
  • The CPLEX interface now supports mixed-integer QPs
  • qpOASES has been updated to latest version, 3.2 and has been thoroughly refactored. All options are now available.
  • All other interfaces have been refactored internally.
  • Solver-specific options, e.g. the IPOPT option "linear_solver" has to be set using an "ipopt." prefix:
solver = nlpsol('solver', 'ipopt', nlp, {'verbose':True, 'ipopt.max_iter':10, 'ipopt.linear_solver':'ma27'})

or, alternatively, by providing a dictionary with all the solver specific options:

solver = nlpsol('solver', 'ipopt', nlp, {'verbose':True, 'ipopt':{'max_iter':10, 'linear_solver':'ma27'}})

(the former is actually a shorthand for the latter). Cf. #1668

Deprecated features

  • ControlSimulator
  • Simulator Thanks to #1592, integrators now support outputting output at multiple time points.

Fewer Function classes

Classes inheriting from the Function base class (e.g. SXFunction, Integrator, NlpSolver) have been removed from the public API. Only the Function itself remains. Instead of calling the constructors of these classes, the user needs to call a function which returns a Function instance. #1585. Classes affected:

  • SXFunction: Call the constructor of the Function class instead. In practice this means renaming SXFunction -> Function
  • MXFunction: Call the constructor of the Function class instead. In practice this means renaming MXFunction -> Function
  • NlpSolver -> nlpsol (function that returns a Function instance)
  • Integrator -> integrator (function that returns a Function instance)
  • ImplicitFunction -> rootfinder (function that returns a Function instance)
  • QpSolver -> qpsol (function that returns a Function instance)
  • LinearSolver -> linsol (function that returns a Function instance)
  • ExternalFunction -> external (function that returns a Function instance)

Renamed functions

There has been an effort to clean up the naming in CasADi and remove superfluous functions and classes. Most functions are now named using underscore words separated by underscore (for_example_like_this). Cf. #1586. Some of the symbols in the API this affects:

  • mul -> mtimes
  • toCsc_matrix -> sparse
  • inner_prod -> dot (For Python: watch out you are using casadi.dot and not numpy.dot!)
  • isNull -> is_null
  • DMatrix -> DM
  • IMatrix -> IM
  • jacobianTimesVector -> jtimes
  • All queries of the form isXxx have been renamed is_xxx
  • Function::getStats -> Function::stats
  • SX::getName(), MX::getName() -> SX::name(), MX::name()
  • countNodes -> n_nodes
  • substituteInPlace -> substitute_inplace
  • Sparsity::dulmage_mendelsohn -> btf
  • Sparsity::strongly_connected_components -> scc
  • Matrix::hasNonStructuralZeros -> has_zeros
  • Function::nIn() -> n_in
  • Function::nOut() -> n_out
  • sumRows/sumCols -> sum1/sum2
  • collocationPoints -> collocation_points. Also the returned list is now one element less than before. To get the old behaviour, prepend the result with zero.
  • dimString -> dim
  • dependsOn -> depends_on

Misc

  • The name of a function object must now only consist of letters, numbers (never in first position), and underscores (never in first position or next to other underscores), i.e.
    • f = Function('this is an illegal name', ...) # error
    • f = Function('this_is_a_valid_name', ...) # OK

New C API for generated code

For details, see the user guide.