octave-dev — GNU Octave developers' list

[OctDev] more cleaning

[Etienne G. <et...@an...>]

  Also,

cg_min.m, bracket_min.m, semi_bracket.m, brent_line_min.m and the
associated test functions can also be removed. I will rename
test_cg_min_N.m test_min_N.m.

  Cheers,

  Etienne

-- 
Etienne Grossmann ------ http://www.isr.ist.utl.pt/~etienne

[OctDev] more cleaning

[Etienne G. <et...@an...>]

  Also,

cg_min.m, bracket_min.m, semi_bracket.m, brent_line_min.m and the
associated test functions can also be removed. I will rename
test_cg_min_N.m test_min_N.m.

  Cheers,

  Etienne

-- 
Etienne Grossmann ------ http://www.isr.ist.utl.pt/~etienne

[OctDev] Re: Optimization : bfgs and cg_min

[Etienne G. <et...@is...>]

  Hello,

ok, I guess the obsolete things are really obsolete and can be cleaned
out. I will rename bs_gradient2.m to bs_gradient.m (and modify bfgs
accordingly). I will remove dfp.m (unfortunately, changing
bs_gradient.m breaks dfp.m), so the bad news is we are loosing
dfp.m. I will also remove __quasi_func__.m, which becomes useless.

  As far as derivatives are concerned, numerical derivatives will be
the default (same as it was originally). A separated derivative
function can be passed using the "df" option. If the same function,
when asked for 2 output values, returns the derivative, then the "jac"
option ("GradObj" in  m*tlab) can tell bfgs.m to use that.

  Cheers,

  Etienne

On Fri, May 17, 2002 at 12:31:22PM -0500, Ben Sapp wrote:
# Hi Etienne, 
# 
# Please excuse the delayed response.  
# 
# On Friday 19 April 2002 01:18 pm, Etienne Grossmann wrote:
# > this is to ask the opinion of Octave-Forge developers and users on
# > what to do about the optimization functions :
# >
# >   My opinion is to replace the bfgs.m and nrm.m files so that the new
# > bfgs() function takes the same parameters as the actual cg_min(), and
# > remove this last function.
# 
# I agree.   However,  I think this does not go far enough.  I think we should 
# also remove dfp.m,  __quasi_func__.m and bs_gradient.m.   We might also 
# rename the new function you created called bs_gradient2.m to bs_gradient.m or 
# something more appropriate.  These become obsolete with the work you have 
# done.   I think we should avoid keeping around obsolete things just for the 
# sake of keeping them around.  
# 
# If you agree and you'd like me to do any of this let me know.  
# 
# >   I have verified on various quadratic programming cases and initial
# > positions that my modified bfgs2() executes the same algorithm, in the
# > same time (no extra overhead) as the original bfgs(). In terms of
# > speed, it is thus much quicker than cg_min(). In terms of flexibility,
# > it is better than bfgs(), since it can optimize wrt to any (not just
# > the 1st) argument, and the termination criterion can be tweaked.
# 
# Great!  I think this reaffirms that the new work you have done makes a fair 
# amount of the old optimization stuff obsolete.  
# 
# >   Another difference with the original bfgs(), which may be either an
# > advantage or a pain, is that it requires the derivatives of the
# > function to be provided by the user. This is an advantage because, if
# > a hand-made derivative is available, it can be used instead of the
# > numerical differentiation. This has the slight disadvantage that, if
# > you want to use numerical differentiation, you should provide the
# > function yourself, e.g. with cdiff().
# 
# At some point would you mind if I added a feature that if derivatives are not 
# supplied we go ahead and try to numerically approximate them?  
# 
# Cheers,
# Ben.  


-- 
Etienne Grossmann ------ http://www.isr.ist.utl.pt/~etienne

[OctDev] Re: Optimization : bfgs and cg_min

[Ben S. <bs...@la...>]

Hi Etienne, 

Please excuse the delayed response.  

On Friday 19 April 2002 01:18 pm, Etienne Grossmann wrote:
> this is to ask the opinion of Octave-Forge developers and users on
> what to do about the optimization functions :
>
>   My opinion is to replace the bfgs.m and nrm.m files so that the new
> bfgs() function takes the same parameters as the actual cg_min(), and
> remove this last function.

I agree.   However,  I think this does not go far enough.  I think we should 
also remove dfp.m,  __quasi_func__.m and bs_gradient.m.   We might also 
rename the new function you created called bs_gradient2.m to bs_gradient.m or 
something more appropriate.  These become obsolete with the work you have 
done.   I think we should avoid keeping around obsolete things just for the 
sake of keeping them around.  

If you agree and you'd like me to do any of this let me know.  

>   I have verified on various quadratic programming cases and initial
> positions that my modified bfgs2() executes the same algorithm, in the
> same time (no extra overhead) as the original bfgs(). In terms of
> speed, it is thus much quicker than cg_min(). In terms of flexibility,
> it is better than bfgs(), since it can optimize wrt to any (not just
> the 1st) argument, and the termination criterion can be tweaked.

