Difference between revisions of "User:Josiah425:TISEAN Package"

From Octave
Jump to navigation Jump to search
 
(25 intermediate revisions by the same user not shown)
Line 1: Line 1:
  
 
= TISEAN Package Porting Project  =
 
= TISEAN Package Porting Project  =
== Elaborated proposal ==
+
== Goal of the project ==
Porting of the TISEAN package has a couple parts. First part is making the fortran and c programs accessible to Octave. Second part would be creating makefiles and putting all that code in a neat package.  
+
The goal of this project is not to port the entire TISEAN package to octave. That would be a desired outcome though it might not be feasible within the time constraints. The goal of this project is to give the TISEAN package a solid start and to port as many functions as possible to create a solid foundation for the future.
I have divided the first part into three subparts:  
+
 
# fortran ones that can be re-implemented easily in m-files (a good example of such a program is 'henon')
+
== General division ==
# the fortran ones that need to be linked to oct files
+
As the TISEAN package consists of 74 programs I have divided the first part into three sub-parts:  
# c programs which also need to be linked to oct files.
+
# FORTRAN ones that can be re-implemented easily in m-files (a good example of such a program is 'henon') -- there are 5 programs in this class
As linking fortran code to oct code is most diffucult of those three tasks I assume in my estimates that it will take me around 3 hours for each program, there are 28 in this category. Thus I assume it will take me about 2-3 to complete this task.  
+
# C programs which also need to be linked to oct files (an example is 'ghkss') -- there are 41 programs in this class
Next there are the programs in the Tisean which can be ported to m-files easily. As this is not as difficult a task as porting fortran code to oct files I have alloted 2 hr for each program. I have put 5 programs in this category thus it should only take me about 2 days to complete this task
+
# FORTRAN ones that need to be linked to oct files (an example of such a program is 'project') -- there are 28 programs in this class
Last but not least, I have 41 programs in C that need to ported to Oct files. As this task seems fairly straightforward I have allotted 2 for each program. There are 41 programs in this category, therefore this task should also take me 2-3 weeks.  
+
They are ordered so that according to my estimates the difficulty rises with the number. This is because typecasting and implicit typing (which is included in most of the FORTRAN files in the TISEAN library) can be problematic sometimes.
I plan to allot another 2 weeks for cleaning the code up thus bringing it to a grand total of about 7 weeks.  
+
 
