[petsc-dev] TSSolve web page JED and EMIL READ THIS!

[Barry Smith]

> On Feb 6, 2015, at 7:58 PM, Jed Brown <jed at jedbrown.org> wrote:
> 
> Barry Smith <bsmith at mcs.anl.gov> writes:
> 
>>> On Feb 6, 2015, at 12:28 PM, Mark Adams <mfadams at lbl.gov> wrote:
>>> 
>>> http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/TS/TSSolve.html#TSSolve
>>> 
>>> The TSSolve web page does not have an output parameter.  It is not clear to my why you would use TSSetSolution.  Is there any difference between using and not using TSSetSolution other than you do not need to give TSSolve u?  
>> 
>> 
>>   This is fuzzy (even fuzzier than the fact that KSP has
>>   KSPSetSolution() or one can pass it into KSPSolve() while
>>   SNESSolve() does NOT take a solution.
> 
> What do you mean "SNESSolve does not take a solution"?
> 
>  PetscErrorCode SNESSolve(SNES snes,Vec b,Vec x)
> 
>>   Our API here is not great:
>> 
>>   Normally it doesn't matter, one can pass it in either place or both places. BUT if TS_EXACTFINALTIME_INTERPOLATE is used then the u is required (this is not documented and the error checking does not give useful feedback to the user) but the user could either or not call TSSetSolution() also. The reason for this case is that TS internally wants to keep the actual final step step inside the TS object and interpolate the solution into the u provided to the user.  Note also that TSGetSolution() after solve returns the solution at the final time computed by the TSSolve() NOT the interpolated solution at the time requested by the user. This could also be confusing.
>> 
>>   I can document this crappy API but my instinct is too actually
>>   remove TSSetSolution() to get rid of the oddball special case and
>>   unneeded and hence confusing two ways of passing the "solution". 
> 
> I never liked the pattern of calling XXSolve() with u=NULL.  I think you
> liked the idea that the user could configure a solver and say solve
> without having to create a vector.

   Yeah that's right, the DM would be responsible for creating the vector. In the linear case the user can provide a function to compute the right hand side with KSPSetComputeRHS() so the DM can determine the appropriate vector sizes inside the KSP and the user doesn't have to worry about initially creating the right size vectors to pass into KSPSolve(). Similarly if we had a TSSetComputeInitialConditions() (which for some reason we don't yet have) 
TS could create the "solution" vector internally based on the DM and fill it up appropriately and again the user need not provide any vectors directly (or monkey with how to provide them). 

   So we actually have three ways to get vectors for solutions, in order of priority, first overrules second overrules third

        KSPSolve(x                SNESSolve(x                TSSolve(x
        KSPSetSolution()       SNESSetSolution()       TSSetSolution()
        KSPSetDM                 SNESSetDM                 TSSetDM  (this is currently not used to create a vector).

and one reason for the XXXGetSolution() is if the DM created the solution inside the XXX object, the user can get it back (otherwise the user cannot access the solution created this way.). The DM create approach also allows things like grid sequencing, adaptive refinement without requiring the user to worry about layouts of intermediate sized vectors etc.

   So going back to my email, now with more clarity, do we get rid of the XXXSetSolution/RightHandSide() paradigm; this would void questions like Mark's about what the differences are between them**. But do we lose any useful functionality? 

** thus one either calls the solvers with vector arguments to be used or with NULL arguments and the solver creates them.

  Barry

>  I can see how this would be
> attractive for adaptive methods, but I'd rather solvers behave closer to
> stateless.
> 
>>  Another alternative is to remove the u argument to TSSolve()
>>  completely and have the user always call TSSetSolution(). Again when
>>  TS_EXACTFINALTIME_INTERPOLATE we'd duplicate that thing internally
> 
> I don't like this.