Great!  I think this reaffirms that the new work you have done makes a fair 
amount of the old optimization stuff obsolete.  

>   Another difference with the original bfgs(), which may be either an
> advantage or a pain, is that it requires the derivatives of the
> function to be provided by the user. This is an advantage because, if
> a hand-made derivative is available, it can be used instead of the
> numerical differentiation. This has the slight disadvantage that, if
> you want to use numerical differentiation, you should provide the
> function yourself, e.g. with cdiff().

At some point would you mind if I added a feature that if derivatives are not 
supplied we go ahead and try to numerically approximate them?  

Cheers,
Ben.  

Re: [OctDev] Re: Optimization : bfgs and cg_min

[Rafael L. <lab...@mp...>]

[GROSSMANN:
  Salut Etienne,
:]

[SF: 
  Hi Octave-Smiths,
:]

* Etienne Grossmann <et...@is...> [2002-04-23 21:34]:

> I've worked a little bit on "some sort of a preprocessor" that allows to
> maintain many .m files with a single template. The idea is that many
> functions with different synopsis and nearly the same internals would be
> easier to maintain : 
> [...]

There is a neat tool called slice (http://www.engelschall.com/sw/slice/)
that does a similar job.  The exemple in the POD section of your script,
would work with slice like this:

File foo.tpl:

    This is for all                                           
    This is also for all
    [SIMPLE:hello world:]
    [OBSEQUIOUS:Your excellent highness, please accept my humble "hello":]
    That's again for all

Command for generating the files:

    for i in SIMPLE OBSEQUIOUS
        do slice -o ${i}uUNDEF:foo_$(echo $i|tr A-Z a-z).txt foo.tpl
    done

It is also possible to define output filenames from inside the template
file.  In this case:

File foo.tpl:

    %!slice -o SIMPLEuUNDEF:foo_simple.txt
    %!slice -o OBSEQUIOUSuUNDEF:foo_obsequious.txt
    This is for all
    This is also for all
    [SIMPLE:hello world:]
    [OBSEQUIOUS:Your excellent highness, please accept my humble "hello":]
    That's again for all
    
Command for generating the files:

    slice foo.tpl

-- 
Rafael

[OctDev] Re: Optimization : bfgs and cg_min

[Etienne G. <et...@is...>]

<only Paul>
  Hi Paul

<only Ben>
  Hi Ben

<only sf>
  Hi Octave-Smiths

</only>
  I've worked a little bit on "some sort of a preprocessor" that
allows to maintain many .m files with a single template. The idea is
that many functions with different synopsis and nearly the same
internals would be easier to maintain :

>From pki...@ja... Fri Apr 19 19:36:53 2002

# Maybe we could have three separate internal routines, one for each case?
# If you want to go that route, I suggest keeping a single source file with
# some sort of preprocessor markup and use make to generate the actual
# functions that get installed.  I don't think we can use the C preprocessor
# because it needs to understand identifiers and strings, so we would have to
# invent our own.  I know people have done matlab preprocessors in the past
# (me included) but I can't find any links at the moment.

  The preprocessor, called 'fsplit' (you suggest a better name if you
like) is really simple. If you put this mail run in a file foo.tpl and
and do

  fsplit foo.tpl

it will produce files 'foo_Paul.txt', 'foo_Ben.txt' and
'foo_sf.txt'. When it finds a tag

<only sf>

All that follows (until the next <only> or </only> tag) goes into the 
file foo_sf.txt.

<only Ben, Paul>

Now, this will go to 'foo_Paul.txt' and 'foo_Ben.txt'.

</only>

And this will go to all files.

The name of the input file is trimmed by removing the old suffix,
which is indicated by 

<oldsuffix tpl>

The suffix of the new files is indicated by the <newsuffix> tag, like

<newsuffix txt>

Now, of course, for .m files, one will want <newsuffix m>. Note that
tags that are not at the beginning of the line are ignored, so that
I can write <newsuffix whatever_I_like>, the suffix is still .txt.

  And that's it.

  Does this sound like useful stuff?

  Etienne

PS : I could add some options to facilitate maintainance. I have in
     mind : 

        fsplit --clean foo.tpl

     Which only removes the created templates.

-- 
Etienne Grossmann ------ http://www.isr.ist.utl.pt/~etienne

Re: [OctDev] Re: TSA-tb

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-04-08 22:21]:

> When these are done, I will cut a version for Dirk to include in Debian,
> then we can start hacking on the CVS server.

I am back home now, and I see that a new release of octave-forge was out
last week.  Should I try to remove that tsa/ directory now?

-- 
Rafael

[OctDev] comments

[Paul K. <pki...@ja...>]

I have a new set of summary docs available at:

	http://octave.sourceforge.net/index/index.html

Check it out.  Let me know what you think.

