[boost] Quan was [PQS] Roadmap

From: Andy Little (andy_at_[hidden])
Date: 2006-07-17 11:45:37

Hi,

    Since I ultimately intend to resubmit Quan to boost and in light of the
recent PQS review, I hope that this message isnt O.T.
    Note also the Quan mailing list. ( I guess it would be wise to take any
followups off the boost developers list)

*** Quan Draft Roadmap ***

Please note that the views expressed here are my personal views (and possibly
ramblings) on the direction that Quan should take. They arent set in stone, so
please feel free to argue any points and suggest other directions that the
library should take. Also please feel free to add anything else.

I have set up a Quan mailing list at quan-matters_at_lists.sourceforge.net. I hope
that can be the main vehicle for discussion related to Quan. You can subscribe
at:

https://lists.sourceforge.net/lists/listinfo/quan-matters

Alternatively you can mail me at

andy attt servocomm dottt freeserve dottt co dottt uk
(Please put something obviously not spamlike as the subject line!)

Unfortunately the Quan roadmap isnt as detailed or finished as I would like ,
but I thought it better to get it out in its current state that not at all.

**Personal Philosophy for Quan**

Quan is designed simply to make the programmers life easier.  The
quan::fixed_quantity, available in the Alpha quan release available at:

http://sourceforge.net/project/showfiles.php?group_id=170593

 is intended to be an example of that philosopy. IMO it wraps up some
complicated functionality in a simple entity.

The latest state of fixed_quantity is also available via CVS at:

http://quan.cvs.sourceforge.net/quan/
(my latest code and docs is currently in the concept_08_July_2006-branch.)

The Quan library firstly needs good documentation. Unfortunately good
documentation is extremely hard and time consuming to write, but it has to be
done for a public library.

I hope that the Quan library will be useful for advanced uses, but at the same
time I want a library that is designed for use by mere mortals like me too. It
may be difficult to reconcile simplicity with advanced Maths, but nevertheless
that should be one of Quan's goals.

The library also needs to be correct, so alongside documentation there need to
be a comprehensive set of Unit tests for any functionality.

The library is intended one day to become part of the Boost distro
http://www.boost.org, therefore the code, documentation and tests should be
written with boost compatibility in mind.

****The Quan project status****

The Quan project uses the boost license:

http://www.boost.org/more/license_info.html

Quan is dependent on the latest version of the  Boost distro
http://www.boost.org, which can be downloaded here:

http://sourceforge.net/project/showfiles.php?group_id=7586

Quan is currently using the CVS version control system. A useful page about
using CVS is available here:

http://cvsbook.red-bean.com/cvsbook.html

If you are interested in working on the Quan project then a reasonable knowledge
of CVS will be necessary. The best way to learn the system is to set up a local
database and practise on that.
(It might also be a good idea to download the Quan code and try it out, to see
if you like it!)

If boost moves to SVN then Quan will follow after watching their progress, but
meanwhile Quan should stay in step with Boost IMO.

** Full functionality **

Quan will need a lot of associated functionality to be useful in real world
projects. This to me means it needs firstly vectors and point vectors, and
secondly some  way to transform them in 2D and 3D. the discussion during the
review of PQS on the boost developers list should be a source of inspiration.
Maybe 3rd party libraaies can be used, but I havent found them yet and I reckon
they will need to be written for Quan. There is an obvious dependence of such
functionality on the Concepts of what a Quantity is, so work on the Quan
Concepts documentation needs to be considered high priority.

****Quan parts needing immediate attention ****

*** quan::fixed_quantity aka pqs::t1_quantity ***

Its probably time to stop changing the interface of fixed_quantity for trivial
reasons, so fixed_quantity should basically stay as it is unless major issues
are found. I believe that the fixed_quantity interface (ie quan::length::mm) is
quite stable in overview and has been for some time in its previous incarnation
pqs. I have been doing some work on Concepts, docs and improving the low level
scaling /unit conversion code, which are currently in CVS on
concept_08_July_2006-branch (merged to main trunk today 17/July/2006) .

