bin.MarsNest
============

.. py:module:: bin.MarsNest

.. autoapi-nested-parse::

   The MarsNest executable does not accept any input.

   The executable requires the presence of grid_spec files in the current directory.
   Test grid_spec files can be generated by running the AmesGCM with 0 days as the input.


   Third-party Requirements:

       * ``numpy``
       * ``argparse``
       * ``netCDF4``
       * ``matplotlib``
       * ``os``



Attributes
----------

.. autoapisummary::

   bin.MarsNest.args
   bin.MarsNest.debug
   bin.MarsNest.f
   bin.MarsNest.map_dir
   bin.MarsNest.nskip
   bin.MarsNest.parser
   bin.MarsNest.parser
   bin.MarsNest.thick_line


Functions
---------

.. autoapisummary::

   bin.MarsNest.debug_wrapper
   bin.MarsNest.extract_grid
   bin.MarsNest.extract_path_basename
   bin.MarsNest.find_tile_number
   bin.MarsNest.get_corners
   bin.MarsNest.get_poly_path
   bin.MarsNest.is_child
   bin.MarsNest.list_full_paths
   bin.MarsNest.main


Module Contents
---------------

.. py:function:: debug_wrapper(func)

   A decorator that wraps a function with error handling
   based on the --debug flag.

   If the --debug flag is set, it prints the full traceback
   of any exception that occurs. Otherwise, it prints a
   simplified error message.

   :param func: The function to wrap.
   :type   func: function
   :return: The wrapped function.
   :rtype:  function
   :raises Exception: If an error occurs during the function call.
   :raises TypeError: If the function is not callable.
   :raises ValueError: If the function is not found.
   :raises NameError: If the function is not defined.
   :raises AttributeError: If the function does not have the
       specified attribute.
   :raises ImportError: If the function cannot be imported.
   :raises RuntimeError: If the function cannot be run.
   :raises KeyError: If the function does not have the
       specified key.
   :raises IndexError: If the function does not have the
       specified index.
   :raises IOError: If the function cannot be opened.
   :raises OSError: If the function cannot be accessed.
   :raises EOFError: If the function cannot be read.
   :raises MemoryError: If the function cannot be allocated.
   :raises OverflowError: If the function cannot be overflowed.
   :raises ZeroDivisionError: If the function cannot be divided by zero.
   :raises StopIteration: If the function cannot be stopped.
   :raises KeyboardInterrupt: If the function cannot be interrupted.
   :raises SystemExit: If the function cannot be exited.
   :raises AssertionError: If the function cannot be asserted.


.. py:function:: extract_grid(lon, lat, varIN, lon_target, lat_target, window_lon, window_lat)

   This function extract a subsample of a larger grid variable. It deals with wrapping around the longitudes on the edges of the grid.
   Args:
       lon: 1D array of longitude -180/+180
       lat: 1D array of latitudes -90/+90
       varIN: 2D array  var2IN(lat,lon)
       lon_target: float, center longitude of subgrid (e.g =-136.)
       lat_target: float, center latitude of subgrid  (e.g =40.)
       window_lon: width of window in degree   (e.g =10.)
       window_lat: heigth of window in degree  (e.g. =5.)
   Returns:
       lon_window: 1D array of truncated longitude (may not be increasing)
       lat_window: 1D array of truncated latitudes (may not be increasing)
       varIN_out:  2D array of subsample of varIN


.. py:function:: extract_path_basename(filename)

   Return the path and basename of a file. If only the filename is provided, assume it is the current directory
   Args:
       filename: e.g. 'XXXXX.fixed.nc', './history/XXXXX.fixed.nc' or '/home/user/history/XXXXX.fixed.nc'
   Returns:
       filepath : '/home/user/history/XXXXX.fixed.nc' in all the cases above
       basename:   XXXXX.fixed.nc in all the cases above

   ***NOTE***
   This routine does not check for file existence and only operates on the provided input string.


.. py:function:: find_tile_number(filename)

   Return the line number given a file name.
   (Spit grid_spec.nest03.tile8.nc as  "grid_spec.nest03" ".tile" "8.nc" and remove ".nc"


.. py:function:: get_corners(poly_path)

   Return the North West and South East corner of a gridscspec file.
   Args:
       gridspec_filename: full path to a gridscpec file
   Return:
       NWc,SEc =(lat,lon) of the two corners


.. py:function:: get_poly_path(gridspec_filename)

   Return the North West and South East corner of a gridscspec file.
   Args:
       gridspec_filename: full path to a gridscpec file
   Return:
       poly = a numpy array size (N,(lat,lon) )with the corners


.. py:function:: is_child(poly_path_child, poly_path_parent)

   Test if a grid is nested in another grid.
   Args:
       poly_path_child: a polygon object wit the 4 corners of the child tile
       poly_path_parent: a polygon object wit the 4 corners of the parent tile
   Returns:
       bool: True if all the corners of the child grids are contained within the path defined by the paretn grid



.. py:function:: list_full_paths(input_path)

   List all files in directory.


.. py:function:: main()

.. py:data:: args
   :value: None


.. py:data:: debug

.. py:data:: f

.. py:data:: map_dir
   :value: '/nobackup/rurata/FMS_MARS_data/mars_topo.nc'


.. py:data:: nskip
   :value: 2


.. py:data:: parser

.. py:data:: parser

.. py:data:: thick_line
   :value: 0.5