My plan is to tackle the hardest task first, that is to work on the fortran programs that need to be linked to oct files.  
+
This number can be brought down significantly. This is because some programs are deprecated, others are just C/FORTRAN copies of each other, others are not important in GNU Octave (such as 'compare' and choose'). After taking the factors above into consideration the number of functions that need to be ported drops to 49. I have prepared a detailed discussion of all of those functions [[User:Josiah425:TISEAN_Package:Table_of_functions| here]]. This number will further drop once certain programs are confirmed to have similar programs in GNU Octave or some packages in Octave Forge.
There are 9 weeks designated for GSoC so I hope the extra room will allow me easily finish on time.
+
 
 +
Apart from the qualitative division I propose a work oriented division. In it each subpart can be tackled separately and create an entity in-and-of-itself. I chose to work along the lines of the articles about implementations of nonlinear timeseries included in the documentation. This article discusses various algorithms and what certain programs mean. It can be found [http://www.mpipks-dresden.mpg.de/~tisean/Tisean_3.0.1/docs/chaospaper/TiseanHTML.html here]. I will discuss in which order I would like to port various topics from this article and where my work currently stands.
 +
==== Nonlinear noise reduction ====
 +
This is the first topic I chose. It is because it contains programs from all three categories. It is also relatively small -- it contains 3 programs: project, lazy, ghkss. I have chosen to further implement addnoise and henon, to demonstrate how project and ghkss work. Thus this topic contains programs from each category:
 +
* Re-implementable in mfile (henon)
 +
* Linkable to FORTRAN (project, addnoise, lazy)
 +
* Linkable to c (ghkss)
 +
I have already started working on this stage. My progress can be viewed at [https://bitbucket.org/josiah425/tisean https://bitbucket.org/josiah425/tisean]. So far I have implemented addnoise, project and re-implemented henon as an mfile. As most work on this topic has been completed I estimate that finishing it up will take around 2 days -- throughout my outline I estimate about 1 day per program (that includes documentation and testing).
 +
 
 +
==== Phase space representation ====
 +
This is the next topic that needs to be implemented. This is because it contains programs (especially 'delay') that are used to visualize data. Whenever an example is given in the package the resulting data is routed through 'delay' before it is plotted. Apart from delay it also contains other functions that can divided into the following categories:
 +
* Linkable to c (delay, corr, mutual, false_nearest, pca)
 +
There are two more programs in this section of the article they are: 'autocorr' and 'pc', both implemented in FORTRAN. There is no need to port them as according to the documentation ([http://www.mpipks-dresden.mpg.de/~tisean/Tisean_3.0.1/docs/contents.html here]) they are redundant with other functions. Further more, it is likely 'corr' does not need to be implemented, because 'xcorr' in signal package seems to have similar functionality. This has not been confirmed yet, once that occurs, a definite answer can be given.
 +
Assuming around a day for each function (with testing and documenting the usage) I assume this stage will take a little under a week.
 +
==== Nonlinear prediction ====
 +
This seems like a reasonable next step. It consists of the following programs:
 +
* Linkable to FORTRAN (predict, upo)
 +
* Linkable to C (lzo-test, lzo-gm, lzo-run, lfo-ar, lfo-gm, lfo-run, rbf, polynom, xzero)
 +
Again assuming around a day for each program (with testing, documenting usage and writing examples) I assume this stage will take about two weeks.
 +
==== Lyapunov exponents ====
 +
This stage will include:
 +
* Linkable to C (lyap_r, lyap_k, lyap_spec)
 +
It will take about 2-3 days to complete.
 +
==== Dimensions and entropies ====
 +
This topic is next on the list. Programs it include are as follows:
 +
* Linkable to FORTRAN (c2, c2t, c2d, c2g, c1)
 +
* Linkable to C (d2, boxcount)
 +
This part of the article also mentions 'c2naive' which is implemented in FORTRAN, but it is also described as redundant by the documentation ([http://www.mpipks-dresden.mpg.de/~tisean/Tisean_3.0.1/docs/contents.html here])
 +
This stage should take little over a week. I expect this stage and the previous one to take about two weeks.
 +
==== Testing for nonlinearity ====
 +
This is the last topic I intend to tackle. The following programs are included here:
 +
* Linkable to FORTAN (surrogates, randomize , timerev)
 +
This stage should take me about 3 days to complete.
 +
==== Tutorial ====
 +
I also plan to port all of the functions needed for the four exercises described in the 'Tutorial' section of the documentation. The programs that need to be ported additionally are as follows:
 +
* Linkable to FORTRAN (stp)
 +
* Linkable to C (ar-model, d2, poincare, recurr, nstat_z)
 +
The programs: 'spectrum', 'historgram', 'extrema', 'corr' need to have a confirmed equivalent function in GNU Octave.
 +
This stage should take me about a week.
 +
=== Notes on time estimates ===
 +
Totaling up the above estimates it should take me 6-7 weeks to complete my task as outlined above.  
 +
 
 +
My estimates might be high, but I believe it is more important to complete the task thoroughly than to port more programs haphazardly.
 +
 
 +
== Details of work on each program ==
 +
* FORTRAN linking
 +
For each FORTRAN program that I intend to link to a oct-file I intend to:
 +
# Strip the program of its input validation and transform it into a subroutine
 +
# Create a .cc program (compiled into an oct-file) that will launch the stripped FORTRAN subroutine; this .cc program will also not contain input validation, it will be for internal use only
 +
# Create a m-file that will perform input validation and launch the .cc and contain usage documentation
 +
* C linking
 +
I intend to do here something similar to the FORTRAN programs, although, it might be better to not create any extra m-files and incorporate the program's existing input validation into the .cc file. This might be a desired course of action. I will make a decision once I complete one such linking program.
 +
* Reimplementing in mfile
 +
This is quite straightforward, although it is important not to make a mistake while taking this approach.

Latest revision as of 17:58, 10 April 2015

TISEAN Package Porting Project[edit]

Goal of the project[edit]

The goal of this project is not to port the entire TISEAN package to octave. That would be a desired outcome though it might not be feasible within the time constraints. The goal of this project is to give the TISEAN package a solid start and to port as many functions as possible to create a solid foundation for the future.

General division[edit]

As the TISEAN package consists of 74 programs I have divided the first part into three sub-parts:

  1. FORTRAN ones that can be re-implemented easily in m-files (a good example of such a program is 'henon') -- there are 5 programs in this class
  2. C programs which also need to be linked to oct files (an example is 'ghkss') -- there are 41 programs in this class
  3. FORTRAN ones that need to be linked to oct files (an example of such a program is 'project') -- there are 28 programs in this class

They are ordered so that according to my estimates the difficulty rises with the number. This is because typecasting and implicit typing (which is included in most of the FORTRAN files in the TISEAN library) can be problematic sometimes.

This number can be brought down significantly. This is because some programs are deprecated, others are just C/FORTRAN copies of each other, others are not important in GNU Octave (such as 'compare' and choose'). After taking the factors above into consideration the number of functions that need to be ported drops to 49. I have prepared a detailed discussion of all of those functions here. This number will further drop once certain programs are confirmed to have similar programs in GNU Octave or some packages in Octave Forge.

Apart from the qualitative division I propose a work oriented division. In it each subpart can be tackled separately and create an entity in-and-of-itself. I chose to work along the lines of the articles about implementations of nonlinear timeseries included in the documentation. This article discusses various algorithms and what certain programs mean. It can be found here. I will discuss in which order I would like to port various topics from this article and where my work currently stands.

Nonlinear noise reduction[edit]

This is the first topic I chose. It is because it contains programs from all three categories. It is also relatively small -- it contains 3 programs: project, lazy, ghkss. I have chosen to further implement addnoise and henon, to demonstrate how project and ghkss work. Thus this topic contains programs from each category:

  • Re-implementable in mfile (henon)
  • Linkable to FORTRAN (project, addnoise, lazy)
  • Linkable to c (ghkss)

I have already started working on this stage. My progress can be viewed at https://bitbucket.org/josiah425/tisean. So far I have implemented addnoise, project and re-implemented henon as an mfile. As most work on this topic has been completed I estimate that finishing it up will take around 2 days -- throughout my outline I estimate about 1 day per program (that includes documentation and testing).

Phase space representation[edit]

This is the next topic that needs to be implemented. This is because it contains programs (especially 'delay') that are used to visualize data. Whenever an example is given in the package the resulting data is routed through 'delay' before it is plotted. Apart from delay it also contains other functions that can divided into the following categories:

  • Linkable to c (delay, corr, mutual, false_nearest, pca)

There are two more programs in this section of the article they are: 'autocorr' and 'pc', both implemented in FORTRAN. There is no need to port them as according to the documentation (here) they are redundant with other functions. Further more, it is likely 'corr' does not need to be implemented, because 'xcorr' in signal package seems to have similar functionality. This has not been confirmed yet, once that occurs, a definite answer can be given. Assuming around a day for each function (with testing and documenting the usage) I assume this stage will take a little under a week.

Nonlinear prediction[edit]

This seems like a reasonable next step. It consists of the following programs:

  • Linkable to FORTRAN (predict, upo)
  • Linkable to C (lzo-test, lzo-gm, lzo-run, lfo-ar, lfo-gm, lfo-run, rbf, polynom, xzero)

Again assuming around a day for each program (with testing, documenting usage and writing examples) I assume this stage will take about two weeks.

Lyapunov exponents[edit]

This stage will include:

  • Linkable to C (lyap_r, lyap_k, lyap_spec)

It will take about 2-3 days to complete.

Dimensions and entropies[edit]

This topic is next on the list. Programs it include are as follows:

  • Linkable to FORTRAN (c2, c2t, c2d, c2g, c1)
  • Linkable to C (d2, boxcount)

This part of the article also mentions 'c2naive' which is implemented in FORTRAN, but it is also described as redundant by the documentation (here) This stage should take little over a week. I expect this stage and the previous one to take about two weeks.

Testing for nonlinearity[edit]

This is the last topic I intend to tackle. The following programs are included here:

  • Linkable to FORTAN (surrogates, randomize , timerev)

This stage should take me about 3 days to complete.

Tutorial[edit]

I also plan to port all of the functions needed for the four exercises described in the 'Tutorial' section of the documentation. The programs that need to be ported additionally are as follows:

  • Linkable to FORTRAN (stp)
  • Linkable to C (ar-model, d2, poincare, recurr, nstat_z)

The programs: 'spectrum', 'historgram', 'extrema', 'corr' need to have a confirmed equivalent function in GNU Octave. This stage should take me about a week.

Notes on time estimates[edit]

Totaling up the above estimates it should take me 6-7 weeks to complete my task as outlined above.

My estimates might be high, but I believe it is more important to complete the task thoroughly than to port more programs haphazardly.

Details of work on each program[edit]

  • FORTRAN linking

For each FORTRAN program that I intend to link to a oct-file I intend to:

  1. Strip the program of its input validation and transform it into a subroutine
  2. Create a .cc program (compiled into an oct-file) that will launch the stripped FORTRAN subroutine; this .cc program will also not contain input validation, it will be for internal use only
  3. Create a m-file that will perform input validation and launch the .cc and contain usage documentation
  • C linking

I intend to do here something similar to the FORTRAN programs, although, it might be better to not create any extra m-files and incorporate the program's existing input validation into the .cc file. This might be a desired course of action. I will make a decision once I complete one such linking program.

  • Reimplementing in mfile

This is quite straightforward, although it is important not to make a mistake while taking this approach.