There are bugs that I know about, such as it doesn't
handle duplicate files in the tree.

Also, it would be nice to have a list of just the
functions on octave-forge and none from octave.

All files are generated from admin/make_index.  Feel
free to make changes, but check it back in frequently.

Paul Kienzle
pki...@us...

Re: [OctDev] Re: TSA-tb

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-04-08 22:21]:

> We have backups of the tarball.  But please wait for a couple of days.
> [...]
> When these are done, I will cut a version for Dirk to include in Debian,
> then we can start hacking on the CVS server.

Actually, removing the tsa directory with the CVSROOT/loginfo trick is
extremely straightforward and should do no harm to the CVS tree.  I just did
a test with a local CVS repository and it works fine.  However, I understand
your reluctance to doing hacks when a major release is under way.

Just tell me when I am allowed to do the hack.  After doping it, I will post
the cookbook here, so anybody can do similar things in the future.

-- 
Rafael

Re: [OctDev] Re: TSA-tb

[Paul K. <pki...@ja...>]

We have backups of the tarball.  But please wait for a couple of days.

I have finished sending FIXES patches to John (he has accepted most of
them) and now I have to update the build to reflect this.  Also, we are
most of the way toward having a "Functions by category" html set which is
much needed documentation on the state of octave/octave-forge.  I just need
to find the energy to build some nice html and maybe finish the last 10% of
the categorization.  No test target in the make file for this release :-(

When these are done, I will cut a version for Dirk to include in Debian,
then we can start hacking on the CVS server.

Thanks,

Paul Kienzle
pki...@us...

On Tue, Apr 09, 2002 at 12:02:18AM +0200, Rafael Laboissiere wrote:
> * Paul Kienzle <pki...@ja...> [2002-04-07 11:23]:
> 
> > The more complicated answer is that someone with a good understanding of
> > CVS can grab the entire CVS tree and manually edit the files so that tsa
> > never appears at the root level, then ask source forge to please replace
> > the CVS tree with the new one.  I am not that person.  Anyone else up to
> > the challenge?
> 
> To fix a permission problem in a CVS tree of another project at SourceForge,
> I did a trick using the CVSROOT/loginfo file.  Arbritary shell code in that
> file can be executed at cvs commit. 
> 
> I can try the trick for removing the tsa directory.  Should I?
> 
> -- 
> Rafael
> 
> _______________________________________________
> Octave-dev mailing list
> Oct...@li...
> https://lists.sourceforge.net/lists/listinfo/octave-dev
> 
> Sponsored by http://www.ThinkGeek.com/
> 

Re: [OctDev] Re: TSA-tb

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-04-07 11:23]:

> The more complicated answer is that someone with a good understanding of
> CVS can grab the entire CVS tree and manually edit the files so that tsa
> never appears at the root level, then ask source forge to please replace
> the CVS tree with the new one.  I am not that person.  Anyone else up to
> the challenge?

To fix a permission problem in a CVS tree of another project at SourceForge,
I did a trick using the CVSROOT/loginfo file.  Arbritary shell code in that
file can be executed at cvs commit. 

I can try the trick for removing the tsa directory.  Should I?

-- 
Rafael

[OctDev] Re: TSA-tb

[Paul K. <pki...@ja...>]

The simple answer is no.  We are stuck with tsa in the root forever more.

The more complicated answer is that someone with a good understanding of
CVS can grab the entire CVS tree and manually edit the files so that tsa
never appears at the root level, then ask source forge to please replace
the CVS tree with the new one.  I am not that person.  Anyone else up to
the challenge?

Paul Kienzle
pki...@us...

On Sun, Apr 07, 2002 at 05:56:40AM -0700, Alois Schloegl wrote:
> Paul, 
> 
> I tried to upload my TSA-toolbox, but it did not go into 
> octave-forge/extra/tsa rather then cvsroot/tsa. 
> Can you remove tsa from cvsroot? I do not know how to do it. 
> 
> Alois 
> 
> 

Re: [OctDev] Re: docbook

[Matthew W. R. <ma...@fr...>]

>   I am attaching a sligthly more recent version, in .tex and .html
>   (produced by HeVeA. Note : w/ the .Xresources specified by Paul,
>   it looks very much like the .dvi. And its almost like it
>   without).

As you might expect, looking at the page in Opera results in some
strange symbols showing up.  I don't know if html is the best way to
distribute documentation with lots of math.  Someone mentioned PDF
earlier, why not use that? 

--
Matthew W. Roberts
--------------------------------------------------------------------
Structural Engineering  *  Texas A&M University  *  ma...@op...

Re: [OctDev] Re: docbook

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-03-20 11:33]:

> I don't care too much about format so long as it is stable, convenient, and
> flexible.  If the latex to html translators do what we need, and we all are
> familiar with latex, then you will need to provide a compelling argument
> for us to learn DocBook.  

