Getting Involved

There are lots of ways to get involved with yt, as a community and as a technical system – not all of them just contributing code, but also participating in the community, helping us with designing the websites, adding documentation, and sharing your scripts with others.

Coding is only one way to be involved!

Communication Channels

There are five main communication channels for yt:

  • We have an IRC channel, on irc.freenode.net in #yt. You can connect through our web gateway without any special client, at http://yt-project.org/irc.html . IRC is the first stop for conversation!
  • Many yt developers participate in the yt Slack community. Slack is a free chat service that many teams use to organize their work. You can get an invite to yt’s Slack organization by clicking the “Join us @ Slack” button on this page: http://yt-project.org/community.html
  • yt-users is a relatively high-traffic mailing list where people are encouraged to ask questions about the code, figure things out and so on.
  • yt-dev is a much lower-traffic mailing list designed to focus on discussions of improvements to the code, ideas about planning, development issues, and so on.
  • yt-svn is the (now-inaccurately titled) mailing list where all pushes to the primary repository are sent.

The easiest way to get involved with yt is to read the mailing lists, hang out in IRC or slack chat, and participate. If someone asks a question you know the answer to (or have your own question about!) write back and answer it.

If you have an idea about something, suggest it! We not only welcome participation, we encourage it.

Documentation

The yt documentation is constantly being updated, and it is a task we would very much appreciate assistance with. Whether that is adding a section, updating an outdated section, contributing typo or grammatical fixes, adding a FAQ, or increasing coverage of functionality, it would be very helpful if you wanted to help out.

The easiest way to help out is to fork the main yt repository (where the documentation lives in the doc directory in the root of the yt mercurial repository) and then make your changes in your own fork. When you are done, issue a pull request through the website for your new fork, and we can comment back and forth and eventually accept your changes. See Making and Sharing Changes for more information about contributing your changes to yt on bitbucket.

Technical Contributions

Contributing code is another excellent way to participate – whether it’s bug fixes, new features, analysis modules, or a new code frontend. See Creating A New Code Frontend for more details.

The process is pretty simple: fork on BitBucket, make changes, issue a pull request. We can then go back and forth with comments in the pull request, but usually we end up accepting.

For more information, see How to Develop yt, where we spell out how to get up and running with a development environment, how to commit, and how to use BitBucket.

Online Presence

Some of these fall under the other items, but if you’d like to help out with the website or any of the other ways yt is presented online, please feel free! Almost everything is kept in hg repositories on BitBucket, and it is very easy to fork and contribute back changes.

Please feel free to dig in and contribute changes.

Word of Mouth

If you’re using yt and it has increased your productivity, please feel encouraged to share that information. Cite our paper, tell your colleagues, and just spread word of mouth. By telling people about your successes, you’ll help bring more eyes and hands to the table – in this manner, by increasing participation, collaboration, and simply spreading the limits of what the code is asked to do, we hope to help scale the utility and capability of yt with the community size.

Feel free to blog about, tweet about and talk about what you are up to!

Long-Term Projects

There are some wild-eyed, out-there ideas that have been bandied about for the future directions of yt – some of them even written into the mission statement. The ultimate goal is to move past simple analysis and visualization of data and begin to approach it from the other side, of generating data, running solvers. We also hope to increase its ability to act as an in situ analysis code, by presenting a unified protocol. Other projects include interfacing with ParaView and VisIt, creating a web GUI for running simulations, creating a run-tracker that follows simulations in progress, a federated database for simulation outputs, and so on and so forth.

yt is an ambitious project. Let’s be ambitious together.

yt Community Code of Conduct

The community of participants in open source Scientific projects is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences success and continued growth. We expect everyone in our community to follow these guidelines when interacting with others both inside and outside of our community. Our goal is to keep ours a positive, inclusive, successful, and growing community.

