pyne/pyne — pull request #42 by fitze (2012-07-31 13:29:38+00:00)
Title: The beginning of the mcnp.Inp class

I have forked the pyne repo and have pushed my mcnp.Inp to my fork (fitze/pyne/staging); these changes are now in this pull request. I do not expect the work to be incorporated just yet; I am more interested in starting a discussion about what we want mcnp.Inp to look like.

At this point it is necessary to obtain feedback about if what I've done is
something we want. I really look forward to your feedback.

*********************
Current functionality
*********************
Earlier this year, I developed a simple OO python interface to MCNPX that
served only my needs for a class I was taking. However, it can be generalized
to cover all (most?) of the functionality of MCPNX. Under Anthony Scopatz'
suggestion I have cleaned up the code, put in docstrings for most methods (the
API is below), have made an example of its usage. The place to
look for information on this class is:

1. The source files pyne/mcnp.py, pyne/mcnpcard.py.
2. The example of its usage, in pyne/examples.py, for a simple infinite
lattice spectrum.
3. Sphinx documentation at libref/mcnp.rst, libref/mcnpcard.rst, and
usersguide/mcnp.rst.

The following functionality exists:

1. The user can generate an MCNP input by instantiating a member of the class,
calling a number of `add_*()` methods and subsequently calling `write()`
(see example).
2. Basic cell cards (allowing lattice inputs is perhaps the most challenging
card input to manage).
3. Simple surface cards (this is the easiest to extend).
4. A criticality source (no `SDEF` yet).
5. Simple F4 tally and a tally multiplier card if desired.
6. Other simple cards.
7. Minimal error checking.

Something that is not documented but that is implemented is that the class also
contains methods for running MCNPX. So, originally I had it set up to more than
simply generate in an input file; it was connected to my own output parser
(that also only served my needs) and so I did not need to interact with MCNPX
at all on my own.

*********************
Desired functionality
*********************
Anthony Scopatz was saying that he imagines this input wrapper would operate
through dictionaries, somewhat along the idea of what json files are. The
benefit is mostly that the data is then not attached to a class, and it
persists in a human-readable format. What I am interested in
is the object-oriented interface, which it seens can easily be a layer on top
of something like a json file. An NJOY project we found used json-type files to
express NJOY input in a human-readable form, and we could do something similar
here.

Perhaps the biggest objective with this code is creating something that is
persistent so that the input object is not created again every time the input
is to be modified. That is, an input object built from the interactive command
prompt could be loaded again without having to execute all the commands;
everything would be saved in the json file. Basically it seems that the
mcnpcard class would write to the json file instead of storing the data in the
class until its asked to write an output file(mcnp.Inp.write()).

***********
Future work
***********
The following are in no particular order, but are the things I have in mind for
what needs to be done. Of course, there is the basic need to add most of cards
available first.:

1. Error-checking: it would be nice to be able to do some of the error checking in
this class, especially in cases where the MCNPX errors are unclear. This may
not be relevant here, but for example the MCNPX error that results when the
line endings are not correct (LF versus CRLF) is not descriptive. Some of
MCNPX's error checking seems to be pretty good though.
2. JSON: Create a JSON file layer as a file that users can use to make their
objects persist. This could be done using the `json` python module, or with
our own classes if that puts too much "junk" into the JSON file.
3. Integrating with existing PyNE modules, especially pyne.Material.
4. Creating a number of examples of usage; I feel that this is really the best
way for people to learn how to use the module.

******************
Design Discussions
******************
There are some aspects of the design of the interface that I'd like to hear
your thoughts about:

1. Learning curve: What do we expect the user knows? When they use a temp keyword
on a cell card should the documentation tell them what free gas thermal
treatment is? Do we want people to have learned how to write cards before using
this wrapper, or be able to only know the wrapper interface? I think that
the code might become too hard to maintain with MCNPX updates, etc. if we
try to write it in such a way that the user need not visit the MCNPX manual.
I think that we should expect that the user knows the manual, or perhaps we
can refer the user to sections in it. This may also become an issue with
security/export control. I'm tempted to put a lot of documentation into the
docstrings so that the MCNPX manual need not be referenced, as this would
enhance usability, but perhaps it does not make sense.
2. Repitition of methods. Basically each card has a class in `pyne.mcnpcard`
and a method in `pyne.mcnp`. Maybe it isn't really an issue. The former has
information about the input as a whole, and the latter has the "low-level"
information about how the card is supposed to be written. I am particularly
interested in any feedback on how this duplication may be eliminated without
losing the functionality it provides.
3. I've only used MCNPX for the past two years and I haven't done anything too
crazy with it. I'm sure some of you have used it in much more substantial
ways. What type of functionality is necessary for the wrapper? I believe
that modularity is typically achieved by writing multiple text files and
including them into the actual input file using `FILE=` cards. How can we,
in this new framework, still allow for the traditional modularity? Or should
people achieve the modularity just by maintaining scripts that generate
those individual text files? Can the `mcnp.Inp` class be used to generate
only partial input files?
4. Should we develop the different classes (Outp, Mctal) so that we have a
complete MCNP wrapper (i.e. it would have a method to run MCNP) and the user
does not need to actually interact with MCNP on their own? If someone uses
this mcnp.Inp class they are likely going to write their own `run()` method,
etc. Is that functionality the same across all users? If it is then perhaps
we should implement it.