Additional python documentation, possible examples?

[tmcclintock]

As a new user of CLASS mostly interested in the python module, I found the amount of documentation on the wiki page lacking. I was able to find answers to the particular questions I had by looking at the dropbox folder from the IPMU lectures.

Now that I am somewhat more familiar with running the python module, I'd like to contribute to the project by writing up some simple examples. Would this be of use, or should I not bother? Thank you.

[miguelzuma]

It would be good to have more documentation, as well as a collection of both pedagogical examples of classy, as well as a more advanced collection that people could use. A couple ideas:

@ThomasTram has a github public repository with examples of CLASS using python:

https://github.com/ThomasTram/iCLASS

Also @ardok-m and I have been working in another repository to handle work with CLASS using python:

https://github.com/miguelzuma/work-in-class

[tmcclintock]

Sounds good. Would you prefer these examples as stand-alone .py files or longer notebooks?

[rainwoodman]

As a new user of Class via the Python interface I found the interface slightly awkward to work with.

• There are quite a few memory holes; ufunc /broadcasting with numpy is non-exist.
• Although CLASS has tried very hard to be modular but the python binding is monolithic -- every module provided in the same namespace;
• Special interfaces for MontePython are mixed into the main module;

I wonder if there is plan for a revision of the Python interface to address some of these technical and design issues, an how practical it is to introduce a major API breakage.

[lesgourg]

Hi Yu, yes, I fully agree with you! Indeed there is an old plan to rewrite the wrapper completely. There is just a matter of time missing; but I am more and more motivated to do it, and any help would then be welcome - I should also recontact Tom McClintock who offered to help. The basic plan is the following: we want to write a python script that will parse the CLASS .h files, and that will automatically scythonize all the variables contained in the main structures, and all the functions considered as "external" (first few functions of each module). This is not unrealistic, especially since we can add a few //comments in the .h files that would be designed to guide this parser. Then the wrapper user could really do anything with the code and the modularity would be fully preserved. On top of that, we should leave (and improve when necessary) the currently existing functions, which have been written more for MontePython use than for general use.

[tmcclintock]

Hey again. @lesgourg I would be happy to help work on the wrapper, but at the moment I am very wrapped up (pun intended) in getting some papers out for my degree. I am not sure when I will be available to write some real code for CLASS. I am still totally up for working on documentation for everything as it exists now.

As it stands, I have been writing how-to guides for the other grad students in my group. Here is an example of one of the notebooks I have made. I take a lot of time writing descriptive comments in the markdown cells. If this type of notebook seems useful to you I can make plenty more. One question I have is where I should do the work. Should I work on my own fork of Class and issue a PR? Should I just work in a different repository that you can link to independently? Let me know and I can get started right away!

@rainwoodman I think that one reason the interface seems monolithic is how the output fields must be specified in the same dictionary that sets the cosmology. A really good place to start in terms of documentation is getting all the important information in explanatory.ini and putting it into notebooks, especially the parts the specify how to structure the dictionary used in Class.set().

[rainwoodman]

@tmcclintock Notebooks are definitely useful documentations. It would be even better if API is self clarifying and naming-consistency with other mainstream packages (e.g. astropy.cosmology). Online help in the form of docstrings is also particularly useful for someone to quickly poke around.

@lesgourg There are probably two use cases:

1. Using class as is, to extract the transfer function etc for other applications (e.g. nbody simulations)

2. Adding your own model to class and run it.

The first case doesn't really need a C parser / scanner; everything can be hard coded and synchnized with the latest class release.

The second case does seem to prefer a source code parser; but on the other hand, if one is sufficiently equiped to modify class, the barrier to add the interface to the python binding manually is probably not that high neither.

My main concern with a source code scanner is to properly extract the docstring and converting the conventions - if we are to use astropy.cosmology names, then a glue layer is always needed, and it seems to be easier to directly implement the logic than to expressing it as rules.

We also want to make sure that setup.py. entrypoint of the python binding installation shall be setup.py, not a makefile. This would pave the way to all one key install pip install classy and shipping of binary packages (mostly concerning case 1).