As members of the community,

  • We pledge to treat all people with respect and provide a harassment- and bullying-free environment, regardless of sex, sexual orientation and/or gender identity, disability, physical appearance, body size, race, nationality, ethnicity, and religion. In particular, sexual language and imagery, sexist, racist, or otherwise exclusionary jokes are not appropriate.
  • We pledge to respect the work of others by recognizing acknowledgment/citation requests of original authors. As authors, we pledge to be explicit about how we want our own work to be cited or acknowledged.
  • We pledge to welcome those interested in joining the community, and realize that including people with a variety of opinions and backgrounds will only serve to enrich our community. In particular, discussions relating to pros/cons of various technologies, programming languages, and so on are welcome, but these should be done with respect, taking proactive measure to ensure that all participants are heard and feel confident that they can freely express their opinions.
  • We pledge to welcome questions and answer them respectfully, paying particular attention to those new to the community. We pledge to provide respectful criticisms and feedback in forums, especially in discussion threads resulting from code contributions.
  • We pledge to be conscientious of the perceptions of the wider community and to respond to criticism respectfully. We will strive to model behaviors that encourage productive debate and disagreement, both within our community and where we are criticized. We will treat those outside our community with the same respect as people within our community.
  • We pledge to help the entire community follow the code of conduct, and to not remain silent when we see violations of the code of conduct. We will take action when members of our community violate this code such as contacting confidential@yt-project.org (all emails sent to this address will be treated with the strictest confidence) or talking privately with the person.

This code of conduct applies to all community situations online and offline, including mailing lists, forums, social media, conferences, meetings, associated social events, and one-to-one interactions.

The yt Community Code of Conduct was adapted from the Astropy Community Code of Conduct, which was partially inspired by the PSF code of conduct.

How to Develop yt

yt is a community project!

We are very happy to accept patches, features, and bugfixes from any member of the community! yt is developed using mercurial, primarily because it enables very easy and straightforward submission of changesets. We’re eager to hear from you, and if you are developing yt, we encourage you to subscribe to the developer mailing list. Please feel free to hack around, commit changes, and send them upstream.

Note

If you already know how to use the mercurial version control system and are comfortable with handling it yourself, the quickest way to contribute to yt is to fork us on BitBucket, make your changes, push the changes to your fork and issue a pull request. The rest of this document is just an explanation of how to do that.

See Coding Style Guide for more information about coding style in yt and Docstrings for an example docstring. Please read them before hacking on the codebase, and feel free to email any of the mailing lists for help with the codebase.

Keep in touch, and happy hacking!

Open Issues

If you’re interested in participating in yt development, take a look at the issue tracker on bitbucket. Issues are marked with a milestone of “easy”, “moderate”, or “difficult” depending on the estimated level of difficulty for fixing the issue. While we try to triage the issue tracker regularly, it may be the case that issues marked “moderate” are actually easier than their milestone label indicates since that is the default value.

Here are some predefined issue searches that might be useful:

Submitting Changes

