Support fixed step integration for a const IntegratorBase

[wei-chen-li]

Resolves #22665

The implementation follows the discussion to offer a new entry point: IntegratorBase<T>::IntegrateWithSingleFixedStepToTime(const T& t_target, Context<T>* context) const which:

1. updates the mutable context argument,
2. still writes to the error control estimate,
3. still writes to book-keeping statistics -- by marking them as mutable,
4. still writes to scratch memory -- by marking them as mutable.

---

This change is 

[jwnimmer-tri]

@drake-jenkins-bot ok to test

+@sherm1 for feature review or delegation, please.

[sherm1]

Feature pass done with some requests for clarification.
Also, our styleguide convention mentioned below is to put the Context as the first argument. That's not a hard requirement, but please consider it for consistency with other Drake code.

Reviewed 8 of 19 files at r1, 11 of 11 files at r2, all commit messages.
Reviewable status: 11 unresolved discussions, LGTM missing from assignee sherm1(platform), needs at least two assigned reviewers, commits need curation (https://drake.mit.edu/reviewable.html#curated-commits) (waiting on @wei-chen-li)

---

systems/analysis/integrator_base.h line 1109 at r2 (raw file):
BTW consider adding

• Not thread safe

---

systems/analysis/bogacki_shampine3_integrator.h line 68 at r2 (raw file):

  // Vector used to save initial value of xc.
  mutable VectorX<T> save_xc0_;

BTW for consistency with the other data members (err_est_vec_, derivs[123]_), consider changint this to std::unique_ptr<VectorX<T>> to achieve mutability the same way the other temps do. Really all these members are effectively mutable (just the pointer to them is const) but as written it looks like only save_xc0 is mutable.

---

systems/analysis/runge_kutta3_integrator.h line 89 at r2 (raw file):

  // These are pre-allocated temporaries for use by integration. They store
  // the derivatives computed at various points within the integration
  // interval.

BTW consider adding "// also mutable"

---

systems/analysis/runge_kutta5_integrator.h line 86 at r2 (raw file):

  // These are pre-allocated temporaries for use by integration. They store
  // the derivatives computed at various points within the integration
  // interval.

BTW also mutable

---

systems/analysis/implicit_euler_integrator.h line 531 at r2 (raw file):

  // The continuous state update vector used during Newton-Raphson.
  std::unique_ptr<ContinuousState<T>> dx_state_;

BTW consider adding a comment noting that this is also intentionally mutable.

---

systems/analysis/integrator_base.h line 1093 at r2 (raw file):

   optimization, for which the integration process should be _consistent_: it
   should execute the same sequence of arithmetic operations for all values
   of the nonlinear programming variables. In keeping with the naming

It's not clear to me under what circumstances the proposed implementation achieves this consistency. It gets rid of the internal state stored in the Context by passing that as an argument. But at least in the case of the implicit integrators, I believe the Jacobians and possibly other algorithmic state are saved internally. If the intent is to limit the consistent behavior to explicit integrators (or a particular subset) that should be documented clearly here.

Also, I don't know what you mean by "all values of the nonlinear programming variables". There is no nonlinear programming going on here. I presume you have some application in mind, but the documentation here needs to explain what happens here. What exactly are the promises of this method? Are you saying that it will execute the same arithmetic operations when given the same arguments? That doesn't seem correct in general, unless some resets are done to clear out internal state for integrators that have it (or narrow the applicability of this function, ideally with some runtime enforcement to make sure it isn't misused). Less important but worth a note is that the statistics will be different even if the arguments are the same.

---

systems/analysis/integrator_base.h line 1096 at r2 (raw file):

   semantics of this function, error controlled integration is not supported
   (though error estimates will be computed for integrators that support that
   feature), which is a minimal requirement for "consistency".

minor: because this is const but not thread safe, there should be an @warning to that effect in the documentation. Users might otherwise assume that const here means "thread safe".

---

systems/analysis/integrator_base.h line 1098 at r2 (raw file):

   feature), which is a minimal requirement for "consistency".
   @param t_target The current or future time to integrate to.
   @param context The context to perform integration on on.

typo: on on -> on

---

systems/analysis/integrator_base.h line 1127 at r2 (raw file):

    if constexpr (scalar_predicate<T>::is_bool) {
      // Correct any round-off error that has occurred. Formula below requires

nit: the first sentence of this comment should be on the unconditional SetTime() call below rather than within the conditional error-checking block.

---

systems/analysis/integrator_base.h line 1699 at r2 (raw file):

  T largest_step_size_taken_{nan()};
  int64_t num_steps_taken_{0};
  mutable int64_t num_ode_evals_{0};

BTW I'm surprised to see only this one stat made mutable. A comment here would be helpful.

---

systems/analysis/radau_integrator.h line 187 at r2 (raw file):

  //           step of size `h`.
  bool StepRadau(const T& t0, const T& h, const VectorX<T>& xt0,
                 VectorX<T>* xtplus, Context<T>* context, int trial = 1) const;

BTW we have a Drake Styleguide advisory to put Context first in argument lists to avoid this kind of unpleasant interaction with default arguments. It's a preference rather than a requirement but putting Context first would be more consistent with other Drake code.