***The Quan units database***

I have a local database and associated application used for generating the Quan
headers and units html. Ideally the database would be on the Sourceforge
database system and CGI scripts used to generate headers remotely and possibly
add (after human vetting) quantities to the database. My local database
application was only designed to generate headers on my own system. Ideally it
would be rewritten using maybe DTL http://dtemplatelib.sourceforge.net/ or SOCI
http://soci.sourceforge.net/ library. DTL says it provides cross-platform access
including Access2000 (my local database) and MySQL (sourceforge database)),
which would suit me but, whatever way its achieved, the database should be
upgraded and moved into MySQL on Sourceforge. Needs investigating. If anyone is
interested I will put the source for my local acccess in the Quan CVS. It is
however raw source for Windows without any docs.

Once up on Sourceforge the database needs to be filled with quantities and units
(and constants). Then it can go about its business of generating headers and
documentation.

There is also work on a Units database and XML schema by NIST
http://unitsml.nist.gov/ The idea of being able to communicate physical
quantities across applications is intended to be embodied in UnitsML. This
should be taken into consideration in design of the database. The philosophy of
UnitsML looks very close to Quan , so compatibility with UnitsML should be
mandatory. I think it is also worth getting in touch with the authors of UnitsML
and UnitsDB soon too to let them know about the Quan project as a potential
application.

*** Unit tests **

The unit tests are improving, but still need work. Firstly to be more
comprehensive. Some are still just empty functions waiting to be filled in.
Another issue is portability. For example in using various Quan default real
types, where double is often hard coded, and second in mirroring the exact
expression used in the implementation calculation, in the comparison test
calculation. The detailed semantics of the fixed_quantity need sorting out so
that it should be as predictable as possible. Floating point control and
predictability is an important goal and the current release is slightly loose in
this respect.

It would be nice to take advantage of the Sourceforge compile farm for unit
tests.

*** Addition of the multiunit_quantity and the uni_quantity to the library***

(Alternative Name suggestions please :-) )

Work on the other 2 quantity types needs to be started.

**For the multiunit_quantity**

The one that can change its units at runtime.
Uses of the multiunit_quantity are intended to be for User I/O Dialog Boxes (or
Widgets) and the like. The multiunit_quantity should play well with the
fixed-quantity of course.

I have a prototype at
http://www.servocomm.freeserve.co.uk/Cpp/pqs-2-00-02/pqs-2-00-02.zip which I was
reasonably happy with and if I write it that will be the approach I will take.
 Again in http://www.servocomm.freeserve.co.uk/Cpp/pqs-2-00-02/pqs-2-00-02.zip
there are some examples of this type of use.

Working on multiunit_quantity may be tricky until the fixed_quantity
implementaion and low level code is more stable however as (at least how I did
it) it made much use of the fixed-quantity unit conversion code.

**For the uni_quantity**

The one that can change its dimension and units at runtime
Potential uses for this type are in testing inside matrices, where the type can
be switched in for Dimensional Analysis checking and anywhere that a quantity
must be created at runtime, maybe for reading from XML or a database for
example.

I did a quick prototype for a uni_quantity, . The main problem is the size in
the obvious implementation. IIRC it used around 60 bytes of memory per object.
Maybe that is acceptable, maybe not. An alternative approach might be providing
a handle to a hash map of dimensions and units. Anyway this needs to be
investigated.

***Quan space***

After the discussions of PQS on Boost the vect <quan/three_d/vect.hpp> needs to
be rewritten to cater for 2D 3D etc e.g vect<N,T>. The rationale is to write
code that can be used in N dimensional space. I am very keen to get 2D and 3D
entities in Quan. Including vectors, homogeneous transform matrices and
quaternions. The classic use case for me is representing the airflow around a
wind turbine.

There are have been various suggestions that third party libraries can be used,
but I dont see the libraries and I think Quan will have to provide its own at
least to show it can be done.