We provide a brief introduction to submitting changes here. yt thrives on the strength of its communities (http://arxiv.org/abs/1301.7064 has further discussion) and we encourage contributions from any user. While we do not discuss version control, mercurial or the advanced usage of BitBucket in detail here, we do provide an outline of how to submit changes and we are happy to provide further assistance or guidance.

Licensing

yt is licensed under the BSD 3-clause license. Versions previous to yt-2.6 were released under the GPLv3.

All contributed code must be BSD-compatible. If you’d rather not license in this manner, but still want to contribute, please consider creating an external package, which we’ll happily link to.

How To Get The Source Code For Editing

yt is hosted on BitBucket, and you can see all of the yt repositories at http://bitbucket.org/yt_analysis/. With the yt installation script you should have a copy of Mercurial for checking out pieces of code. Make sure you have followed the steps above for bootstrapping your development (to assure you have a bitbucket account, etc.)

In order to modify the source code for yt, we ask that you make a “fork” of the main yt repository on bitbucket. A fork is simply an exact copy of the main repository (along with its history) that you will now own and can make modifications as you please. You can create a personal fork by visiting the yt bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in, you should see an option near the top right labeled “fork”. Click this option, and then click the fork repository button on the subsequent page. You now have a forked copy of the yt repository for your own personal modification.

This forked copy exists on the bitbucket repository, so in order to access it locally, follow the instructions at the top of that webpage for that forked repository, namely run at a local command line:

$ hg clone http://bitbucket.org/<USER>/<REPOSITORY_NAME>

This downloads that new forked repository to your local machine, so that you can access it, read it, make modifications, etc. It will put the repository in a local directory of the same name as the repository in the current working directory. You should also run the following command, to make sure you are at the “yt” branch, and not other ones like “stable” (this will be important later when you want to submit your pull requests):

$ hg update yt

You can see any past state of the code by using the hg log command. For example, the following command would show you the last 5 changesets (modifications to the code) that were submitted to that repository.

$ cd <REPOSITORY_NAME>
$ hg log -l 5

Using the revision specifier (the number or hash identifier next to each changeset), you can update the local repository to any past state of the code (a previous changeset or version) by executing the command:

$ hg up revision_specifier

Lastly, if you want to use this new downloaded version of your yt repository as the active version of yt on your computer (i.e. the one which is executed when you run yt from the command line or the one that is loaded when you do import yt), then you must “activate” it using the following commands from within the repository directory.

$ cd <REPOSITORY_NAME>
$ python2.7 setup.py develop

This will rebuild all C modules as well.

How To Read The Source Code

If you just want to look at the source code, you may already have it on your computer. If you build yt using the install script, the source is available at $YT_DEST/src/yt-hg. See Installing yt Using pip or From Source for more details about to obtain the yt source code if you did not build yt using the install script.

The root directory of the yt mercurial repository contains a number of subdirectories with different components of the code. Most of the yt source code is contained in the yt subdirectory. This directory its self contains the following subdirectories:

frontends

This is where interfaces to codes are created. Within each subdirectory of yt/frontends/ there must exist the following files, even if empty:

  • data_structures.py, where subclasses of AMRGridPatch, Dataset and AMRHierarchy are defined.
  • io.py, where a subclass of IOHandler is defined.
  • fields.py, where fields we expect to find in datasets are defined
  • misc.py, where any miscellaneous functions or classes are defined.
  • definitions.py, where any definitions specific to the frontend are defined. (i.e., header formats, etc.)
fields
This is where all of the derived fields that ship with yt are defined.
geometry
This is where geometric helpler routines are defined. Handlers for grid and oct data, as well as helpers for coordinate transformations can be found here.
visualization
This is where all visualization modules are stored. This includes plot collections, the volume rendering interface, and pixelization frontends.
data_objects
All objects that handle data, processed or unprocessed, not explicitly defined as visualization are located in here. This includes the base classes for data regions, covering grids, time series, and so on. This also includes derived fields and derived quantities.
analysis_modules
This is where all mechanisms for processing data live. This includes things like clump finding, halo profiling, halo finding, and so on. This is something of a catchall, but it serves as a level of greater abstraction that simply data selection and modification.
gui
This is where all GUI components go. Typically this will be some small tool used for one or two things, which contains a launching mechanism on the command line.
utilities
All broadly useful code that doesn’t clearly fit in one of the other categories goes here.
extern
Bundled external modules (i.e. code that was not written by one of the yt authors but that yt depends on) lives here.

If you’re looking for a specific file or function in the yt source code, use the unix find command:

$ find <DIRECTORY_TREE_TO_SEARCH> -name '<FILENAME>'

The above command will find the FILENAME in any subdirectory in the DIRECTORY_TREE_TO_SEARCH. Alternatively, if you’re looking for a function call or a keyword in an unknown file in a directory tree, try:

$ grep -R <KEYWORD_TO_FIND> <DIRECTORY_TREE_TO_SEARCH>

This can be very useful for tracking down functions in the yt source.

Building yt

If you have made changes to any C or Cython (.pyx) modules, you have to rebuild yt. If your changes have exclusively been to Python modules, you will not need to re-build, but (see below) you may need to re-install.

If you are running from a clone that is executable in-place (i.e., has been installed via the installation script or you have run setup.py develop) you can rebuild these modules by executing:

$ python2.7 setup.py develop

If you have previously “installed” via setup.py install you have to re-install:

$ python2.7 setup.py install

Only one of these two options is needed.

Developing yt on Windows

If you plan to develop yt on Windows, it is necessary to use the MinGW gcc compiler that can be installed using the Anaconda Python Distribution. The libpython package must be installed from Anaconda as well. These can both be installed with a single command:

$ conda install libpython mingw

Additionally, the syntax for the setup command is slightly different; you must type:

$ python2.7 setup.py build --compiler=mingw32 develop

or

$ python2.7 setup.py build --compiler=mingw32 install

Requirements for Code Submission

Modifications to the code typically fall into one of three categories, each of which have different requirements for acceptance into the code base. These requirements are in place for a few reasons – to make sure that the code is maintainable, testable, and that we can easily include information about changes in changelogs during the release procedure. (See YTEP-0008 for more detail.)

  • New Features
    • New unit tests (possibly new answer tests) (See Testing)
    • Docstrings in the source code for the public API
    • Addition of new feature to the narrative documentation (See How to Write Documentation)
    • Addition of cookbook recipe (See How to Write Documentation)
    • Issue created on issue tracker, to ensure this is added to the changelog
  • Extension or Breakage of API in Existing Features
  • Bug fixes
    • Unit test is encouraged, to ensure breakage does not happen again in the future. (See Testing)
    • Issue created on issue tracker, to ensure this is added to the changelog

When submitting, you will be asked to make sure that your changes meet all of these requirements. They are pretty easy to meet, and we’re also happy to help out with them. In Coding Style Guide there is a list of handy tips for how to structure and write your code.

How to Use Mercurial with yt

If you’re new to Mercurial, these three resources are pretty great for learning the ins and outs:

The commands that are essential for using mercurial include:

  • hg help which provides help for any mercurial command. For example, you can learn more about the log command by doing hg help log. Other useful topics to use with hg help are hg help glossary, hg help config, hg help extensions, and hg help revsets.
  • hg commit which commits changes in the working directory to the repository, creating a new “changeset object.”
  • hg add which adds a new file to be tracked by mercurial. This does not change the working directory.
  • hg pull which pulls (from an optional path specifier) changeset objects from a remote source. The working directory is not modified.
  • hg push which sends (to an optional path specifier) changeset objects to a remote source. The working directory is not modified.
  • hg log which shows a log of all changeset objects in the current repository. Use -G to show a graph of changeset objects and their relationship.
  • hg update which (with an optional “revision” specifier) updates the state of the working directory to match a changeset object in the repository.
  • hg merge which combines two changesets to make a union of their lines of development. This updates the working directory.

We are happy to asnswers questions about mercurial use on our IRC, slack chat or on the mailing list to walk you through any troubles you might have. Here are some general suggestions for using mercurial with yt:

  • Named branches are to be avoided. Try using bookmarks (see hg help bookmark) to track work. (More info about bookmarks is available on the mercurial wiki)
  • Make sure you set a username in your ~/.hgrc before you commit any changes! All of the tutorials above will describe how to do this as one of the very first steps.
  • When contributing changes, you might be asked to make a handful of modifications to your source code. We’ll work through how to do this with you, and try to make it as painless as possible.
  • Your test may fail automated style checks. See Coding Style Guide for more information about automatically verifying your code style.
  • Please avoid deleting your yt forks, as that deletes the pull request discussion from process from BitBucket’s website, even if your pull request is merged.
  • You should only need one fork. To keep it in sync, you can sync from the website. See Bitbucket’s Blog Post about this. See Making and Sharing Changes for a description of the basic workflow and Working with Multiple BitBucket Pull Requests for a discussion about what to do when you want to have multiple open pull requests at the same time.
  • If you run into any troubles, stop by IRC (see Go on IRC to ask a question) or the mailing list.

Making and Sharing Changes

The simplest way to submit changes to yt is to do the following:

  • Build yt from the mercurial repository
  • Navigate to the root of the yt repository
  • Make some changes and commit them
  • Fork the yt repository on BitBucket
  • Push the changesets to your fork
  • Issue a pull request.

Here’s a more detailed flowchart of how to submit changes.

  1. If you have used the installation script, the source code for yt can be found in $YT_DEST/src/yt-hg. Alternatively see Installing yt Using pip or From Source for instructions on how to build yt from the mercurial repository. (Below, in How To Read The Source Code, we describe how to find items of interest.)

  2. Edit the source file you are interested in and test your changes. (See Testing for more information.)

  3. Fork yt on BitBucket. (This step only has to be done once.) You can do this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository yt.

  4. Create a bookmark to track your work. For example: hg bookmark my-first-pull-request

  5. Commit these changes, using hg commit. This can take an argument which is a series of filenames, if you have some changes you do not want to commit.

  6. Remember that this is a large development effort and to keep the code accessible to everyone, good documentation is a must. Add in source code comments for what you are doing. Add in docstrings if you are adding a new function or class or keyword to a function. Add documentation to the appropriate section of the online docs so that people other than yourself know how to use your new code.

  7. If your changes include new functionality or cover an untested area of the code, add a test. (See Testing for more information.) Commit these changes as well.

  8. Push your changes to your new fork using the command:

    hg push -B my-first-pull-request https://bitbucket.org/YourUsername/yt/
    

    Where you should substitute the name of the bookmark you are working on for my-first-pull-request. If you end up doing considerable development, you can set an alias in the file .hg/hgrc to point to this path.

    Note

    Note that the above approach uses HTTPS as the transfer protocol between your machine and BitBucket. If you prefer to use SSH - or perhaps you’re behind a proxy that doesn’t play well with SSL via HTTPS - you may want to set up an SSH key on BitBucket. Then, you use the syntax ssh://hg@bitbucket.org/YourUsername/yt, or equivalent, in place of https://bitbucket.org/YourUsername/yt in Mercurial commands. For consistency, all commands we list in this document will use the HTTPS protocol.

  9. Issue a pull request at https://bitbucket.org/YourUsername/yt/pull-request/new A pull request is essentially just asking people to review and accept the modifications you have made to your personal version of the code.

During the course of your pull request you may be asked to make changes. These changes may be related to style issues, correctness issues, or even requesting tests. The process for responding to pull request code review is relatively straightforward.

  1. Make requested changes, or leave a comment indicating why you don’t think they should be made.

  2. Commit those changes to your local repository.

  3. Push the changes to your fork:

  4. Your pull request will be automatically updated.

Working with Multiple BitBucket Pull Requests

Once you become active developing for yt, you may be working on various aspects of the code or bugfixes at the same time. Currently, BitBucket’s modus operandi for pull requests automatically updates your active pull request with every hg push of commits that are a descendant of the head of your pull request. In a normal workflow, this means that if you have an active pull request, make some changes locally for, say, an unrelated bugfix, then push those changes back to your fork in the hopes of creating a new pull request, you’ll actually end up updating your current pull request!

There are a few ways around this feature of BitBucket that will allow for multiple pull requests to coexist; we outline one such method below. We assume that you have a fork of yt at http://bitbucket.org/YourUsername/Your_yt (see Making and Sharing Changes for instructions on creating a fork) and that you have an active pull request to the main repository.

The main issue with starting another pull request is to make sure that your push to BitBucket doesn’t go to the same head as your existing pull request and trigger BitBucket’s auto-update feature. Here’s how to get your local repository away from your current pull request head using revsets and your hgrc file:

  1. Set up a Mercurial path for the main yt repository (note this is a convenience step and only needs to be done once). Add the following to your Your_yt/.hg/hgrc:

    [paths]
    upstream = https://bitbucket.org/yt_analysis/yt
    

    This will create a path called upstream that is aliased to the URL of the main yt repository.

  2. Now we’ll use revsets to update your local repository to the tip of the upstream path:

    $ hg pull upstream
    $ hg update -r "remote(yt, 'upstream')"
    

After the above steps, your local repository should be at the current head of the yt branch in the main yt repository. If you find yourself doing this a lot, it may be worth aliasing this task in your hgrc file by adding something like:

[alias]
ytupdate = update -r "remote(yt, 'upstream')"

And then you can just issue hg ytupdate to get at the current head of the yt branch on main yt repository.

Make sure you are on the branch you want to be on, and then you can make changes and hg commit them. If you prefer working with bookmarks, you may want to make a bookmark before committing your changes, such as hg bookmark mybookmark.

To push your changes on a bookmark to bitbucket, you can issue the following command:

$ hg push -B myfeature https://bitbucket.org/YourUsername/Your_yt

The -B means “publish my bookmark, the changeset the bookmark is pointing at, and any ancestors of that changeset that aren’t already on the remote server”.

To push to your fork on BitBucket if you didn’t use a bookmark, you issue the following:

$ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt

The -r . means “push only the commit I’m standing on and any ancestors.” The -f is to force Mecurial to do the push since we are creating a new remote head without a bookmark.

You can then go to the BitBucket interface and issue a new pull request based on your last changes, as usual.

Coding Style Guide

Automatically checking code style

Below are a list of rules for coding style in yt. Some of these rules are suggestions are not explicitly enforced, while some are enforced via automated testing. The yt project uses a subset of the rules checked by flake8 to verify our code. The flake8 tool is a combination of the pyflakes and pep8 tools. To check the coding style of your contributions locally you will need to install the flake8 tool from pip:

$ pip install flake8

And then navigate to the root of the yt repository and run flake8 on the yt folder:

$ cd $YT_HG
$ flake8 ./yt

This will print out any flake8 errors or warnings that your newly added code triggers. The errors will be in your newly added code because we have already cleaned up the rest of the yt codebase of the errors and warnings detected by the flake8 tool. Note that this will only trigger a subset of the full flake8 error and warning list, since we explicitly blacklist a large number of the full list of rules that are checked by flake8 by default.

Source code style guide

  • In general, follow PEP-8 guidelines. http://www.python.org/dev/peps/pep-0008/
  • Classes are ConjoinedCapitals, methods and functions are lowercase_with_underscores.
  • Use 4 spaces, not tabs, to represent indentation.
  • Line widths should not be more than 80 characters.
  • Do not use nested classes unless you have a very good reason to, such as requiring a namespace or class-definition modification. Classes should live at the top level. __metaclass__ is exempt from this.
  • Do not use unnecessary parenthesis in conditionals. if((something) and (something_else)) should be rewritten as if something and something_else. Python is more forgiving than C.
  • Avoid copying memory when possible. For example, don’t do a = a.reshape(3,4) when a.shape = (3,4) will do, and a = a * 3 should be np.multiply(a, 3, a).
  • In general, avoid all double-underscore method names: __something is usually unnecessary.
  • When writing a subclass, use the super built-in to access the super class, rather than explicitly. Ex: super(SpecialGridSubclass, self).__init__() rather than SpecialGrid.__init__().
  • Docstrings should describe input, output, behavior, and any state changes that occur on an object. See Docstrings below for a fiducial example of a docstring.
  • Use only one top-level import per line. Unless there is a good reason not to, imports should happen at the top of the file, after the copyright blurb.
  • Never compare with True or False using == or !=, always use is or is not.
  • If you are comparing with a numpy boolean array, just refer to the array. Ex: do np.all(array) instead of np.all(array == True).
  • Never comapre with None using == or !=, use is None or is not None.
  • Use statement is not True instead of not statement is True
  • Only one statement per line, do not use semicolons to put two or more statements on a single line.
  • Only declare local variables if they will be used later. If you do not use the return value of a function, do not store it in a variable.
  • Add tests for new functionality. When fixing a bug, consider adding a test to prevent the bug from recurring.

API Style Guide

  • Do not use from some_module import *

  • Internally, only import from source files directly – instead of:

    from yt.visualization.api import ProjectionPlot

    do:

    from yt.visualization.plot_window import ProjectionPlot

  • Import symbols from the module where they are defined, avoid transitive imports.

  • Import standard library modules, functions, and classes from builtins, do not import them from other yt files.

  • Numpy is to be imported as np.

  • Do not use too many keyword arguments. If you have a lot of keyword arguments, then you are doing too much in __init__ and not enough via parameter setting.

  • In function arguments, place spaces before commas. def something(a,b,c) should be def something(a, b, c).

  • Don’t create a new class to replicate the functionality of an old class – replace the old class. Too many options makes for a confusing user experience.

  • Parameter files external to yt are a last resort.

  • The usage of the **kwargs construction should be avoided. If they cannot be avoided, they must be explained, even if they are only to be passed on to a nested function.

Docstrings

The following is an example docstring. You can use it as a template for docstrings in your code and as a guide for how we expect docstrings to look and the level of detail we are looking for. Note that we use NumPy style docstrings written in Sphinx restructured text format.

r"""A one-line summary that does not use variable names or the
function name.

Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. ``var``.

Parameters
----------
var1 : array_like
    Array_like means all those objects -- lists, nested lists, etc. --
    that can be converted to an array.  We can also refer to
    variables like ``var1``.
var2 : int
    The type above can either refer to an actual Python type
    (e.g. ``int``), or describe the type of the variable in more
    detail, e.g. ``(N,) ndarray`` or ``array_like``.
Long_variable_name : {'hi', 'ho'}, optional
    Choices in brackets, default first when optional.

Returns
-------
describe : type
    Explanation
output : type
    Explanation
tuple : type
    Explanation
items : type
    even more explaining

Other Parameters
----------------
only_seldom_used_keywords : type
    Explanation
common_parameters_listed_above : type
    Explanation

Raises
------
BadException
    Because you shouldn't have done that.

See Also
--------
otherfunc : relationship (optional)
newfunc : Relationship (optional), which could be fairly long, in which
          case the line wraps here.
thirdfunc, fourthfunc, fifthfunc

Notes
-----
Notes about the implementation algorithm (if needed).

This can have multiple paragraphs.

You may include some math:

.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}

And even use a greek symbol like :math:`omega` inline.

References
----------
Cite the relevant literature, e.g. [1]_.  You may also cite these
references in the notes section above.

.. [1] O. McNoleg, "The integration of GIS, remote sensing,
   expert systems and adaptive co-kriging for environmental habitat
   modelling of the Highland Haggis using object-oriented, fuzzy-logic
   and neural-network techniques," Computers & Geosciences, vol. 22,
   pp. 585-588, 1996.

Examples
--------
These are written in doctest format, and should illustrate how to
use the function.  Use the variables 'ds' for the dataset, 'pc' for
a plot collection, 'c' for a center, and 'L' for a vector.

>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
>>> print "a\n\nb"
a
b

"""

Variable Names and Enzo-isms

Avoid Enzo-isms. This includes but is not limited to:

  • Hard-coding parameter names that are the same as those in Enzo. The following translation table should be of some help. Note that the parameters are now properties on a Dataset subclass: you access them like ds.refine_by .

    • RefineBy `` => `` refine_by
    • TopGridRank `` => `` dimensionality
    • TopGridDimensions `` => `` domain_dimensions
    • InitialTime `` => `` current_time
    • DomainLeftEdge `` => `` domain_left_edge
    • DomainRightEdge `` => `` domain_right_edge
    • CurrentTimeIdentifier `` => `` unique_identifier
    • CosmologyCurrentRedshift `` => `` current_redshift
    • ComovingCoordinates `` => `` cosmological_simulation
    • CosmologyOmegaMatterNow `` => `` omega_matter
    • CosmologyOmegaLambdaNow `` => `` omega_lambda
    • CosmologyHubbleConstantNow `` => `` hubble_constant
  • Do not assume that the domain runs from 0 .. 1. This is not true everywhere.

  • Variable names should be short but descriptive.

  • No globals!