From a872a70d4450a56c0f61009138019767f9a20d4d Mon Sep 17 00:00:00 2001 From: steven-murray Date: Fri, 19 Feb 2016 18:50:41 +0800 Subject: [PATCH] updated docs significantly, adding features and better intro example --- CHANGELOG.rst | 3 +++ README.rst | 8 +++----- docs/index.rst | 56 ++++++++++++++++++++++++++++++++++++++------------ 3 files changed, 49 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index d8ef51d..155c9c5 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -15,6 +15,9 @@ come in v2.1.0, which may again be backward incompatible. Though this is not ide backwards-incompatible changes will be restricted to increase in the major version number), this has been driven by time constraints. +Known issues with this version, to be addressed by the next, are that both scripts (hmf and hmf-fit) +are buggy and untested. Don't use these until the next version unless you're crazy. + Features ++++++++ - New methods on all frameworks to list all parameters, defaults and current values. diff --git a/README.rst b/README.rst index d879727..b8e2e86 100644 --- a/README.rst +++ b/README.rst @@ -2,7 +2,7 @@ hmf === -**The halo mass function calculator** +**The halo mass function calculator.** .. image:: https://travis-ci.org/steven-murray/hmf.png?branch=master :target: https://travis-ci.org/steven-murray/hmf @@ -14,10 +14,8 @@ hmf :target: https://coveralls.io/github/steven-murray/hmf?branch=master `hmf` is a python application that provides a flexible and simple way to calculate the -Halo Mass Function for any input cosmology, redshift, dark matter model, virial -overdensity or several other variables. Addition of further variables should be simple. - -It is also the backend to `HMFcalc `_, the online HMF calculator. +Halo Mass Function for a range of varying parameters. It is also the backend to +`HMFcalc `_, the online HMF calculator. Documentation ------------- diff --git a/docs/index.rst b/docs/index.rst index 2905b9d..0fc2d05 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,28 @@ .. include:: ../README.rst +Features +-------- +* Calculate mass functions and related quantities extremely easily. +* Very simple to start using, but wide-ranging flexibility. +* Caching system for optimal parameter updates, for efficient iteration over parameter space. +* Support for all LambdaCDM cosmologies. +* Focus on flexibility in models. Each "Component", such as fitting functions, filter functions, + growth factor models and transfer function fits are implemented as generic classes that + can easily be altered by the user without touching the source code. +* Focus on simplicity in frameworks. Each "Framework" mixes available "Components" to derive + useful quantities -- all given as attributes of the Framework. +* Comprehensive in terms of output quantities: access differential and cumulative mass functions, + mass variance, effective spectral index, growth rate, cosmographic functions and more. +* Comprehensive in terms of implemented Component models + * 5+ models of transfer functions including directly from CAMB + * 4 filter functions + * 20 hmf fitting functions +* Includes models for Warm Dark Matter +* Nonlinear power spectra via HALOFIT +* Functions for sampling the mass function. +* CLI scripts both for producing any quantity included, or fitting any quantity. + Installation ------------ `hmf` is built on several other packages, most of which will be familiar to the @@ -13,7 +35,9 @@ installed when installing `hmf`, except for one. Explicitly, the dependencies ar numpy, scipy, scitools, cosmolopy and emcee. You will only need `emcee` if you are going to be using the fitting capabilities -of `hmf`. The final, optional, library is pycamb. It is a bit trickier to install. +of `hmf`. + +The final, optional, library is pycamb. It is a bit trickier to install. Please follow the guidelines on its `readme page `_. .. note:: At present, versions of CAMB post March 2013 are not working with @@ -26,30 +50,36 @@ to install the latest build (not necessarily stable), grab it `here To go really bleeding edge, install the develop branch using ``pip install git+git://github.com/steven-murray/hmf.git@develop``. -Basic Usage ------------ -`hmf` can be used interactively (for instance in ipython) or in a script and is -called like this: +Quickstart +---------- +Once you have `hmf` installed, you can quickly generate a mass function +by opening an interpreter (e.g. IPython) and doing: >>> from hmf import MassFunction >>> hmf = MassFunction() >>> mass_func = hmf.dndlnm ->>> mass_variance = hmf.sigma ->>> ... -This will return a Sheth-Mo-Tormen (2001) mass function between -:math:`10^{10}-10^{15} M_\odot`, at :math:`z=0` for the default PLANCK cosmology. -Cosmological parameters may be passed to the initialiser, ``MassFunction()`` +Note that all parameters have (what I consider reasonable) defaults. In particular, +this will return a Sheth-Mo-Tormen (2001) mass function between +:math:`10^{10}-10^{15} M_\odot`, at :math:`z=0` for the default PLANCK15 cosmology. +Nevertheless, there are several parameters which can be input, either cosmological +or otherwise. The best way to see these is to do + +>>> MassFunction.parameter_info() + +We can also check which parameters have been set in our "default" instance: + +>>> hmf.parameter_values To change the parameters (cosmological or otherwise), one should use the `update()` method, if a MassFunction() object already exists. For example >>> hmf = MassFunction() ->>> hmf.update(omegab = 0.05,z=10) #update baryon density and redshift +>>> hmf.update(Ob0 = 0.05, z=10) #update baryon density and redshift >>> cumulative_mass_func = hmf.ngtm -Please check the more in-depth user-guide for more details, or even the API -documentation. +For a more involved introduction to `hmf`, check out the `tutorials `_, +which are currently under construction, or the `API docs `_. Contents