August 2014 - cctbxbb - phenix-online.org

Re: [cctbxbb] Sphinx docs for CCTBX
by Nigel Moriarty 20 Aug '14

20 Aug '14

These links don't work for me. On Mon, Aug 18, 2014 at 3:16 PM, Ian Rees <irees(a)lbl.gov> wrote: > I'm using a separate build configuration for the docs. You can view > the nightly results here: > > http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64 > > If you click the first build, you can view the log files for each > step, and view the Sphinx log file by clicking "docs:cctbx stdio", > e.g. > > > http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64/builds/6/steps/… > > I'm working through the warnings now. Mostly missing references and > import errors. > > Ian > > On Fri, Aug 15, 2014 at 8:37 AM, Nathaniel Echols <nechols(a)lbl.gov> wrote: > > On Fri, Aug 15, 2014 at 8:06 AM, Richard Gildea <rgildea(a)gmail.com> > wrote: > >> > >> I had a go at starting to document cctbx.uctbx.unit_cell, which as you > >> know is mainly a Boost.Python extension > >> (https://sourceforge.net/p/cctbx/code/20467/). Before I travel too much > >> further down this route, is this an appropriate way of documenting > >> Boost.Python extensions or is there a better way we can do this? > > > > > > I haven't had enough time to experiment to decide on the best approach. > I > > see three choices - the first is what you've done: > > > > class my_class (ext.my_class) : > > """doc""" > > > > def boosted_function (self, some_argument) : > > """function doc""" > > super(ext.my_class, self).boosted_function(some_argument) > > > > OR (2): > > > > ext.my_class.__doc__ = """doc""" > > ext.my_class.boosted_function.__func__.__doc__ = """function doc""" > > > > OR (3): > > > > put the docstrings in C++ code, for instance: > > > > .def("boosted_function", &my_class::boosted_function, "function doc") > > > > (not sure what the equivalent is for classes but it's probably pretty > > similar) > > > > My opinion is that (1) is much too prone to confusion and API conflicts > > unless we're already using this code structure (and FYI, you broke the > call > > signatures for a couple of methods). (3) is just gross. (2) is also > gross > > but has the virtue of being the least likely to break, and doesn't > require > > modifying C++ files. So I'm inclined to take that approach > > > > (For what it's worth, when modifying a class using the boost.python > > injector, we appear to be able to set __doc__ inside there; see > > iotbx.pdb.hierarchy for an example.) > > > >> It would be good to get the documentation for the core cctbx classes up > >> and running, however several of the core classes (e.g. > >> cctbx.sgtbx.space_group, cctbx.uctbx.unit_cell, flex arrays) are mostly > >> Boost.Python extensions, so it would be good to arrive at a sensible > way to > >> document these extensions. > > > > > > Agreed. I think for flex arrays we will be stuck writing the docstrings > in > > C++ - however since these are relatively stable APIs it should be > reasonably > > straightforward. > > > > -Nat > -- Nigel W. Moriarty Building 64R0246B, Physical Biosciences Division Lawrence Berkeley National Laboratory Berkeley, CA 94720-8235 Phone : 510-486-5709 Email : NWMoriarty(a)LBL.gov Fax : 510-486-5909 Web : CCI.LBL.gov

2 1

real-space symmetry operators
by Nathaniel Echols 18 Aug '14

18 Aug '14

Hi all-- I'm trying to figure out how to orthogonalize symmetry operators given a unit cell, which doesn't seem to be something we have code for. These appear in PDB files in the REMARK 290 section but I haven't been able to find any other software that generates them, and the relationship between the symops and the real-space equivalents is unclear. I assume this is conceptually similar to orthogonalizing fractional coordinates, but unit_cell.orthogonalize() does not quite do what I wanted. In the PDB, for P63 it has this (excerpted): REMARK 290 2555 -Y,X-Y,Z ... REMARK 290 SMTRY1 2 -0.500000 -0.866025 0.000000 0.00000 REMARK 290 SMTRY2 2 0.866025 -0.500000 0.000000 0.00000 REMARK 290 SMTRY3 2 0.000000 0.000000 1.000000 0.00000 which looks like it should be relatively straightforward, but I'm not very good with matrices. Does anyone know the correct math for this? The corresponding rt_mx object from sgtbx looks like this: r=(0.0, -1.0, 0.0, 1.0, -1.0, 0.0, 0.0, 0.0, 1.0) t=(0.0, 0.0, 0.0) (Yes, I realize that there are much easier ways to apply symmetry operators to coordinates, but I want to limit the number of matrix multiplications involved when starting from Cartesian coordinates.) thanks, Nat

3 3

Sphinx docs for CCTBX
by Nathaniel Echols 15 Aug '14

15 Aug '14

Thanks to some superb work by Nader Morshed, Oliver Zeldin, and Ian Rees, we now have automatically updated Sphinx docs for CCTBX: http://cci.lbl.gov/cctbx_docs/ Obviously these are still pretty sparse - right now most of the formal documentation is clustered here: libtbx libtbx.utils libtbx.phil (mostly re-using Ralf's old documentation) cctbx.miller iotbx.pdb (built on Ralf's newsletter article) mmtbx.command_line These are a combination of inline docstrings and separate restructured text files in cctbx_project/sphinx. We have automatically generated rst files for some modules, but others will need to be added manually. In the end I think we'll want to curate every file, but the current layout will get us started. To facilitate additional contributions, I've modifed the installation script for base packages to include a --sphinx option. After setting up CCTBX you can then do this: cd $BUILD libtbx.configure sphinx cd $SRC/cctbx_project/sphinx make html and you will get the full documentation built locally. I am still figuring out how to use Sphinx effectively; it is definitely possible to document Boost.Python extensions but it's not quite as obvious. I don't expect us to retroactively document several hundred thousand lines of code written over a decade, but if we can get the core parts thoroughly covered that will greatly reduce the barrier for new developers. Suggestions for particular modules to focus on are appreciated; I am going to try to cover the basic PDB+reflection file functionality. I encourage anyone doing CCTBX-related development to contribute as you go. (They don't need to be your own APIs, just modules you're reasonably familiar with.) Those of you who already have a ton of undocumented code can expect me to harass you periodically about fixing this. (Note that I've cannibalized at least one newsletter article for this, and continue to do so; we should re-use existing prose descriptions as much as possible without violating copyrights.) -Nat

4 5