The only argument in favour of DocBook is that it is DTD designed for
technical documentation, containing specific tags like <function>,
<parameter>, etc.  Docbook is a markup "language", while LaTeX is just a
typesetting language (much like HTML in that regard).  That places LaTeX at
lower level of abstraction than DocBook.  Besides, that are hosts of ways to
efficiently parse DocBook-XML nowadays.

Actually, I don't care neither about the format, but the final choice would
depend on the answer to the questions: what are our specific needs here?
What kind of markup do we need in the doc strings?  Are those texinfo
markups enough, or do we need something more powerful?

-- 
Rafael

Re: [OctDev] Re: docbook

[Etienne G. <et...@is...>]

  Hello,

On Wed, Mar 20, 2002 at 11:33:30AM -0500, Paul Kienzle wrote:
# On Wed, Mar 20, 2002 at 04:33:50PM +0100, Rafael Laboissiere wrote:
# > * Paul Kienzle <pki...@ja...> [2002-03-20 10:01]:
# > > I'm attaching a short version of Etienne's optimization tutorial,
# > > and the resulting html from HeVeA.
# > 
# > Your post came without attachments.
# 
# I'll try again.
# 
# > 
# > > Make sure you have the following line in .Xresources:
# > > 
# > >   Netscape*documentFonts.charset*adobe-fontspecific:   iso-8859-1
# > > 
# > > then run xrdb .Xresources and restart netscape.  This magic lets the
# > > browser act on <FONT face=symbol>.  Also be sure that in preferences
# > > you allow the browser to use the font specified in the document.

  I am attaching a sligthly more recent version, in .tex and .html
(produced by HeVeA. Note : w/ the .Xresources specified by Paul, it
looks very much like the .dvi. And its almost like it without). This
is not a final version, because the name of the used minimization
function (minimize or u_minimize or fminunc) has not yet been really
decided upon. Or has it?

[snip]

# For this release Etienne can post his tutorial in html so that Dirk can
# update Debian.  It's not going to happen today since I couldn't stay awake
# at the computer last night, but I hope to get it together in the next
# couple of days.

  Isn't there a saying that says to go slowly in order to go far?
Thanks for the work, in all cases.
 
# For the next release I would like to resolve the documentation question.
# One solution is to put html/xml/pdf targets in the package makefiles and
# let each package use what it wants (latex or DocBook).  We also need to
# decide what browsers to support.  I don't want the bar too high since there
# are dinosaurs like me who still use netscape because they can't be bothered
# to figure out how to get galeon running.
# 
# - Paul

  Etienne


-- 
Etienne Grossmann ------ http://www.isr.ist.utl.pt/~etienne

Re: [OctDev] Re: docbook

[Paul K. <pki...@ja...>]

On Wed, Mar 20, 2002 at 04:33:50PM +0100, Rafael Laboissiere wrote:
> * Paul Kienzle <pki...@ja...> [2002-03-20 10:01]:
> 
> > I would prefer to use an open source tool.
> 
> Oh, I thought that TtM was free.  In this case, forget it.

It is free as in beer for linix, but $90 for windows.

> > I'm attaching a short version of Etienne's optimization tutorial,
> > and the resulting html from HeVeA.
> 
> Your post came without attachments.

I'll try again.

> 
> > Make sure you have the following line in .Xresources:
> > 
> >   Netscape*documentFonts.charset*adobe-fontspecific:   iso-8859-1
> > 
> > then run xrdb .Xresources and restart netscape.  This magic lets the
> > browser act on <FONT face=symbol>.  Also be sure that in preferences
> > you allow the browser to use the font specified in the document.
> 
> I much prefer the native MathML support in Mozilla.  The demo pages worked
> for me out of the box, provided that the X fonts server is providing the
> appropriate type1 math fonts.  The HeVeA way looks too hazardous to me.
> Besides, it relies on the <FONT> tag, which is deprecated in HTML 4.01
> (http://www.w3.org/TR/html401/present/graphics.html#h-15.2.2)
> 
> At any rate, I think that we are talking about the tool to get HTML out of
> the scraps of documentations, and that the format for those scraps is going
> to be LaTeX.  Right?

I don't care too much about format so long as it is stable, convenient, and
flexible.  If the latex to html translators do what we need, and we all are
familiar with latex, then you will need to provide a compelling argument
for us to learn DocBook.  I'm confident that we can find tools to do an
adequate job translating the latex math markup, so either latex or DocBook
is fine with me.

For this release Etienne can post his tutorial in html so that Dirk can
update Debian.  It's not going to happen today since I couldn't stay awake
at the computer last night, but I hope to get it together in the next
couple of days.

For the next release I would like to resolve the documentation question.
One solution is to put html/xml/pdf targets in the package makefiles and
let each package use what it wants (latex or DocBook).  We also need to
decide what browsers to support.  I don't want the bar too high since there
are dinosaurs like me who still use netscape because they can't be bothered
to figure out how to get galeon running.

- Paul

Re: [OctDev] Re: docbook

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-03-20 10:01]:

