diff --git a/doc/source/faq.rst b/doc/source/faq.rst index f6142bc..74468d0 100644 --- a/doc/source/faq.rst +++ b/doc/source/faq.rst @@ -1,3 +1,68 @@ Frequently Asked Questions =========================== +:meth:`wrf.getvar` uses more memory when xarray is enabled. Is there a memory leak? +------------------------------------------------------------------------------------- + +The difference in memory usage can be observed when running the following code with +and without xarray enabled (see :meth:`wrf.disable_xarray`): + +.. code:: python + + from netCDF4 import Dataset + import wrf + + # Uncomment to disable xarray + # wrf.disable_xarray() + + for i in range(150): + f = Dataset('wrfout_d01_2005-07-17_12_00_00.nc') + p = wrf.getvar(f, 'pressure') + f.close() + +When xarray is enabled, there is an internal thread-local cache used to hold the +XLAT and XLONG coordinate variables, along with a boolean variable to remember +if a particular file or sequence is from a moving nest. This is useful when +working with sequences of WRF files, so that the XLAT and XLONG variables +aren't repeatedly extracted. This cache is limited to holding 20 items by +default, where the key to each cache entry is the object ID for the file +or sequence of files. In this particular example, a new file object is created +for each iteration, which will have a new object ID, so the 20 cache spots are +going to be filled up. Memory usage will be quite a bit higher for the +xarray-enabled case, but the memory usage will eventually top off. + +There is a function :meth:`wrf.set_cache_size` that can be used to decrease the +number of files/sequences in the cache. By setting the cache size to 0, the +cache can be disabled completely. + + +Can I use :class:`xarray.Dataset` as an input to the wrf-python functions? +-------------------------------------------------------------------------- + +Currently, wrf-python is designed to use the API for PyNIO and netCDF4-python, +which differs from the xarray.Dataset API. However, there is an undocumented +feature for Dataset objects that can be used as workaround. Each Dataset +object has a :attr:`xarray.Dataset._file_obj.ds` attribute that can be used +to obtain the underlying netCDF file object. Keep in mind that this is not in +the public API for xarray, so it could break in a future release. + +Here is an example: + +.. code:: python + + import xarray + import wrf + + ds = xarray.open_dataset(FILENAME) + slp = wrf.getvar(ds._file_obj.ds, "slp") + + +In a future release of wrf-python, direct support for Dataset objects will +be added and this will no longer be necessary. + + + + + + +