*** Complex quantities***

Again in http://www.servocomm.freeserve.co.uk/Cpp/pqs-2-00-02/pqs-2-00-02.zip
there is code for a complex quantity. This needs to be ported to Quan. The
issues of infinities caused problems in the previous version IIRC, so this needs
to be addressed. (Partly my poor maths to blame there) and (as with everything
else) a tight spec written, maybe even trying to sort out some of the problems
that exist in std::complex, though I dont quite understand what those are. Maybe
should be coupled to Quaternions in 3D too...

***Performance testing***

I have done some some very limited performance tests consisting basically of
running the <quan_matters/examples/particle.cpp> in VC8 both using
quan::fixed_quantities and doubles and comparing the assembler output. It
appears that the quan::fixed-quantity version has a couple of extra instructions
(mainly when dealing with constants), though the code overall is otherwise
nearly identical. Performance tests need to be done on other compilers too of
course. The whole area of performance versus inbuilt types needs to be started
and documented using as many compilers as possible.

*** Checking of calculations for integer overflow, inf etc. ***

Because Quan fixed_quantity encapsulates an inbuilt type, it would be a good
idea to enable the library also to perform optional runtime checks that
calculations arent overflowing or dividing by zero etc. This would make Quan
into a more comprehensive suite of error checking capabilities.

*** Visualisation ***

Visualisation is the IMO the best way to show off Quan library. Maybe a port of
yade http://yade.berlios.de/. Anyway Quan needs some sort of 3D/GUI application
to show it off.
Other useful items are GUI Unit widgets for users to be able to set their own
units and so on.
Care needs to be taken over licencing issues.

*** Stability, Modularity ***

At some point When the version changes to Non_zero_x_x, whatever mistakes have
been made in the interface spec should be considered embedded, so that the code
base for any users is stable. Before that consider the code Alpha only. This
will probably mean releasing Quan in modules at least once anything gets into a
finished state. IOW fixed_quantity module etc.

**What platforms should Quan run on**

Wherever possible, the library should be designed to allow for (say) the
possibility that an int is 16 bits and so on. I don't think it costs much to do
so.

**Can Quan be used on large systems?***

The kind of problems Quan is designed to solve get worse in large systems. Again
only theoretically currently, but the idea is that it will work well because of
the error checking and code documentation features. However quite what happens
in large matrices, higher level maths and so on, and so on I don't know and
support for these features needs to be written.  I think this is an unanswered
research question frankly and should be approached with an open mind. It may
transpire that such use is impractical. If that turns into a proof that inbuilt
types work better then so be it.

***High Performance systems **

Often there is a high performance requirement. For example Geoffrey Irvings work
http://graphics.stanford.edu/~irving/ and uJanek Kozickis work
http://yade.berlios.de/. Unfortunately Quan is in a no win situation here. It is
never going to beat inbuilt types, but there is an underlying requirement that
Quan needs to be as good as it possibly can. Even in high performance systems
the error checking ability and (hopefully) increased productivity from that may
outweigh the cost (if any) in performance. Work also needs to be done on working
out how Quan can be switched in for testing and switched out for release too.
Work also needs to be done on Quans performance versus inbuilt types with test,
results and documentation.

*** Documentation Format ***

Currently the docs use QuickBook. Other html documentation can be linked in, but
Quickbook can produce pdf format and things get sticky if relative links are
used. Ideally docs will be in QuickBook but other html formats can be used I
guess.
It may be desirable to write any Units and contant html into the Quickbook
document in Quickbook format (or as XML). (Currently I am using Quickbook 1.1
which is monolithic, but in the boost_1.34.0 distro this should change).

** Website **
Currently the website consists just of the fixed_quantity docs. It should
probably provide more general information about the project.

If there is any part of the project that you are interested in helping with then
please get in touch. If you have any points you would like to make, please feel
fee to get in touch with me personally or post to the quan-matters mailing 
list.,

regards
Andy Little