> I would prefer to use an open source tool.

Oh, I thought that TtM was free.  In this case, forget it.

> I'm attaching a short version of Etienne's optimization tutorial,
> and the resulting html from HeVeA.

Your post came without attachments.

> Make sure you have the following line in .Xresources:
> 
>   Netscape*documentFonts.charset*adobe-fontspecific:   iso-8859-1
> 
> then run xrdb .Xresources and restart netscape.  This magic lets the
> browser act on <FONT face=symbol>.  Also be sure that in preferences
> you allow the browser to use the font specified in the document.

I much prefer the native MathML support in Mozilla.  The demo pages worked
for me out of the box, provided that the X fonts server is providing the
appropriate type1 math fonts.  The HeVeA way looks too hazardous to me.
Besides, it relies on the <FONT> tag, which is deprecated in HTML 4.01
(http://www.w3.org/TR/html401/present/graphics.html#h-15.2.2)

At any rate, I think that we are talking about the tool to get HTML out of
the scraps of documentations, and that the format for those scraps is going
to be LaTeX.  Right?

-- 
Rafael

Re: [OctDev] Re: docbook

[Paul K. <pki...@ja...>]

I would prefer to use an open source tool.

Many tools (free and commercial) are listed at:

	http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html

I haven't gone through all the possibilities, but some of them
look adequate.

I'm attaching a short version of Etienne's optimization tutorial,
and the resulting html from HeVeA.

Make sure you have the following line in .Xresources:

  Netscape*documentFonts.charset*adobe-fontspecific:   iso-8859-1

then run xrdb .Xresources and restart netscape.  This magic lets the
browser act on <FONT face=symbol>.  Also be sure that in preferences
you allow the browser to use the font specified in the document.

The HeVeA pages have a more extensive example:

	http://para.inria.fr/~maranget/hevea/examples/suite.html

- Paul


On Wed, Mar 20, 2002 at 10:50:46AM +0100, Rafael Laboissiere wrote:
> * Paul Kienzle <pki...@ja...> [2002-03-19 15:52]:
> 
> > I was suggesting html as a distribution target, but latex for the source.  
> > 
> > The primary reason is that markup is tedious in MathML but not in latex.
> 
> Agreed.
> 
> > This suggests an alternative approach: Find everything in the document
> > that lies within $...$ or $$...$$ and use latex to convert it to mathML.
> 
> So you should consider TtM (http://hutchinson.belmont.ma.us/tth/mml/).  It's
> web trail translation for Mozilla is quite impressive.
> 
> -- 
> Rafael
> 
> _______________________________________________
> Octave-dev mailing list
> Oct...@li...
> https://lists.sourceforge.net/lists/listinfo/octave-dev

Re: [OctDev] Re: docbook

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-03-19 15:52]:

> I was suggesting html as a distribution target, but latex for the source.  
> 
> The primary reason is that markup is tedious in MathML but not in latex.

Agreed.

> This suggests an alternative approach: Find everything in the document
> that lies within $...$ or $$...$$ and use latex to convert it to mathML.

So you should consider TtM (http://hutchinson.belmont.ma.us/tth/mml/).  It's
web trail translation for Mozilla is quite impressive.

-- 
Rafael

[OctDev] Re: docbook

[Paul K. <pki...@ja...>]

I was suggesting html as a distribution target, but latex for the source.  

The primary reason is that markup is tedious in MathML but not in latex.

This suggests an alternative approach: Find everything in the document
that lies within $...$ or $$...$$ and use latex to convert it to mathML.

- Paul

On Tue, Mar 19, 2002 at 08:58:56PM +0100, Rafael Laboissiere wrote:
> * Paul Kienzle <pki...@ja...> [2002-03-19 12:25]:
> 
> > For the documentation we distribute we need to use a format that is
> > available to the user.  html and pdf are obvious candidates here, and I see
> > that most everyone will be able to view MathML with a bit of effort
> > (http://www.w3.org/Math/implementations.html).  Initially I'll use html
> > because it is easiest, but MathML seems like the direction we should go.
> 
> DocBook may be a better choice than HTML for documentation.  Indeed, DocBook
> is intended for writing software documentation, having tags like <funcdef>,
> <parameter>, <variablelist>, etc.  See the Element Reference chapter of the
> DocBook Book at http://www.docbook.org.
> 
> As an example of what DocBook can do, lokk at the documentation of the
> PLplot package, which has been converted (by me and others) into the DocBook
> format:
> 
>     http://plplot.sourceforge.net/resources/docbook-manual/
> 
> In particular, see the API section in
> 
>     http://plplot.sf.net/resources/docbook-manual/plplotdoc-html-0.4.3/api.html
> 
> -- 
> Rafael
> 
> _______________________________________________
> Octave-dev mailing list
> Oct...@li...
> https://lists.sourceforge.net/lists/listinfo/octave-dev

Re: [OctDev] Re: Nonlinear optimization tutorial

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-03-19 12:25]:

> For the documentation we distribute we need to use a format that is
> available to the user.  html and pdf are obvious candidates here, and I see
> that most everyone will be able to view MathML with a bit of effort
> (http://www.w3.org/Math/implementations.html).  Initially I'll use html
> because it is easiest, but MathML seems like the direction we should go.

DocBook may be a better choice than HTML for documentation.  Indeed, DocBook
is intended for writing software documentation, having tags like <funcdef>,
<parameter>, <variablelist>, etc.  See the Element Reference chapter of the
DocBook Book at http://www.docbook.org.

As an example of what DocBook can do, lokk at the documentation of the
PLplot package, which has been converted (by me and others) into the DocBook
format:

    http://plplot.sourceforge.net/resources/docbook-manual/

In particular, see the API section in

    http://plplot.sf.net/resources/docbook-manual/plplotdoc-html-0.4.3/api.html

-- 
Rafael

Re: [OctDev] Re: Nonlinear optimization tutorial

[Paul K. <pki...@ja...>]

I'm interested in the actual editting since that is what we are doing now.

Pure latex for tutorial guides seems to be the concensus since it is a
freely available stable format that is easily editted and which can be
transformed in a variety of distribution formats.  Also, given the
distributed nature of the project, it is convenient for the documents
are "composable" in perl, e.g., allowing the function descriptions to be
pulled from the function files and pasted after the unifying description.
Feel free to continue to suggest other alternatives.

For the documentation we distribute we need to use a format that is
available to the user.  html and pdf are obvious candidates here, and I see
that most everyone will be able to view MathML with a bit of effort
(http://www.w3.org/Math/implementations.html).  Initially I'll use html
because it is easiest, but MathML seems like the direction we should go.

- Paul

On Tue, Mar 19, 2002 at 11:08:36AM +0100, Rafael Laboissiere wrote:
> * Paul Kienzle <pki...@ja...> [2002-03-18 10:28]:
> 
> > We need to settle on a document format, or maybe a small number of formats.
> > That way it will be easier to work together on documentation. Standard
> > layout of documentation in the directory would also be helpful so that the
> > build/install docs can work like install m-files.
> 
> DocBook-XML seems to be a natural choice, besides the fact that it has no
> native support for mathematical typesetting.  If/when MathML will work
> together with DocBook and have a good TeX backend, the DocBook format will
> be a strong candidate.  Sebastian Ratz' PassiveTeX looks promising, though I
> never used it (see http://www.hcu.ox.ac.uk/TEI/Software/passivetex/).  
> 
> At any rate, editing math directly in MathML seems quite tedious and
> verbose. However, I think that the present discussion has to do with choice
> of formats and not with the actual editing.
> 
> -- 
> Rafael
> 
> _______________________________________________
> Octave-dev mailing list
> Oct...@li...
> https://lists.sourceforge.net/lists/listinfo/octave-dev

Re: [OctDev] Re: Nonlinear optimization tutorial

[Rafael L. <lab...@mp...>]

* Paul Kienzle <pki...@ja...> [2002-03-18 10:28]:

> We need to settle on a document format, or maybe a small number of formats.
> That way it will be easier to work together on documentation. Standard
> layout of documentation in the directory would also be helpful so that the
> build/install docs can work like install m-files.

DocBook-XML seems to be a natural choice, besides the fact that it has no
native support for mathematical typesetting.  If/when MathML will work
together with DocBook and have a good TeX backend, the DocBook format will
be a strong candidate.  Sebastian Ratz' PassiveTeX looks promising, though I
never used it (see http://www.hcu.ox.ac.uk/TEI/Software/passivetex/).  

At any rate, editing math directly in MathML seems quite tedious and
verbose. However, I think that the present discussion has to do with choice
of formats and not with the actual editing.

-- 
Rafael

Re: [OctDev] Re: Nonlinear optimization tutorial

[Etienne G. <et...@is...>]

  Hello

On Mon, Mar 18, 2002 at 10:28:22AM -0500, Paul Kienzle wrote:
# Thanks!
#
# I would say stick with the name minimize.  If you also happen to give your
# minimization some constraint options, then minimize can choose a constraint
# algorithm.  If that is too awkward, then we can find a new name for the
# constrained version, such as mincon.
#
# Any opinions as to whether matlab's minimization function interface is
# acceptable?  My preference is to not introduce new interfaces unless they
# are clearly better.

  A friend sent me a recent help text on m*tlab minimization
functions. Here is what seemed salient to me. The relevant function is
called 'fminunc' :

  [x, best_val, exit_status, misc ] =

    fminunc (function, x0, option_struct, extra_arg1, extra_arg2,...)


'misc' contains whatever extra information should be returned : number
of function evaluations, number of algorithm iterations, test for
optimality of result.

  My guess is that 'exit_status' (a number which says whether the
method succeeded, or just the max number of iterations was reached) is
legacy from old the past. Something like the 'nev' (number of function
evaluations) returned by my optim functions.

  Now about the 'extra_arg1',... : functions taking multiple args can
be minimized, but only with respect to the first argument. We could
accept extra args like this, also, but currently, extra arguments are
accepted by passing a list in the second argument 'x0'. We could have
the best of both worlds if it weren't that the current minimize()
assumes trailing parameters are options.

  About the 'option_struct' : it contains all the options and is
returned by 'optimset("param", "value", ... )' . Some options already
exist in minimize(), under different names :

  'Display'       <-- more or less like --> 'verbose'
  'GradObj'       <-- more or less like --> 'dfunc'
  'Hessian'       <-- more or less like --> 'd2func'
  'DiffMinChange' <-- more or less like --> Step for num. diff

   MaxIter        \
   Tolfun         } Misc termination criteria, not all of which
   TolX           } I grok
   TolPCG         /

   HessMult       \ Misc tricks to make 2nd order algorithms cheaper.
   HessPattern    } I don't think these would be easy to implement.
   HessUpdate     / minimize() has 'd2inv' which allows to specify the
                    inverse of Hessian when it is easier to compute it
		    "by hand".
   etc ...

  In conclusion, it should be possible to do something like fminunc
and a little more : 

- Call the frontend 'fminunc', accept a struct instead of named
  options (+ accept to minimize other than 1st arg).

- Use same option names (caveat : not all opts will be there, not all
  will do the same thing), plus our own (ot: Ben's 'order' option
  could fit). I find m*tlab options verbose, though, maybe have some
  abbreviated ones too.

- Define an 'optimset' function that returns a struct from named
  options and eventually a previous option struct.


  Moreover, it still should be possible to define a function
minimize() which accepts named options (use 'fminunc' as a backend, or
vice-versa).

  The amount of work this all represents has increased, but it doesn't
seem insurmountable at all. What is the deadline again? We could start
by a rough but functionnal approximation and improve on it.

  Here are some other m*tlab goodies :

** Have one function compute the function value, derivative (if
nargout>=2) and hessian (if nargout>=3) : This reduces the # of
functions to write.

** Another interesting feature of m*tlab is the 'inline' function :
inline("norm(x)") which seemingly defines and returns the name of a
function like

  function v = noname_func (x), v = norm(x); endfunction,

unless it returns a 'function' object; who knows. I like the idea, I'm
not sure it is really useful, and it should be possible to do
something like this at little cost.


# We need to settle on a document format, or maybe a small number of
# formats.  That way it will be easier to work together on documentation.
# Standard layout of documentation in the directory would also be helpful so
# that the build/install docs can work like install m-files.
#
# Something tex based certainly seems to be in order since it makes the math
# easier to typeset.  I'm partial to latex myself.
#
# I don't know what to make of lyx.  While ascii based, I'm guessing that lyx
# would not be very happy if you make modifications directly on the file with
# a plain text editor, so everyone would have to use lyx.
#
# Anyone have experience with MathML?  Is there common browser support?
# Latex2html can be really ugly.  Is MathML something you could edit directly
# (like html), or is it only really usuable with a sophisticated editor.
#
# That Octave uses texinfo is a good argument for using texinfo ourselves.
# What I've seen from octave function headers, though, tells me I won't like
# it much.  I still am avoiding going through and fixing up all our function
# headers to use texinfo format ;-)
#
# Other suggestions?
#
# - Paul

  Together w/ Ben and Matthew's opinions, it seems that latex is the
favorite. Not a problem for me, I can import latex in lyx without too
much work.

  Cheers,

  Etienne

--
Etienne Grossmann ------ http://www.isr.ist.utl.pt/~etienne

Re: [OctDev] Specification for nonlinear optim. front-end

[Ben S. <bs...@la...>]

Hi Etienne,

This is great.  Thank you for writing it up.  I have a few comments.  

I think the "ndif" option should be replaced with an "order" option. 
-----------------------------------------------------------------------
order -> specify 0,1,2 and get the default method for that order.  

ndif -> If we add the order option this option is superfluous.  The logic for 
checking coherence of the arguments can take care of the case where a method 
is explicitly chosen and where an order is chosen.  

I suggest this mainly becuase it seems more intuitive to me.  What do you 
think?  

Comments on Order 1 methods
-----------------------------------------------------------------------
The interface for bfgs and dfp are not the same as cg_min.  I think that they 
should be changed to match.  I also happen to think that cg_min has a better 
intefrace than bfgs and dfp.   At the very least we need to make a way to 
pass variables through to the function being minimized which bfgs and dfp 
currently don't allow.   

You did not suggest a default for the order one methods.  I think bfgs should 
be the default.  When faced with multiple options for a problem we should 
choose the one that will probably be the fastest for most problems.  

Do we need/want to maintain dfp?  I wrote it becuase we used both in a class 
I was taking.   dfp and bfgs are essentially the same.  That is they try to 
construct the inverse hessian from gradients.  I am not sure it adds any 
thing except work. Here is a quote from  Linear and Nonlinear Programming by 
David Luenberger talking about the BFGS method.  "Numerical experiments have 
repeatedly indicated that [BFGS] performance is superior to that of the DFP 
formula, for this reason [BFGS] is now generally preferred."   My feeling is 
we should toss it unless someone has a reason to keep it.  

Shorthand option
-------------------------------------------------------
I had not thought of this.  I think it is a particularly nice feature that is 
not available for most analysis packages.  It is always a good idea to make 
things as transparent as possible.  


On Saturday 16 March 2002 10:02 am, Etienne Grossmann wrote:
>   Hello,
>
> here is a possible specification for a front-end to unconstrained
> nonlinear optimization functions. The current "optimize()" function
> does more or less this already, but only has the Nelder-Mead,
> conjugate gradient and Levenberg-Marquardt ("D2" below) algorithms.
>
>
> Synopsis of a front-end for optimization
> ----------------------------------------
>
>   [x_best,v_best,...] = minimize (func, start_point, ...)
>
>   start_point is the starting point for the iterative minimization
>               method.
>
>               If func takes more than one argument, start_point may be
>               a list. By default, func will be minimized with respect
>               to the first argument, but any other argument may be
>               specified with the "narg" option below.
>
> Implemented methods and their applicability
> -------------------------------------------
>
>   +--------------------+---+-------+-------+------+
>
>   |                    |   | Deriv |       |      |
>   |
>   | METHOD             |Dim| Order | Domain| Func |
>
>   +--------------------+---+-------+-------+------+
>
>   | Newton-Ralphson    | 1 |   2   |  all  |  C2  |
>   | Nelder-Mead        | N |   0   |  all  | cont |
>   | BFGS               | N |   1   |  all  |  C1  |
>   | Conjugate Gradient | N |   1   |  all  |  C1  |
>   | DFP                | N |   1   |  all  |  C1  |
>   | D2                 | N |   2   |  all  |  C2  |
>
>   +--------------------+---+-------+-------+------+
>
> Options indication 1st or second differential
> ---------------------------------------------
>
> "dfunc" dfuncname
>   => Use an algorithm that uses the differential.
>      Assumes the differential df can be calculated with
>
>        df = dfuncname (x)
>
> "d2func" dfuncname
>   => Use an algorithm that uses the 1st and 2nd differentials.
>      Assumes the function value f, differentials df and d2f can be
>      calculated with
>
>        [f,d2,d2f] = d2funcname (x)
>
> "ndif"
>   => Use numerical differentiation.
>
> Options indicating the algorithm
> --------------------------------
>
> newton_ralphson       (nr)
>   => Dim == 1
>
> nelder_mead           (nm)
>
> bfgs
>   => Need Dfunc
>
> cong_grad             (cg)
>   => Need Dfunc
>
> dfp
>   => Need Dfunc
>
> levenberg_marquardt   (lm)
>   => Need D2func
>
> -- Default :
>    If    Dfunc  is given : Method == bfgs, cg or dfp
>    Elsif D2func is given
>      If Dim == 1 : Method == nr
>      Else        : Method == lm
>
> Options controling termination
> ------------------------------
>
>   Option    Description                   Applicable methods
>   -----------------------------------------------------------
>   ftol h    Absolute function improvement (nm, dfp, bfgs, lm)
>   vtol h    Volume   of simplex	          (nm)
>   rtol h    Radius of simplex		  (nm)
>   dtol h    Amplitude of derivative	  (dfp, bfgs, lm)
>   xtol h    Amplitude of step		  (nm, dfp, bfgs, lm)
>
> Other options
> -------------
> narg n               Indicate which argument with respect to which
>                      func is optimized (when it takes multiple
>                      arguments).
>
> step h               Indicate the initial step size (not for method
>                      that uses 2nd diff)
>
> maxev n          Maximum number of function evaluations
>
> verbose          Show status during algorithm run
>
> shorthand        Do not perform the optimization, but return the name
>                  of the backend function and the options that are
>                  passed to it. The backend can then be called
>                  directly, with little overhead.
>
> Checks that should be done on the coherence of the input
> --------------------------------------------------------
>
> If Dfunc  is needed, but not specified : do numerical differentiation
>
> If D2func is needed, but not specified :
>
>   If Dim == 1 : do numerical differentiation
>   Else        : error (not yet implemented)
>
> If Dim == 1 but size Xstart != 1 : error
>
> If termination criterion is used w/ inappropriate method : error
>
> If Dfunc or  D2func are specified but not required by method : warn
>
> If both Dfunc and D2func are specified : warn

-- 
Ben Sapp                         Los Alamos National Laboratory
email: <mailto:bs...@la...>   Phone: (505)667-3277
Fax:   (505)665-7920             URL:   http://www.neutrino.lanl.gov/
--