[SciPy-dev] change scipy.optimize function signatures?? FEEDBACK NEEDED!! (ticket 285)

[Michael McNeil Forbes]

On 19 Jul 2007, at 11:03 AM, Alan G Isaac wrote:

> On Thu, 19 Jul 2007, Anne Archibald apparently wrote:
>> Perhaps making objects to represent optimization problems might make
>> it easier to suppy as many or as few parameters as desired?
>
> BUT the immediate issue is:
> how to handle this ticket?
> http://projects.scipy.org/scipy/scipy/ticket/285
>
> Are you saying, handle it like this...
>
> Keep the `brent` signature unchanged,
> but move the core code into a class `Brent`.
> The class can expose additional parameters as desired.
> The `brent` function will now create an instance
> of the `Brent` class and run it.
> Individuals wanting finer control over optimization
> parameters can create their own instance and set
> parameters to their heart's desire.

Perhaps the opposite idea would work: keep the brent function call  
with explicit arguments close to the underlying C or Fortran code and  
make a Brent class that provides users with a unified and simplified  
interface to this function along the line of Matthieu's proposal.

My idea is to keep the workhorse functions with minimal argument  
processing so that they can be used when efficiency is a concern  
(keeping the signature close to the underlying C functions allows one  
to inline the code if speed is really needed and possibly maintain  
backward compatibility, though argument names should at least be  
consistent!)

The class interface could then do more extensive argument and option  
processing that is slow, but user friendly and "smart": suitable for  
use outside of loops or interactively.

---------------------
As for dealing with options, I have been thinking of several ideas,  
but have not had time to put them together in a proposal yet.  I am  
just throwing out my ideas here since people are thinking about this.

I have the following long-term "goals":

User Oriented:
1) Consistent optimization parameters across all methods (same names  
and semantics where possible)
2) Easy access to access the parameters in docstrings.
3) Ability to use functions with a minimal number of parameters (good  
default values).
4) Easy to get and manipulate the default parameters programatically  
(i.e. the function/class could provide a dictionary filled with the  
default parameters for the user to modify in subsequent calls.)
4a) It would be nice if this "dictionary" of parameters was also  
"documented" in some way to allow easy access to the descriptions of  
the options.
6) Access to efficient underlying functions, possibly allowing for  
inlining with minimal code changes.

Developer Oriented:
7) Options should be easily specified with a description in a single  
place.
8) Docstrings and other option documentation should be generated  
automatically from this specification so that there is no duplication  
of code/documentation.
9) Along the lines of Matthieu's proposal, if various optimization  
"modules" are grouped together, then it would be nice if the  
containing module could dynamically query the components and present  
a complete list of relevant parameters to the user both in the  
docstring and through a default parameter object.

Ideas for implementation:
A) Python's introspection tools provide ample ways for dynamically  
modifying docstrings, so as long as the development interface is kept  
clean, this should be easily implemented.
B) Function decorators could provide a very nice syntactic mechanism  
for specifying options and arguments.  The decorators can modify the  
docstring as required, and parameters/default values etc.  I thought  
this would be a great way of dealing with these issues but there a  
big problems with pickling/archiving decorated functions and pickling  
functions can be very useful.  Decorators also require Python 2.4  
which may be a problem.
C) Attributes can be used to nicely provide documented option  
containers.
D) One could even dynamically create subclasses of the option values  
so the values themselves are documented (this may be abusing the  
flexibility of python's introspection abilities but I think it is  
cute...  It is probably dangerous though.)

I wish I had a more concrete proposal ready, but I simply have not  
had the time;-(

Michael.