Updates the global list of line error-suppressions.

  Parses any NOLINT comments on the current line, updating the global
  error_suppressions store.  Reports an error if the NOLINT comment
  was malformed.

  Args:
    filename: str, the name of the input file.
    raw_line: str, the line of input text, with comments.
    linenum: int, the number of the current line.
    error: function, an error handler.


Returns a non-empty error message if the next header is out of order.

    This function also updates the internal state to be ready to check
    the next include.

    Args:
      header_type: One of the _XXX_HEADER constants defined above.

    Returns:
      The empty string if the header is in the right order, or an
      error message describing what's wrong.


Logs the fact we've found a lint error.

  We log where the error was found, and also our confidence in the error,
  that is, how certain we are this is a legitimate style regression, and
  not a misidentification or a use that's sometimes justified.

  False positives can be suppressed by the use of
  "cpplint(category)"  comments on the offending line.  These are
  parsed into _error_suppressions.

  Args:
    filename: The name of the file containing the error.
    linenum: The number of the line containing the error.
    category: A string used to describe the "category" this bug
      falls under: "whitespace", say, or "runtime".  Categories
      may have a hierarchy separated by slashes: "whitespace/indent".
    confidence: A number from 1-5 representing a confidence score for
      the error, with 5 meaning that we are certain of the problem,
      and 1 meaning that it could be a legitimate construct.
    message: The error message.


Returns the CPP variable that should be used as a header guard.

  Args:
    filename: The name of a C++ header file.

  Returns:
    The CPP variable that should be used as a header guard in the
    named file.


Logs an error if a source file does not include its header.


Update nesting state with current line.

    Args:
      filename: The name of the current file.
      clean_lines: A CleansedLines instance containing the file.
      linenum: The number of the line to check.
      error: The function to call with any errors found.


r"""Logs an error if we see certain non-ANSI constructs ignored by gcc-2.

  Complain about several constructs which gcc-2 accepts, but which are
  not standard C++.  Warning about these in lint is one way to ease the
  transition to new compilers.
  - put storage class first (e.g. "static const" instead of "const static").
  - "%lld" instead of %qd" in printf-type functions.
  - "%1$d" is non-standard in printf-type functions.
  - "\%" is an undefined character escape sequence.
  - text after #endif is not allowed.
  - invalid inner-style forward declaration.
  - >? and <? operators, and their >?= and <?= cousins.

  Additionally, check for constructor/destructor style violations and reference
  members, as it is very convenient to do so while checking for
  gcc-2 compliance.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    nesting_state: A NestingState instance which maintains information about
                   the current stack of nested blocks being parsed.
    error: A callable to which errors are reported, which takes 4 arguments:
           filename, line number, error level, and message


Checks for the correctness of various spacing around function calls.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    error: The function to call with any errors found.


Reports for long function bodies.

  For an overview why this is done, see:
  https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Write_Short_Functions

  Uses a simplistic algorithm assuming other style guidelines
  (especially spacing) are followed.
  Only checks unindented functions, so class members are unchecked.
  Trivial bodies are unchecked, so constructors with huge initializer lists
  may be missed.
  Blank/comment lines are not counted so as to avoid encouraging the removal
  of vertical space and comments just to get through a lint check.
  NOLINT *on the last line of a function* disables this check.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    function_state: Current function name and lines in body so far.
    error: The function to call with any errors found.


Checks for the correctness of various spacing issues in the code.

  Things we check for: spaces around operators, spaces after
  if/for/while/switch, no spaces around parens in function calls, two
  spaces between code and comment, don't start a block with a blank
  line, don't end a function with a blank line, don't add a blank line
  after public/protected/private, don't have too many blank lines in a row.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    nesting_state: A NestingState instance which maintains information about
                   the current stack of nested blocks being parsed.
    error: The function to call with any errors found.


Looks for misplaced braces (e.g. at the end of line).

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    error: The function to call with any errors found.


Looks for redundant trailing semicolon.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    error: The function to call with any errors found.


Checks rules from the 'C++ style rules' section of cppguide.html.

  Most of these rules are hard to test (naming, comment style), but we
  do what we can.  In particular we check for 2-space indents, line lengths,
  tab usage, spaces inside code, etc.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    file_extension: The extension (without the dot) of the filename.
    nesting_state: A NestingState instance which maintains information about
                   the current stack of nested blocks being parsed.
    error: The function to call with any errors found.


Figures out what kind of header 'include' is.

  Args:
    fileinfo: The current file cpplint is running over. A FileInfo instance.
    include: The path to a #included file.
    used_angle_brackets: True if the #include used <> rather than "".
    include_order: "default" or other value allowed in program arguments

  Returns:
    One of the _XXX_HEADER constants.

  For example:
    >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'stdio.h', True)
    _C_SYS_HEADER
    >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'string', True)
    _CPP_SYS_HEADER
    >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'foo/foo.h', True, "standardcfirst")
    _OTHER_SYS_HEADER
    >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'foo/foo.h', False)
    _LIKELY_MY_HEADER
    >>> _ClassifyInclude(FileInfo('foo/foo_unknown_extension.cc'),
    ...                  'bar/foo_other_ext.h', False)
    _POSSIBLE_MY_HEADER
    >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'foo/bar.h', False)
    _OTHER_HEADER


Check rules that are applicable to #include lines.

  Strings on #include lines are NOT removed from elided line, to make
  certain tasks easier. However, to prevent false positives, checks
  applicable to #include lines in CheckLanguage must be put here.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    include_state: An _IncludeState instance in which the headers are inserted.
    error: The function to call with any errors found.


Checks rules from the 'C++ language rules' section of cppguide.html.

  Some of these rules are hard to test (function overloading, using
  uint32 inappropriately), but we do the best we can.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    file_extension: The extension (without the dot) of the filename.
    include_state: An _IncludeState instance in which the headers are inserted.
    nesting_state: A NestingState instance which maintains information about
                   the current stack of nested blocks being parsed.
    error: The function to call with any errors found.


Check for non-const references.

  Separate from CheckLanguage since it scans backwards from current
  line, instead of scanning forward.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    nesting_state: A NestingState instance which maintains information about
                   the current stack of nested blocks being parsed.
    error: The function to call with any errors found.


Various cast related checks.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    error: The function to call with any errors found.


Checks for a C-style cast by looking for the pattern.

  Args:
    filename: The name of the current file.
    clean_lines: A CleansedLines instance containing the file.
    linenum: The number of the line to check.
    cast_type: The string for the C++ cast to recommend.  This is either
      reinterpret_cast, static_cast, or const_cast, depending.
    pattern: The regular expression used to find C-style casts.
    error: The function to call with any errors found.

  Returns:
    True if an error was emitted.
    False otherwise.


Fill up the include_dict with new includes found from the file.

  Args:
    filename: the name of the header to read.
    include_dict: a dictionary in which the headers are inserted.
    io: The io factory to use to read the file. Provided for testability.

  Returns:
    True if a header was successfully added. False otherwise.


 Loads the configuration files and processes the config overrides.

  Args:
    filename: The name of the file being processed by the linter.

  Returns:
    False if the current |filename| should not be processed further.


Does google-lint on a single file.

  Args:
    filename: The name of the file to parse.

    vlevel: The level of errors to report.  Every error of confidence
    >= verbose_level will be reported.  0 is a good default.

    extra_check_functions: An array of additional check functions that will be
                           run on each source line. Each function takes 4
                           arguments: filename, clean_lines, line, error


Prints a brief usage string and exits, optionally with an error message.

  Args:
    message: The optional error message.


Parses the command line arguments.

  This may set the output format and verbosity level as side-effects.

  Args:
    args: The command line arguments:

  Returns:
    The list of filenames to lint.


Filters out files listed in the --exclude command line switch. File paths
  in the switch are evaluated relative to the current working directory


Return true if child is subdirectory of parent.
  Assumes both paths are absolute and don't contain symlinks.


    Configure and make the executable.

    This function is called first. It is responsible for calling the configure script and
    make to create an executable. It takes no inputs and produces no outputs.


    Run the executable.

    This function is called second. It is responsible for calling the Athena++ binary in
    such a way as to produce testable output. It takes no inputs and produces no outputs.


    Analyze the output and determine if the test passes.

    This function is called third; nothing from this file is called after it. It is
    responsible for reading whatever data it needs and making a judgment about whether or
    not the test passes. It takes no inputs. Output should be True (test passes) or False
    (test fails).


Run the thread, logging everything.


Uses parameters from "athinput" to define a Riemann problem with a
    specified (optional) eos.


sanitize_lbl(label): Makes labels latex friendly.


Computes minimum pressure for Riemann solver.


Fills in empty parameters if possible.


Print state variables.


Find the middle state on the opposite side of a shock from a specified
        edge state and mid.p.

        Inputted mid state must have pressure specified

        Returns mid_state, flux across wave/shock


Energy function (of mass flux) to find root of.


Determine the two middle states for a specified middle pressure (p*).


Returns difference in middle state speeds as a function of normalized
        middle pressure.


Generate the solution to the specified Riemann problem.


Return the state for a specified sorted vector of characteristic (xi=x/t).


Returns an array of state data corresponding to the specified array of
        characteristics.


Plot solution to Riemann problem.

        Keyword arguments:
        var     -- variable(s) to be plotted (default ['rho', 'p', 'u'])
        xi_min  -- min xi to be plotted (default automatic)
        xi_max  -- max xi to be plotted (default automatic)
        nsimp   -- number of points to use in rarefaction/simple waves (default 100)
        speeds  -- choose whether to plot wave speeds (default True)
        fig     -- if True and ax is None create new figure (default True)
        ax      -- specify ax(es) to use for plotting (default None)
        popt    -- option dictionary to pass to plt.plot (default None)
        discont -- show discontinuities by not connecting lines (default True)
        lbls    -- show axis labels (default True)


Plot the Riemann fan for this problem.


Format wave-speeds for printing in a table


Format all for state-vectors for printing in a table


Return the state for a given characteristic.


Initialize ODE integration.


A RiemannSol wrapper to specify left/right state variables via a dict.
    Each key in state has form of [dpTu][lr].
    Example: state = dict(dl=1, pl=1, ul=0, dr=0.125, pr=1, ur=0)


Determine if this EOS is valid


Gamma_1 as a function of density (rho) and temperature (T)


Temperature as a function of density (rho) and specific enthalpy (h)


Temperature as a function of density (rho) and pressure (p)


Temperature as a function of density (rho) and internal energy density (e)


Function to interpret input as an EOS


Check input NumPy array for the presence of any NaN entries


Wrapper to np.loadtxt() for applying optional checks used in regression tests


Read .hst files and return dict of 1D arrays.

    Keyword arguments:
    raw -- if True, do not prune file to remove stale data from prev runs (default False)


Read .tab files and return dict or array.

    Keyword arguments:
    raw -- if True, do not parse the header to figure out key names (default False)


Read .vtk files and return dict of arrays of data.


Read .athdf files and populate dict of arrays of data.

    Keyword arguments:
    raw -- if True, do not merge MeshBlocks into a single array (default False)


Average cell values according to given mesh refinement scheme.


Read athinput file and returns a dictionary of dictionaries.


This is really an integration test of projector with maszcal.nfw


    Returns the Fourier transform of the spherical top-hat function
    evaluated at a given k*R.


    Determines the sigma^2 parameter over the m-z grid by integrating
    over k.


Convert mass M to radius R assuming density rho.


        M      is  (nM)  or  (nM, nz)
        z      is  (nz)
        rho    is  (nz)
        delta  is  (nz)  or  scalar
        k      is  (nk)
        P      is  (nz,nk)

        Somewhat awkwardly, k and P are comoving.  rho really isn't.

        return is  (nM,nz)


        Determines the sigma^2 parameter over the m-z grid by integrating
        over k.


SHAPE mass, z


SHAPE mass, z, cons


SHAPE r, mass, z, cons


SHAPE z, params


SHAPE r, z, params


SHAPE mass, z, c


SHAPE mass, r, z, c


SHAPE cluster, cons


SHAPE r, cluster, c


SHAPE r, cluster


SHAPE mu, z


SHAPE r, mu, z, params


SHAPE mu, z, params


SHAPE mu, z, r, params


SHAPE rs.shape, z, params


SHAPE cluster, rs.shape, params


SHAPE cluster, params


SHAPE a_sz, r, params


SHAPE r, a_sz, params


        The order of make_flat's output should always align with the ordering given
        by cartesian product, when the product is interpreted as coordinates for the
        values of the flattened array


Define the computational graph, which allows us to sample specific targets efficiently


Generate the observations from the true values of the parameters


Specific function to sample from the priors defined in the config file.


        Has to be built separately than in the graph scope because the julia function takes a
        dictionary of parameters as input, rather than an array that is generated in the graph


Convert the simulated stars to GD1 coordinates


Convert the simulated GD1 stars to binned images


    Initialise the swyft simulator
    Args:
      stream_generator: function (from sstrax or elsewhere) to generate the stream
      gd1_pos_coverter: function (from sstrax or elsewhere) to convert to GD1 position
      gd1_vel_converter: function (from sstrax or elsewhere) to convert to GD1 velocity
      conf: dictionary of config options, output of init_config
    Returns:
      Swyft lightning simulator instance
    Examples
    --------
    >>> sysargs = ['/path/to/config/file.txt']
    >>> tmnre_parser = read_config(sysargs)
    >>> conf = init_config(tmnre_parser, sysargs, sim=True)
    >>> import sstrax as st
    >>> simulator = init_simulator(st.simulate_stream, st.halo_to_gd1_vmap, st.halo_to_gd1_velocity_vmap, conf)


    Run a swyft simulator to save simulations into a given zarr store
    Args:
      simulator: swyft simulator object
      store: initialised zarr store
      conf: dictionary of config options, output of init_config
      max_sims: maximum number of simulations to perform (otherwise will fill store)
    Examples
    --------
    >>> sysargs = ['/path/to/config/file.txt']
    >>> tmnre_parser = read_config(sysargs)
    >>> conf = init_config(tmnre_parser, sysargs, sim=True)
    >>> simulator = init_simulator(conf)
    >>> store = setup_zarr_store(conf, simulator)
    >>> simulate(simulator, store, conf)


    Load the config using configparser, returns a parser object that can be accessed as
    e.g. tmnre_parser['FIELD']['parameter'], this will always return a string, so must be
    parsed for data types separately, see init_config
    Args:
      sysargs: list of command line arguments (i.e. strings) containing path to config in position 0
    Returns:
      Config parser object containing information in configuration file sections
    Examples
    --------
    >>> sysargs = ['/path/to/config/file.txt']
    >>> tmnre_parser = read_config(sysargs)
    >>> tmnre_parser['TMNRE']['num_rounds'] etc.


    Initialise the config dictionary, this is a dictionary of dictionaries obtaining by parsing
    the relevant config file. A copy of the config file is stored along with the eventual simulations.
    All parameters are parsed to the correct data type from strings, including lists and booleans etc.
    Args:
      tmnre_parser: config parser object, output of read_config
      sysargs: list of command line arguments (i.e. strings) containing path to config in position 0
      sim: boolean to choose whether to include config copying features etc. if False, will create a
           copy of the config in the store directory and generate the param idxs file
    Returns:
      Dictionary of configuration options with all data types explicitly parsed
    Examples
    --------
    >>> sysargs = ['/path/to/config/file.txt']
    >>> tmnre_parser = read_config(sysargs)
    >>> conf = init_config(tmnre_parser, sysargs, sim=True)


    Initialise the network with the settings given in a loaded config dictionary
    Args:
      conf: dictionary of config options, output of init_config
    Returns:
      Pytorch lightning network class
    Examples
    --------
    >>> sysargs = ['/path/to/config/file.txt']
    >>> tmnre_parser = read_config(sysargs)
    >>> conf = init_config(tmnre_parser, sysargs, sim=True)
    >>> network = init_network(conf)


    Save logratios from a particular round
    Args:
      logratios: swyft logratios instance
      conf: dictionary of config options, output of init_config
      round_id: specific round id for store name


    Save bounds from a particular round
    Args:
      bounds: unpacked swyft bounds object
      conf: dictionary of config options, output of init_config
      round_id: specific round id for store name


    Load bounds from a particular round
    Args:
      conf: dictionary of config options, output of init_config
      round_id: specific round id for store name
    Returns:
      Bounds object with ordering defined by the param idxs in the config


    Save coverage samples from a particular round
    Args:
      coverage: swyft coverage object instance
      conf: dictionary of config options, output of init_config
      round_id: specific round id for store name


Ensure a a file exists and if not make the relevant path


smooth the data using a window with requested size.

    This method is based on the convolution of a scaled window with the signal.
    The signal is prepared by introducing reflected copies of the signal
    (with the window size) in both ends so that transient parts are minimized
    in the begining and end part of the output signal.

    input:
        x: the input signal
        window_len: the dimension of the smoothing window
        window: the type of window from 'flat', 'hanning', 'hamming', 'bartlett', 'blackman'
            flat window will produce a moving average smoothing.

    output:
        the smoothed signal

    example:

    t=linspace(-2,2,0.1)
    x=sin(t)+randn(len(t))*0.1
    y=smooth(x)

    see also:

    numpy.hanning, numpy.hamming, numpy.bartlett, numpy.blackman, numpy.convolve
    scipy.signal.lfilter

    TODO: the window parameter could be the window itself if an array instead of a string

	Source: http://www.scipy.org/Cookbook/SignalSmooth		2009-03-13


Apply a length-k median filter to a 1D array x.
    Boundaries are extended by repeating endpoints.


Function loads in empty exoplanet dictionary for pandexo input


    This program contains the functionality for running PandExo

    Parameters
    ----------
    exo : exoplanet input dictionary
    inst : instrument input dictionary
    save_file : default saves file output but you can spefiy no file output
    output_path : path for output files. default will print out files in current working directory
    output_file : file name, default = single.p for single run

    Returns
    -------
    result : For single run output will just be a single PandExo output dictionary

    Attributes
    ----------
    load_mode_dict : to call instrument dictionaries based off keys
    run_inst_space : to run instrument parameters space in parallel
    run_param_space : to run exoplanet parameter space in parallel


    Determine number of HST orbits needed for transit observation when not provided by the user.

    PARAMETERS
    ----------
    trdur           : float, transit duration in seconds

    RETURNS
    -------
    norbits         : float, number of HST orbits per transit (including discarded thermal-settling orbit)

    HISTORY
    -------
    Written by Kevin Stevenson      October 2016


    Determine optimal nsamp and samp_seq values when not provided by the user.

    PARAMETERS
    ----------
    hmag            : float, H-band magnitude
    disperser       : string, grism (g102 or g141)
    scanDirection   : string, spatial scan direction (Forward or Round Trip)
    subarray        : string, subarray aperture (grism256 or grism512)
    obsTime         : float, available observing time per HST orbit in seconds
    maxScanHeight   : (optional) float, maximum scan height in pixels
    maxExptime      : (optional) float, maximum exposure time in seconds

    RETURNS
    -------
    bestnsamp       : float, number of up-the-ramp samples (1..15)
    bestsamp_seq    : string, time between non-destructive reads (SPARS5, SPARS10, or SPARS25)

    HISTORY
    -------
    Written by Kevin Stevenson      October 2016


    Determine the recommended exposure time, scan rate, scan height, and overheads.

    PARAMETERS
    ----------
    hmag            : float, H-band magnitude
    disperser       : string, grism (g102 or g141)
    scanDirection   : string, spatial scan direction (Forward or Round Trip)
    subarray        : string, subarray aperture (grism256 or grism512)
    nsamp           : float, number of up-the-ramp samples (1..15)
    samp_seq        : string, time between non-destructive reads (SPARS5, SPARS10, or SPARS25)

    RETURNS
    -------
    exptime         : float, exposure time in seconds
    tottime         : float, total frame time including overheads in seconds
    scanRate        : float, recommended scan rate in arcsec/s
    scanHeight      : float, scan height in pixels
    fluence         : float, maximum pixel fluence in electrons

    HISTORY
    -------
    Written by Kevin Stevenson      October 2016


    Compute transit/eclipse depth uncertainty for a defined system and number of spectrophotometric channels.

    PARAMETERS
    ----------
    hmag            : float, H-band magnitude
    trdur           : array, transit duration in seconds
    numTr           : array, number of observed transits/eclipses
    nchan           : float, number of spectrophotometric channels
    disperser       : string, grism (g102 or g141)
    scanDirection   : string, spatial scan direction (Forward or Round Trip)
    subarray        : string, subarray aperture (grism256 or grism512)
    nsamp           : float, number of up-the-ramp samples (1..15)
    samp_seq        : string, time between non-destructive reads (SPARS5, SPARS10, or SPARS25)
    norbits         : float, number of requested orbits per transit (including discarded thermal-settling orbit)
    schedulability  : string, % time HST can observe target (30 or 100)

    RETURNS
    -------
    deptherr        : float, transit/eclipse depth uncertainty per spectrophotometric channel

    HISTORY
    -------
    Written by Kevin Stevenson      October 2016


    Plot earliest and latest possible spectroscopic light curves for given start window size

    PARAMETERS
    ----------
    eventType       : str, 'transit' or 'eclipse'
    rms             : float, light curve root-mean-square
    ptsOrbit        : float, number of frames per HST orbit
    numOrbits       : float, number of HST orbits per visit
    depth           : float, transit/eclipse depth
    inc             : float, orbital inclination in degrees
    aRs             : float, Semi-major axis in units of stellar radii (a/R*)
    period          : float, orbital period in days
    windowSize      : float, observation start window size in minutes
    ecc             : (Optional) float, eccentricity (default is 0)
    w               : (Optional) float, longitude of periastron (default is 90 degrees)
    duration        : (Optional) float, full transit/eclipse duration in days
    offset          : (Optional) float, manual offset in observation start time, in minutes
    fignum          : (Optional) Figure number
    useFirstOrbit   : (Optional) bool, whether to use first orbit

    RETURNS
    -------
    minphase        : float, earliest observation start phase
    maxphase        : float, latest observation start phase

    HISTORY
    -------
    Written by Kevin Stevenson           October 2016
    Added eccentric orbit handling       December 2016
    Added option for useFirstOrbit, IJMC April 2017


    Plot exoplanet transmission/emission spectrum

    PARAMETERS
    ----------
    specfile        : string, filename for model spectrum [wavelength, flux]
    w_unit          : string, wavelength unit (um or nm)
    disperser       : string, grism (g102 or g141)
    deptherr        : float or array of length nchan, simulated transit/eclipse depth uncertainty
    nchan           : float, number of spectrophotometric channels
    smooth          : (Optional) float, length of smoothing kernel
    labels          : (Optional) Legend labels: ['Model name', 'Simulated obs. name']
    fignum          : (Optional) Figure number

    HISTORY
    -------
    Written by Kevin Stevenson      October 2016


    Creates the necessary directories for saving output files
    if they do not already exist.

    Parameters
    -----------
    params: dict
        Dictionary containing the parameters passed to lognormal_galaxies,
        including "out_dir" specifying the output directory.


    Generates the necessary input files for generate_Poisson.
    First, it runs eisensteinhubaonu/compute_pk to calculate the matter power spectrum from the cosmological parameters.
    Then it runs compute_xi/compute_xi to calculate the corresponding correlation function.
    Then it runs compute_pkG/calc_pkG to calculate the Gaussian power spectrum for the galaxy field.
    Then it runs compute_pkG/calc_pkG to calculate the Gaussian power spectrum for the matter field.
    Finally it runs compute_pkG/calc_pkG to calculate the Gaussian cross-power spectrum of the galaxy and matter fields.

    Parameters
    -----------
    params: dict
        Dictionary containing the parameters for lognormal_galaxies.
    exe: object
        An executable object used to run the external commands.


    Generate galaxy and matter density field and the Poisson-sampled lognormal galaxy catalog
    using lognormal_galaxies.

    Parameters
    -----------
    i: int
        Number of this realization.
    params: dict
        Dictionary containing the input parameters for lognormal_galaxies.
    seed1: int
        Seed.
    seed2: int
        Seed.
    seed3: int
        Seed.
    exe:
        Executable object used to run the external commands.


    Calls calculate_pk/calc_pk_const_los_ngp function of lognormal_galaxies.

    Parameters
    ----------
    i: int
        Number of this realization.
    params: dict
        Dictionary containing input parameters for lognormal_galaxies.
    exe:
        Executable object used to run the external commands.


    Calls function calculate_cross/calc_cpk_const_los_v2 of lognormal_galaxies to calculate galaxy-matter power spectrum.

    Parameters
    ----------
    i: int
        Number of this realization.
    params: dict
        Input parameters for lognormal_galaxies.
    exe:
        Executable object used to run the external commands.


    Returns the Kaiser linear P(k,mu) in redshift space

    .. math::

        P(k,mu) = (1 + f/b_1 \mu^2)^2 b_1^2 P_\mathrm{lin}(k)

    Copied from nbodykit.


        Method to initiate a Power_Spectrum_Model object from a file
        containing a saved LognormalIntensityMock object.

        Parameters
        -----------
        filename : str
            Name of the file containing the saved LognormalIntensityMock object.
        out_filename : str
            Output filename for the power spectrum results.
        catalog_filename : str, optional
            Filename of the catalog associated with the LognormalIntensityMock object.
        only_params : bool, optional
            Set to True to load only the parameters and skip loading the meshes.
        only_meshes : list of str, optional
            List of specific meshes to load. Default is ["noise_mesh", "obs_mask"].
        do_model_shot_noise : bool, optional
            Set to True to model the shot noise by shuffling the galaxy positions perpendicular to the LOS.
            Default is None/False.

        Returns
        --------
        instance : Power_Spectrum_Model
            An instance of the Power_Spectrum_Model class.


        Step in initializing the Power_Spectrum_Model instance.

        Parameters
        -----------
        do_model_shot_noise : bool
            Set to True to model the shot noise by shuffling the galaxy positions perpendicular to the LOS.
        out_filename : str
            Output filename for the power spectrum results.


Luminosity function times L**2


Damping function D^2 for LOS-parallel top-hat smoothing with smoothing length s_par.


Damping function D^2 for LOS-perpendicular exponential smoothing with smoothing length s_perp.


Damping function D for cic resampling with the aliasing correction for the shot noise.


Damping function D for cic resampling evaluated for this instance as a 3D array.


Damping function D^2 for a spherical top-hat smoothing in the directions perpendicular to the LOS.


        Cached property that returns the galaxy power spectrum Pm_kspec.
        If self.RSD is True, it will return the Kaiser RSD approximation.
        Otherwise it will be just the bias squared times the matter power spectrum.

        Returns
        --------
        astropy quantity array
            The power spectrum Pm_kspec.


        Model the shot noise in the intensity and galaxy distributions
        by shuffling the cells in the directions perpendicular to the LOS
        while keeping the LOS position fixed (to keep directional information
        that may exist due to redshift differences).
        After shuffling, calculate the power spectrum.
        Finally the model shot noise is given by the average of the power spectra
        of the shuffled meshes.

        Parameters
        -----------
        N_real : int, optional
            Number of realizations of shuffled meshes. Default is 10.


Broadcasts the 1D mean_intensity_per_redshift array to the 3D mesh (cached).


Broadcasts the 1D mean galaxy number density array to the 3D mesh (cached).


    Logarithmic interpolation accepting linear quantities as input (transformed within the function).

    Parameters
    ----------
    xx : array-like
        Array of x values.
    yy : array-like
        Array of y values.
    kind : str, optional
        Specifies the kind of interpolation. Default is 'linear'.
    bounds_error : bool, optional
        If True, raise an error when attempting to interpolate outside the bounds of the input data. Default is False.
    fill_value : str or numeric, optional
        Specifies the value to use for points outside the bounds of the input data when bounds_error is False. Default is 'extrapolate'.

    Returns
    -------
    callable
        A callable function that performs logarithmic interpolation on input values.


Opens a yaml file and returns a dictionary from its contents.


Uses an opened yaml file and returns the dicionary.


Prints the current memory usage in GB.


    Transforms a binary file containing galaxy data from lognormal_galaxies into an HDF5 file.

    Parameters
    ----------
    bin_filename : str
        Path to the binary output file containing the galaxy catalog from lognormal_galaxies.
    h5_filename : str, optional
        Path to the output HDF5 file.
        If not provided, the output file will be created with the same name as the input file,
        but with the extension '.h5'.

    Returns
    -------
    h5_filename
        Path to the output HDF5 file
    N_gal
        Number of galaxies.


    Calculates the monopole and quadrupole (if lmax==2) power spectrum and mean k in the given k bins.

    Parameters
    ----------
    pkspec : array-like (1D)
        Array of power spectrum values.
        Flattened 3D array.
    k_bins : array-like (1D)
        Array of bin edges for the k values.
    kspec : array-like (1D)
        Array of k values corresponding to pkspec.
        Flattened 3D array.
    muspec : array-like (1D)
        Array of mu values corresponding to pkspec.
        Flattened 3D array.
    lmax : int, optional
        Maximum multipole moment to calculate.
        Options: 1, 2
        Default: 2.

    Returns
    -------
    mean_k : ndarray
        Mean k values in each k bin.
    monopole : ndarray
        Mean monopole power spectrum in each k bin.
    quadrupole : ndarray (or None if lmax==1)
        Mean quadrupole power spectrum in each k bin.


    Bins the power spectrum into a grid of given k_bins in the perpendicular and parallel to the LOS directions.

    Parameters
    -----------
    pkspec: array-like (1D)
        Power spectrum data to be binned.
        Flattened 3D array.
    k_bins: array-like
        Array specifying the bin edges for both k_par and k_perp.
    k_par: array-like (1D)
        Array of k_parallel values corresponding to pkspec.
        Flattened 3D array.
    k_perp: array-like (1D)
        Array of k_perpendicular values corresponding to pkspec.

    Returns
    --------
    P_k_2d: array
        Binned 2D power spectrum.


    Bins the power spectrum into a grid of given k_bins and mu_bins.

    Parameters
    -----------
    pkspec: array-like (1D)
        Power spectrum data to be binned. Flattened 3D array.
    k_bins: array-like
        Array specifying the bin edges for k values.
    kspec: array-like (1D)
        Array of k values corresponding to pkspec.
        Flattened 3D array.
    muspec: array-like (1D)
        Array of mu values corresponding to pkspec.
        Flattened 3D array.
    mu_bins: array-like
        Array specifying the bin edges for mu values.

    Returns
    --------
    mean_k_2d: array
        Binned mean k values in the 2D grid.
    mean_mu_2d: array
        Binned mean mu values in the 2D grid.
    P_k_mu: array
        Binned power spectrum.


    Returns the Jinc function for x!=0 and the limit 0.5 at x==0.
    The Jinc function is the first Bessel function of x divided by x.


    Returns a pmesh.RealField object from an array 'm' as input.

    Parameters
    ----------
    m: array
        Numpy array to be transformed into a pmesh.RealField object.
    Nmesh: array
        Array with dimension (3,) with the number of cells in each dimension.


    Filter for k_perp and k_par modes separately.
    Applies to an pmesh mesh object as a regular filter.

    Uses globally defined variables:
        sigma_perp - 'angular' smoothing in the flat sky approximation
        sigma_par - 'radial' smoothing from number of channels.

    Usage:
        mesh.apply(perp_filter, mode='complex', kind='wavenumber')

    NOTES:
    k[0] *= modifies the next iteration in the loop.
    Coordinates are fixed except for the k[1] which are
    the coordinate that sets what slab is being altered?


    Top-hat filter for k_perp.
    Applies to an pmesh mesh object as a regular filter.

    Uses globally defined variables:
        size_perp - 'angular' size of the top-hat filter in the flat sky approximation

    Usage:
        mesh.apply(angular_tophat_filter, mode='complex', kind='wavenumber')

    NOTES:
    k[0] *= modifies the next iteration in the loop.
    Coordinates are fixed except for the k[1] which are
    the coordinate that sets what slab is being altered?


        Calculates the redshift difference corresponding to the comoving distance of the LOS length.

        Returns
        -------
        float
            Redshift difference corresponding to the comoving distance of the line-of-sight (LOS) length.
            Cached like a property.

        Raises
        ------
        ValueError
            If the LOS is not aligned with any of the axes [1,0,0], [0,1,0], or [0,0,1].


Calculates the minimum distance of a cell within the mesh (cached).


Calculates the redshift coordinates along the LOS axis (cached).


        Initiates a new LognormalIntensityMock instance with the same input parameters as the original one.

        Returns
        -------
        LognormalIntensityMock
            A new instance of LognormalIntensityMock with the same input parameters as the original.


        Converts the values in the input dictionary to their respective data types.

        Parameters
        ----------
        data : dict
            The input dictionary containing the data to be evaluated (string to Quantities or numbers).

        Returns
        -------
        dict
            The modified input dictionary with the evaluated strings.


        Initialize a LognormalIntensityMock instance from a saved file.

        Parameters
        ----------

        filename : str
            The filename of the saved file.

        catalog_filename : str, optional
            The filename of the galaxy catalog to be read. Default is None.

        only_params : bool, optional
            If True, only the parameters are loaded and not the meshes. Default is False.

        only_meshes : list of str, optional
            The list of specific meshes to be loaded. Default is ["intensity_mesh", "noise_mesh", "n_gal_mesh", "obs_mask"].

        Returns
        -------
        LognormalIntensityMock
            A new instance of LognormalIntensityMock initialized from the saved file.


        Initializes the galaxy catalog from a specified file.

        Parameters
        ----------
        catalog_filename : str
            The filename of the galaxy catalog file.

        Returns
        -------
        dict
            A dictionary containing the galaxy catalog data.


        Saves the instance and its attributes to a file.

        Parameters
        ----------
        filename : str
            The filename of the file to save the instance to.
        catalog_filename : str, optional
            The filename of the galaxy catalog file to save (default is None).
            If None, it does not save the galaxy catalog.


        Downsamples a given mesh to a new grid resolution using NGP.

        Parameters
        ----------
        mesh : ndarray or astropy Quantity array
            The input mesh to downsample.
        new_N_mesh : list of int (len 3)
            The new grid resolution for downsampling.

        Returns
        -------
        ndarray or astropy Quantity array
            The downsampled mesh.


        Downsamples all meshes to a new grid resolution using NGP:
        n_gal_mesh, intensity_mesh, obs_mask, sky_intensity_mesh, noise_mesh.

        Parameters
        ----------
        new_N_mesh : list of int (len 3)
            The new grid resolution for downsampling.


        Calculates the mean galaxy number density by
        integrating over the luminosity function from Lmin to Lmax.
        It does not take the selection function into account.
        Make sure that the luminosity function output is in units of
        luminosity_function: dn/dL
        integral:

        .. math:: \\int \\frac{\\mathrm{d}n}{\\mathrm{d}L} \\mathrm{d}L = \\bar{n}_\\mathrm{g} [\\mathrm{Mpc}^{-3}]

        IMPORTANT: The luminosity function input has to be in units of [Mpc^-3 luminosity_unit^-1]
        so that \int dn/dl dL is in units of [Mpc^-3].

        Cached like a property self.n_bar_gal.

        Returns
        -------
        Quantity
            The expected mean galaxy number density in units of 1/Mpc**3,
            not taking into account the selection function.


 Calculates the mean galaxy number density from the mesh self.n_gal_mesh.
            Cached like a property self.n_bar_gal_mesh.


        Calculates the power spectrum from input cosmology
        and runs lognormal simulation in lognormal_galaxies.
        Calculates the RSD position given the LOS.

        Parameters
        ----------
        None.

        Returns
        -------
        None.


        Returns an interpolation function for the input power spectrum.

        Returns
        -------
        callable
            Interpolation function for the input power spectrum.


Automatically generates the filename for the binary output file of lognormal_galaxies galaxy catalog.


        Loads the lognormal catalog from a binary file.

        Parameters
        ----------
        bin_filename : str
            Path to the binary file containing the lognormal galaxy catalog (output from lognormal_galaxies).
        delete_bin: bool
            Set to False if you want to keep the binary file.
            Default: True.

        Returns
        -------
        None.

        Raises
        ------
        AssertionError
            If the number of galaxies in the lognormal catalog does not match the number of positions in the loaded catalog.


        Calculates the power spectrum corresponding to the given wavenumber values.

        Parameters
        ----------
        k : array-like
            Wavenumber values in units of [h / Mpc].

        Returns
        -------
        Quantity
            Power spectrum values in units of [Mpc^3/h^3].


        Assigns redshift along the line-of-sight (LOS) axis
        (x, y, or z) given the mean/middle redshift.
        Also assigns the redshift-space distortion
        (RSD) redshift and inferred positions.

        Returns
        -------
        None

        Raises
        ------
        ValueError
            If the LOS is not aligned with any of the axes [1,0,0], [0,1,0], or [0,0,1].

        Notes
        -----
        This function requires a lognormal galaxy catalog. If the catalog does not exist, it will generate it using lognormal simulations.


        Assigns a single redshift to the entire box.
        Adds the columns 'cosmo_redshift', 'RSD_redshift',
        'RSD_redshift_factor', 'RSD_Position' to self.cat.

        Returns
        -------
        None

        Notes
        -----
        This function requires a lognormal galaxy catalog.
        If the catalog does not exist, it will generate it using lognormal simulations.


Log_10 of the luminosity function.


        Randomly assigns luminosities to the galaxies following the luminosity function.
        Adds the column 'luminosity' to self.cat.

        Returns
        -------
        None

        Notes
        -----
        This function requires a lognormal galaxy catalog.
        If the catalog does not exist, it will generate it using lognormal simulations.


        Converts luminosity to flux in the galaxy catalog.
        Accounts for cosmological effects, not for peculiar velocities.
        Adds the column 'flux' to self.cat.

        Parameters
        ----------
        luminosity : str, optional
            Key name of the luminosity column in the catalog, by default "luminosity".

        Returns
        -------
        None

        Notes
        -----
        This function requires the galaxies to have assigned redshifts.
        If the redshifts are not assigned, they will be assigned using either a single redshift or redshift along the LOS.


        Assigns whether each galaxy was detected or not given the flux limit (min_flux)
        of the observation.

        Parameters
        ----------
        min_flux : astropy quantity, nd-array of floastropy quantities, or function of redshift, optional
            Flux limit of the (mock) observation above which galaxies are detected.
            If a function, it represents the flux limit as a function of redshift.
            Units of flux (erg/s/cm**2) required.
            Either `min_flux` or `limit_ngal` must be provided.
        limit_ngal : float or function of redshift, optional
            Given number of galaxies per unit comoving volume above which galaxies are detected.
            If a function, it represents the number density limit as a function of redshift.
            Either `min_flux` or `limit_ngal` must be provided.

        Returns
        -------
        None

        Notes
        -----
        This function requires the galaxies to have assigned fluxes. If the fluxes are not assigned, they will be computed using the `assign_flux()` method.
        If neither min_flux nor limit_ngal are given, all galaxies will be detected.


        Saves the galaxy catalog, either all galaxies or only detected or undetected galaxies,
        as an h5 file.

        Parameters
        ----------
        cat : LognormalCatalog object, optional
            Which catalog to save. Default: None. If None, use self.cat.
        keys : list of strings, optional
            Which columns to save of the catalog. Options: Position, RSD_Position, Velocity, VelocityOffset,
            cosmo_redshift, RSD_redshift, luminosity, flux, detected.
            Default: Position and Velocity.
        filename : str, optional
            Name of the output catalog file. If it contains a {}, it will be filled with the galaxy_selection argument.
            Default: '{}_galaxies.h5'.
        galaxy_selection : str, optional
            Whether to save all, detected, or undetected galaxies. Options: 'all', 'detected', 'undetected'.
            Default: 'detected'.

        Raises
        ------
        ValueError
            If galaxy_selection is not 'all', 'detected', or 'undetected'.

        Returns
        -------
        None

        Notes
        -----
        This function saves the specified columns of the galaxy catalog as an h5 file.
        The saved file can be opened using h5py and converted into an astropy Table:
        >>> import h5py
        >>> from astropy.table import Table
        >>> with h5py.File(filename, 'r') as F:
        >>>     tab = Table(F)


        Generates the mock intensity map obtained from Cartesian coordinates.
        It does not include noise.

        Parameters
        ----------
        position : str, optional
            The column name in the catalog representing the position of galaxies.
            Options: "RSD_Position" (redshift space), "Position" (real space).
            Default: "RSD_Position".
        redshift : str, optional
            The column name in the catalog representing the redshift of galaxies.
            This is used to calculate the intensity and irrelevant for tracer "n_gal".
            Options: "cosmo_redshift" (without RSD), "RSD_redshift" (which RSD).
            Default: "cosmo_redshift".
        tracer : str, optional
            The tracer to generate the intensity map for.
            Options: "intensity", "n_gal".
            Default: "intensity".
        luminosity : str, optional
            The column name in the catalog representing the luminosity of galaxies.
            Options: "luminosity".
            Default: "luminosity".

        Returns
        -------
        field : ndarray
            The generated intensity map.

        Raises
        ------
        ValueError
            If `tracer` argument is not one of the allowed options.


        Calculate the comoving distance corresponding to the
        LOS smoothing length.

        Returns
        -------
        sigma_par : Quantity
            Comoving distance corresponding to the
            LOS smoothing length.

        Notes
        -----
        This function calculates the comoving distance corresponding to the smoothing length along the line-of-sight (LOS)
        direction. The calculated value depends on the specified rest frame wavelength (lambda_restframe)
        or frequency (nu_restframe), the LOS direction, and the cosmological parameters.


        Calculate the comoving distance corresponding to the angular smoothing length.

        Returns
        -------
        sigma_perp : Quantity
            Comoving distance corresponding to the angular smoothing length.

        Notes
        -----
        This function calculates the comoving distance corresponding to the smoothing length perpendicular to the line-of-sight (LOS)
        direction. The calculated value depends on the specified redshift, angular diameter distance, angular smoothing length,
        and the cosmological parameters.


        Returns the mean intensity of the mesh in units of mean intensity.
        As soon as it is calculated once, it is saved.


        Calculates the galaxy number density mesh based on the specified position of galaxies.
        The parameter self.galaxy_selection_function['n_gal'] decides whether to use
        detected, undetected, or all galaxies.

        Parameters
        ----------
        position : str, optional
            The column name in the catalog representing the position of galaxies.
            Options: "RSD_Position" (redshift space), "Position" (real space)
            Default: "RSD_Position".

        Returns
        -------
        field : ndarray
            The generated galaxy number density mesh.


        Perform binning of the power spectrum.

        Parameters
        ----------
        pkspec : ndarray
            The power spectrum mesh to be binned.
        return_nmodes: bool
            Set to true if you want to have the number of modes in each bin returned.
            Default: False.

        Returns
        -------
        mean_k : ndarray
            The mean wavenumber in each bin.
        monopole : ndarray
            The monopole component of the power spectrum.
        quadrupole : ndarray
            The quadrupole component of the power spectrum.


        Prepare the intensity map Fourier transform delta_I for the power spectrum calculations.
        Applies normalization, adds noise, subtracting the mean intensity per redshift,
        and applies the mask.

        Parameters
        ----------
        sky_subtraction : bool
            Flag indicating whether to perform sky subtraction.

        Returns
        -------
        prepared_intensity_mesh_ft : :class:`pyfftw.interfaces.numpy_fft.fftn.FFTWArray`
            The prepared intensity map in Fourier space after applying the necessary transformations.


        Prepare the galaxy number density Fourier transform delta_g for the power spectrum calculations.
        Performs normalization, subtracts the mean
        galaxy number density per redshift, and applies an observation mask.

        Returns
        -------
        prepared_n_gal_mesh_ft : :class:`pyfftw.interfaces.numpy_fft.fftn.FFTWArray`
            The prepared galaxy number density map in Fourier space after applying the necessary transformations.

        Notes
        -----
        This function prepares the galaxy number density map for analysis by performing normalization, subtracting the mean
        galaxy number density per redshift, and applying an observation mask.


Prepares the dimensionless k values for the power spectrum calculations.


        Compute the power spectrum monopole and quadrupole of the map.

        Parameters
        ----------
        tracer : str, optional
            Which power spectrum to compute.
            Options: 'intensity', 'n_gal', 'cross', 'sky_subtracted_intensity', 'sky_subtracted_cross'.
            Default: 'intensity'.
        save : bool, optional
            Whether to save the computed power spectrum to a file. Default: False.

        Returns
        -------
        mean_k : array_like
            Array of mean wavenumbers.
        monopole : array_like
            Array of monopole power spectrum values.
        quadrupole : array_like
            Array of quadrupole power spectrum values.


        Calculates the mean intensity or the mean galaxy number density that we would expect
        at a given redshift of a given galaxy population (either all or detected/undetected galaxies).
        We use the integrals

        .. math:: \\bar{\\rho}_L(z) = \\int_{L_\\mathrm{min}}^{L_\\mathrm{max}} dL\, \\frac{\mathrm{d}n}{\mathrm{d}L} L
        .. math:: \\bar{I}_\\lambda(z) = \\frac{c \\bar{\\rho}_L(z)}{4 \\pi \\lambda_0 H(z) (1+z)^2}
        and

        .. math:: \\bar{n}_\\mathrm{gal}(z) = \\int_{L_\\mathrm{min}}^{L_\\mathrm{max}} dL\, \\frac{\\mathrm{d}n}{\\mathrm{d}L}

        where

        ``Lmin = self.Lmin`` for all galaxies or undetected galaxies
        or ``Lmin = self.min_flux(z) * 4 * np.pi * D_L**2`` for detected galaxies
        and
        ``Lmax = self.Lmax`` for all galaxies or detected galaxies
        ``Lmax = self.min_flux(z) * 4 * np.pi * D_L**2`` for undetected galaxies.

        If min_flux is a mesh with the same size as N_mesh,
        it will return the mean of the intensity/n_gal mesh depending on the specified tracer.

        Parameters
        ----------
        redshifts: array (n,)
            List/array of redshifts to be computed.
        galaxy_selection: str
            Which galaxies to use: 'all', 'detected', or 'undetected'. Default: 'all'.
        tracer: str
            Whether to calculate the mean intensity ('intensity') or mean galaxy number density ('n_gal').
            Default: 'intensity'.

        Returns
        -------
        mean_intensity_per_redshift: Quantity array (n,)
            List/array of the mean intensity per redshift (if tracer=='intensity') or mean galaxy number density
            per redshift (if tracer=='n_gal'). Same shape as input redshifts array.


Broadcasts the 1D mean_n_gal_per_redshift array to the 3D mesh (cached).


        Runs the entire simulation and analysis pipeline.

        Parameters
        ----------
        skip_lognormal : bool, optional
            Skip the lognormal simulation and use a pre-generated catalog. Default: False.
        save_meshes : bool, optional
            Save the generated LognormalIntensityMock instance to a file and the galaxy catalog to another file. Default: False.
        save_results : bool, optional
            Save the computed power spectra to a file. Default: True.

        Notes
        -----
        This function performs all the necessary steps to run the simulation and analyze the results.
        It includes
          * the lognormal simulation,
          * catalog loading,
          * redshift assignment,
          * luminosity and flux assignment,
          * selection function application,
          * painting intensity and galaxy meshes,
          * and computing power spectra.

        If `skip_lognormal` is False (default), the lognormal simulation and catalog loading will be performed.
        Then, redshift assignment, luminosity assignment, flux assignment, and selection function application will be executed.

        The position variable used for painting the intensity and galaxy meshes depends on the RSD (Redshift-Space Distortion) setting self.RSD.
        If RSD is enabled, "RSD_Position" is used, and if RSD is disabled, "Position" is used.

        The intensity and galaxy meshes will be painted if the corresponding power spectra are enabled in the self.run_pk setting.

        If `save_meshes` is True, the generated intensity and galaxy meshes will be saved to file.

        If `save_results` is True (default), the computed power spectra will be saved to file.


Sample data for a given hour


Returns a dataframe containing the start and end dates of periods of missing data,
    and the duration of the missing period.

    s : series to evaluate

    Returns
    -------
    start date, end date and duration of missing periods as DataFrame


Returns a snow depth file from a MOSAiC dataset id


Calculates the distance along a transect

    :x0: x in local cordinates
    :y0: y in local coordinates


Infers surface type from snow and pond depths.

    Args:
        df : (pandas.DataFrame) containing snow and pond depths

    returns: pandas.Series containing -1, 1 or 2 meaning pond, snow or bare ice surface

    Notes: if pond and snow are both > 0, then np.nan is used.


Loads raw files containing combined snow depth and ice
       thickness transect data.

    Args:
        fp : (str or Path object) filepath to combined file

    Returns: pandas.Dataframe

    Notes:
        1. Some files have trailing ',' in first row, which is interpretted
           by pandas as an extra column and given "Unnamed: column_number".
           This is identified and removed.
        2. Column names have spaces and units in parentheses and are in
           title case, e.g "Snow Depth (m)".  columns are made lower case,
           spaces are replaced with "_" and parentheses removed.


Loads raw files containing combined snow depth and ice
       thickness transect data.

    Args:
        fp : (str or Path object) filepath to combined file

    Returns: pandas.Dataframe


Adds ice_thickness_m column following Itkin et al (2023).  A ice_thickness_flag
    column is also added.

    Args:
        df : (pandas.DataFrame) Dataframe containing raw combined data
        quiet : (boolean) silence warnings !!!Not Implemeneted!!!

    if ice_thickness_18khz_ip_m in df:
        ice_thickness_m = df.ice_thickness_18khz_ip_m
        ice_thickness_flag = 1
    elif ice_thickness_f18325hz_hcp_i_m in df:
        ice_thickness_m = df.ice_thickness_f18325hz_hcp_i_m
        ice_thickness_flag = 2
    else:
        ice_thickness_m = np.nan
        ice_thickness_flag = 0

    returns None


Sets melt_pond_depth_m to zero if <= 0 or add column if not in raw dataframe

    Args:
        df : (pandas.DataFrame) dataframe containing raw data

    Returns: None - assigned inplace


Sets snow depth to 0. if <= 0. or adds column if not in dataframe

    Args:
        df : (pandas.DataFrame) raw combined dataframe

    Returns: None - assigned inplace

    Notes: If snow_depth_m column not present a column is added and assigned np.nan


Returns True if essential columns are in df


Parses raw combined snowdepth and ice thickness transect data files

    Args:
        fp: (str or pathlb.Path object) filepath to combined file

    Returns: pandas.DataFrame see Notes for structure

    Notes:
    Rows are indexed by datetime.

    Columns are: lon, lat, local_x, local_y, ice_thickness_m, ice_thickness_flag,
                 snow_depth_m, melt_pond_depth_m, surface_type, transect_distance_m

    All other columns are dropped.

    Data for ice_thickness_m are selected following Itkin et al (2023).  Data in
    the column ice_thickness_18khz_ip_m if this column exists.  If not, data in
    ice_thickness_f18325hz_hcp_i_m is used.  If neither of these columns is found
    ice_thickness_m is assigned np.nan.

    melt_pond_depth_m is set to zero for pond depths <= 0.


Loads transect metadata files

    Arguments
    ---------
    polar_day : only return transects with incident solar radiation greater than 0.
                (Default: True)
    dropna : if forcing data is not available, drop rows (Default: True)

    Returns
    Pandas Dataframe containing transect id and forcing data


Returns an irradiance in W per m2 as quanta per m2 per s for underice light

    Parameter
    ---------
    irradiance : irradiance in W/m2

    Returns
    -------
    quantum measure of irrandiance as micromoles photons/m2/s

    The quantum measure of radiative flux density for PAR is
    given as:

    $$
    Q = \frac{1}{hc}\int_{400 nm}^{700 nm} I(\lambda) \lambda d\lambda
    $$

    where $h$ is the Planck constant and $c$ is the speed of light.

    The conversion factor for broadband SW used here is from the Greenedge campaign

    Q_PAR / F_PAR = 4.44 +/- 0.005 micromoles photons per J


Returns an irradiance in W per m2 as quanta per m2 per s for underice light

    Parameter
    ---------
    irradiance : irradiance in W/m2

    Returns
    -------
    quantum measure of irrandiance as micromoles photons/m2/s

    The quantum measure of radiative flux density for PAR is
    given as:

    $$
    Q = \frac{1}{N_A hc}\int_{400 nm}^{700 nm} I(\lambda) \lambda d\lambda
    $$

    where $h$ is the Planck constant and $c$ is the speed of light.

    The conversion factor for broadband SW used here is from Morel and Smith

    Q_PAR / F_PAR = 4.44 +/- 0.005 micromoles photons per J

    This comes from the Green water estimate in Table 2 of Morel and Smith (1974),
    which gives the conversion factor in units quanta / J.  Dividing by the
    Avogadro constant (6.022e23) gives the CF in micromoles per J


Converts radiative flux to PAR based on whether ice is present or not

    :df: pandas.DataFrame created in seaicert_mp

    :returns: modified dataframe


Runs SeaIceRT for a single instance

    Parameters
    ----------
    timestamp : datetime
    latitude : latitude (-90.,90.)
    snow_depth : snow depth in meters
    pond_depth : pond depth in meters
    ice_thickness : ice thickness in meters
    surface_temperature : surface (skin) temperature in Kelvin
    air_temperature: float : 2m air temperature in Kelvin
    snow_grain_radius : effective snow grain radius in um (default = 180 um)

    Returns
    -------
    TBD


Puts results into pandas dataframe


Runs the SeaIceRT model for multiple points on a transect.

    Parameters
    ----------
    df : Dataframe containing day of year, latitude, snow depth in m, pond
               depth in m, ice_thickness in meters.  Optionally skin temperature
               and 2 m air temperature may be in the DataFrame.  If these are not
               present, the default values are used (effectively 273.15).

    Returns
    -------
    pandas.DataFrame containing shortwave absorbed flux absorbed by ocean,
    total radiation absorbed by ocean, albedo and surface shortwave flux


Plots a thickness profile from GEM-2 and Magnaprobe data


Returns the snow or ice freeboard height above local sea level

    Parameters
    ----------
    x : pandas.DataFrame containing
        snow depth in meters
        pond depth in meters
        thickness in meters

    density_ice : density pf ice (default 915 kg/m3 from Petty et al )
    density_snow : density of snow (default 300 kg/m3)
    density_water : density of freshwater (1000 kg/m3)

    Returns
    -------
    Pandas Series with surface height (freeboard) above local sea level


Generates plots of reformatted transect data


Follows the parse and write new files workflow in parse_data_summary_spreadsheet


Checks number of header columns match number of data columns

    Assume files are csv


Reads combined file for reformatting


Checks for a missing comma between header column names

    In some files Ice Thickness columns are missing a comma delimiter

    e.g. "Ice Thickness f1525Hz_hcp_i (m), Ice Thickness f1525Hz_hcp_q (m) Ice Thickness f5325Hz_hcp_i (m),"


Converts header to lower case, removes brackets and replaces
    whitespace in header


Write a new file with reformated data


Checks number of data fields matches number of column headings.

    Assumes header is correct


Fixes formatting issues in combined Magnaprobe files

    Parameters
    ----------
    fp : path to input file
    outfp : path to write reformatted file
    verbose : set output to verbose

    Returns
    -------
    None


Returns date, leg, activity, and location info from filename


Modifies filename to contain only characters that
    are in the Portable Filename Character set.

    A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
    a b c d e f g h i j k l m n o p q r s t u v w x y z
    0 1 2 3 4 5 6 7 8 9 . _ -


Load data for a given MOSAiC met site

    Parameters
    ----------
    site : name of site.  One of tower, asfs30, asfs40, asfs50

    Returns
    -------
    xarray.Dataset containing metdata


Extracts variables for transect date range and
    return as pandas dataframe.


Returns a file path for the json sidecar file
    that contains the date for the data in the netcdf file.
    This is found from the netcdf filename.

    Parameters
    ----------
    fname : name of file
    dout : path to store JSON file

    Returns
    -------
    Path for JSON file


Generate a single json sidecar file.

    Files are written to a temporary directory.

    Parameters
    ----------
    fname : path of file to be kerchunked
    outdir : directory path to save json files


Generate single JSON reference files for a list of files

    Parameters
    ----------
    filelist : list of files to create JSON reference files using kerchunk
    outdir : path to save files
    n_jobs : number of threads to use

    Returns
    -------
    List of filepaths to JSON reference files


Generates a multizarr json

    Parameters
    ----------
    jsonlist : list of filepaths for single jsons to combine
    multijson : path for multizarr json

    Returns
    -------
    None


Generates multizarr json files for data from a MOSAiC met site

    Parameters
    ----------
    site : identifier for MOSAiC met site.  tower, asfs30, asfs40, asfs50
    jsonname : filepath for multizarr json file

    Returns
    -------
    None


Loads a multizarr file


Loads filled skin temperature


Returns a single dataframe of met data


Extracts variables for transect date range and
    writes forcing file to csv

    Arguments
    ---------
    transect_file : Cleaned MOSAiC transect file
    met_dataset : filled me data
    verbose : print verbose output

    Returns
    -------
    None


Fixes the transect path to ensure consistency


Converts filename to POSIX fully portable format

    allowed char set A-Z a-z 0-9 . _ -


Makes sure date, campaign and activity fields are same


Parses and compares fields in activity directory path and transect filenames

    :path: pathlib.Path object

    :returns: dict containing file attributes


Returns a new file path


Checks for out-of-expected range values.  If fix=True, set out of range
    values to fill_value.

    Args:
        series : (pandas.Series) series of values to check
        min_value : (scalar) minimum acceptable values
        max_value : (scalar) maximum acceptable values
        fix : (bool) if True replace out of range values with fill_value
        fill_value : (scalar) value with which to replace out of range values.
            Default is np.nan.

    Returns: same type as caller.

    Notes: raises UserWarning if out of range values are found


Prints min and max of dataFrame for all columns


Checks that file has constent structure and values


Renames filepaths and reformats data files


Returns activity ID and location


Returns metadata for one file


Creates summary table of transects


Parses provided file for doc strings, returning a header that starts with "//!" and any blocks that start with "/*!"


Searches in ATS_SRC_DIR and AMANZI_SRC_DIR for filename, then reads that.


Parses a template, replacing with filename docs as provided.


Creates a ColorMap with warm colors above zero, and cold colors below.


Rounds a time to the nearest Month (day 1)

    i.e. Jan 2, 10:00 am --> Jan 1
         Jan 29, 1:00 pm --> Feb 1


Tiles windows like matplotlib


Generic creation of pseudocolor


Generic creation of a single contour without a legend


Loads source files for subsurface and potentially surface.


A generic set of sources.


Adds a window to VisIt and makes it active


Simplified interface to create standard pseudocolors


Simplified interface to create standard pseudocolors on the surface.


Simplified interface to create standard pseudocolors on the snow surface.


Adds a plot of subsurface pressure


Adds a plot of subsurface temperature


Adds a plot of surface temperature


Adds a plot of snow temperature


Adds a plot of surface ponded depth


Draw the plots


Gets an enumerated list of count independent colors.


Create a map from value to color given a colormap.

    Typical Usage:
      >>> # plots 11 lines, with color scaled by index into jet
      >>> mapper = cm_mapper(vmin=0, vmax=10, cmap=matplotlib.cm.jet)
      >>> for i in range(11):
      ...     data = np.load('data_%03d.npy'%i)
      ...     plt.plot(x, data, color=mapper(i))
      ...
      >>> plt.show()


Create a map from value to color, using a colormap that varies alpha in a given color.


Convert string-form list of doubles into list of doubles.


Argparse validator for a directory.


Argparse validator for slices.


Plots the column data given directories and a layout.


The filename for an HDF5 data filename formatter


Argparse validator for an HDF5 mesh filename formatter


(Re-)loads the list of cycles and times.


Filter based on the index into the current set of cycles.

        Note that filters are applied sequentially, but can be undone by
        calling load_times().

        Parameters
        ----------
        indices : one of:
          * int : limits to the ith cycle.
          * list(int) : a list of specific indices
          * slice object : slice the cycle list


Filter the vis file based on cycles.

        Note that filters are applied sequentially, but can be undone by
        calling loadTimes().

        Parameters
        ----------
        cycles :
          One of:
          * int : limits to one specific cycle
          * list(int) : a list of specific cycles


Filter the vis file based on cycles.

        Note that filters are applied sequentially, but can be undone by
        calling load_times().

        Parameters
        ----------
        cycles :
          One of:
          * int : limits to one specific cycle, or the last cycle if -1.
          * list(int) : a list of specific cycles
          * slice object : slice the cycle list
        times : optional
          One of:
          * float : a specific time (within eps in seconds).
          * list(float) : a list of specific times (within eps in seconds).
        eps : float
          Tolerance for defining times, in seconds.  Default is 1.


Forms a variable name.

        Parameters
        ----------
        vname : str
          Base variable name, e.g. 'pressure'

        Returns
        -------
        variable_name : str
          Variable name mangled like it is used in Amanzi/ATS.  Something like
          'DOMAIN-vname.cell.0'


Load and reorder centroids and volumes of mesh.

        Parameters
        ----------
        cycle : int, optional
          If the mesh deforms, the centroids may change.  If not provided, gives
          the first cycle's value.
        order : list(str), optional
          See arguments to structuredOrdering().  If provided, this
          reorders the data, and all future get() and getArray() calls will
          return data in this order.
        round : int
          Decimal places to round centroids to.  Supports sorting.


Load a mesh into 2D polygons.


Plot multiple lines, one for each slice in time, as a function of coordinate.

        Parameters
        ----------
        varname : str
           The variable to plot


Reads a mesh nodal coordinates and connectivity.

    Parameters
    ----------
    directory : str, optional
      Directory to read mesh files from.  Default is '.'
    filename : str, optional
      Mesh filename. Default is the Amanzi/ATS default name, 'ats_vis_mesh.h5'
    key : str, optional
      Key of mesh within the file.  This is the cycle number, defaults to the
      first mesh found in the file.

    Returns
    -------
    elemtype : str
      One of 'QUAD', 'PRISM', 'HEX', or 'TRIANGLE' if typed mesh, or 'MIXED' if
      mesh has more than one types including 'NSIDED' and 'NFACED'
    coords : np.ndarray
      2D nodal coordinate array.  Shape is (n_nodes, dimension).
    conn : list[np.1darray]
      List of length n_elem, each entry is a list of the nodal indices of that
      element.


Given mesh info that is a bunch of HEXes, make polygons for 2D plotting.


Reads and calculates mesh element centroids.

    Parameters
    ----------
    directory : str, optional
      Directory to read mesh files from.  Default is '.'
    filename : str, optional
      Mesh filename. Default is the Amanzi/ATS default name, 'ats_vis_mesh.h5'
    key : str, optional
      Key of mesh within the file.  This is the cycle number, defaults to the
      first mesh found in the file.
    round : int, optional
      Number of decimals to round to -- this avoids roundoff issues in sorting.
      Default is 5.

    Returns
    -------
    centroids : np.ndarray
      2D nodal coordinate array.  Shape is (n_elems, dimension).


Reorders coordinates in a natural ordering for structured meshes.

    This generates a mapping from an unsorted, unraveled list of
    elements to either a (if shape is None) sorted, unraveled list of
    elements or a (if shape is provided) len(order)+1 dimensional
    array of elements that can be used for structured plotting,
    sorting output, post-processing, and more.

    Parameters
    ----------
    coordinates : np.ndarray
      The 2D array of coordinates, shape (n_coordinates, dimension).
    order : list
      An ordering given to sort(), where headings are 'x', 'y', and potentially
      'z' for 3D meshes.  Note omitted headings always go first.  See below for
      common examples.  May be omitted if columnar == True
    shape : list, optional
      If provided, a list of the same length as order, providing the
      number of elements in that dimension.
    columnar : bool, optional
      If True, this sets order = ['x', 'y', 'z'] and shape is guessed by
      assuming (x,y) coordinates are constant in map-view and cells
      are vertical columns, a common Amanzi/ATS mesh layout.

    Returns
    -------
    ordering : List[str]
      Order used to sort, e.g. ['x', 'y']
    ordered_coordinates : np.ndarray
      The re-ordered coordinates, shape (n_coordinates, dimension).
    map : np.ndarray(int)
      Indices of the new coordinates in the old array.  If shape is
      not provided, this is a 1D array and
        ordered_coordinates[i] == coordinates[map[i]]
      If shape is provided or guess_shape is True, this is a
      len(shape)+1-D array and:
        ordered_coordinates[i,...,k] == coordinates[map[i,...,k]]

    Examples
    --------

    Sort a column of 100 unordered cells into a 1D sorted array.  The
    input and output are both of shape (100,3).

      > order, ordered_centroids, map = structuredOrdering(centroids, list())

    Sort a logically structured transect of size NX x NY x NZ =
    (100,1,20), where x is structured and z may vary as a function of
    x.  Both input and output are of shape (2000, 3), but the output
    is sorted with each column appearing sequentially and the
    z-dimension fastest-varying.  map is of shape (2000,).  The
    returned order is ['z',].

      > order, ordered_centroids, map = structuredOrdering(centroids, ['z',])

    Do the same, but this time reshape into a 2D array.  Now the
    ordered_centroids are of shape (100, 20, 3), and the map is of
    shape (100, 20).  The returned order is ['z', 'xy'].

      > order, ordered_centroids, map = structuredOrdering(centroids, ['z',], [20,])

    Do the same as above, but detect the shape.  This works only
    because the mesh is columnar. The returned order is ['z', 'xy'].

      > order, ordered_centroids, map = structuredOrdering(centroids, columnar=True)

    Sort a 3D map-view "structured-in-z" mesh into arbitrarily-ordered
    x and y columns.  Assume there are 1000 map-view triangles, each
    extruded 20 cells deep.  The input is is of shape (20000, 3) and
    the output is of shape (1000, 20, 3).  The returned order is ['z', 'xy'].

      > order, ordered_centroids, map = structuredOrdering(centroids, columnar=True)

    Note that map can be used with the reorder() function to place
    data in this ordering.


Re-orders values and arrays according to a mesh reordering.

    Parameters
    ----------
    data : np.ndarray
      The data, i.e. provided by VisFile.get() or VisFile.getArray()
    map : np.ndarray
      A reordering of indices to remap the data based on a map
      returned by structuredOrdering()

    Returns
    -------
    data : np.ndarray
      The re-ordered data.


Reads an array, called MixedElements in the HDF5 file, to get conn


Reads the element at location i,

    returns etype, nodeids, new_i

    Note this is called dirty because it does not _properly_ deal with
    NFACED objects, but instead just returns a set of unique nodes
    that are in the element (i.e. it has no concept of faces).


Plots lines by color.


Checks that data can be cast in years and stacks it into a 365 x NYEAR array.


Stacks years and generates a single, smooth year.

    Assumes input met data is daily data, and in 365-day year format such that
    len(met)%365 == 0.


Stacks years and generates a single averaged precip rate for snow and rain.


From raw years, generate a single year of spinup data.


Accepts a dictionary of ATS data and writes it to HDF5 file.


Cleans a line and splits off the VerboseObject header and remainder of the line


Reads a file, and returns a list of good and bad timesteps.

    Each are a list of 3-tuples: (step number, time of step, dt)


Adds legends, labels, limits.


Plot the data.


Writes the data to a file for future reading


Reads a .npz file


Plot data provided as a (keys,times,dat) tuple on a set of axes.


Gets file for a single year and single variable.

    Parameters
    ----------
    var : str
      Name the variable, see table in the class documentation.
    year : int
      A year in the valid range (currently 1980-2018)
    bounds : [xmin, ymin, xmax, ymax]
      Collect a file that covers this shape or bounds in lat/lon.

    Returns
    -------
    filename : str
      Path to the data file.


Calls the DayMet Rest API to get data and save raw data.


Accepts a numpy named array of DayMet data and returns a dictionary ATS data.


Unit normal vector of plane defined by points a, b, and c


Area of a polygon given as a list of numpy length 3 arrays.


Reads the raw plist from the file into a string


Strips a bunch of extra stuff trilinos adds.


Pulls simulation output into structured 2D arrays for transect-based, (i,j) indexing.

    Input:
      varnames       | A list of variable names to pull, e.g.
                     |  ['saturation_liquid', 'saturation_ice'], or a single variable
                     |  name, e.g. 'saturation_liquid'
      keys           | Indices of timesteps to pull.  Either an int (i.e. 0, -1, etc)
                     |  for the kth timestep, or a list of ints, or 'all'.
      directory      | Directory of the run.  Defaults to '.'
      filename       | Filename of the run.  Defaults to 'visdump_data.h5'
      mesh_filename  | Filename of the mesh.  Defaults to 'visdump_mesh.h5'
      coord_order    | Order of the transect coordinates.  Defaults to ['x','z'].  The
                     |  mesh is sorted in this order.
      deformable     | Is the mesh deforming?
      return_map     | See return value below.

    Output:
      Output is an array of shape:
      ( len(varnames+2), len(keys), n_cells_coord_order[0], n_cells_coord_order[1] )

      data[0,0,:,:] is the coord_order[0] centroid
      data[1,0,:,:] is the coord_order[1] centroid
      data[i+2,k,:,:] is the ith varname data at the kth requested timestep, sorted in
                      the same way as the centroids.

      Note that the data is re-ordered in INCREASING coordinate, i.e. bottom to top in z.

      If return_map is True, then returns a tuple, (data, map) where
      map is a (NX,NZ) array of integers specifying which global id
      corresponds to the (i,j) cell.  This is useful for mapping input
      data back INTO the unstructured mesh.

    Example usage:
      Calculate and plot the thaw depth at step 5.

      // Pull saturation ice -- TD is where sat ice = 0."
      data = transect_data(['saturation_ice', 5)

      // x coordinate for plotting
      x = data[0,0,:,0]

      // for each column, find highest z where sat_ice > 0.
      td_i = np.array([np.where(data[2,0,i,:] > 0.)[0][-1] for i in range(data.shape[2])])

      // now that we have an index into the highest cell with ice, determine td as the
      // mean of the highest cell with ice and the one above that.  Note this assumes
      // all columns have some thawing.
      td_z = np.array( [  (dat[1,0,i,td_i[i]] + dat[1,0,i,td_i[i+1]]) / 2.
                              for i in range(len(td_i)) ] )

      plt.plot(x, td_z)


Draws a dataset on an ax.


Prints a list of recognized variable names


Spatially integrates intensive data over the domain at timestep i.

        If scale_by_density is set, this additional multiplies by the molar density.


evaporation in [mol/s]:

        Note that some simulations may not include surface energy balance!


precipitation in [mol/s]


runoff [mol/s] in the interval (i,i+1).

        Calculated via a surface water mass balance:

        dWC/dt = precip - infiltration - runoff

        As a result this is an approximation, and may be wrong for a variety of reasons:
          - assumes visualization is at least as frequent as precip data
          - assumes infiltration is relatively smooth

        If any of these caveats affects you, you might find that introducing a
        runoff observation is a better choice than using this function.


transpiration in [mol/s] is in the negative direction (it is a sink)


seepage [mol/s] in the interval (i,i+1).

        Calculated via a subsurface water mass balance:

        dWC/dt = infiltration - transpiration - seepage

        As a result this is an approximation, and may be wrong for a variety of reasons:
          - assumes visualization is at least as frequent as precip data
          - assumes infiltration is relatively smooth

        If any of these caveats affects you, you might find that introducing a
        runoff observation is a better choice than using this function.


Plots the mass balance for a given simulation.


Decorates the axes with labels


This is the wilting point coefficient.


Main access point to data.


Read one file, write another


Read one simulation set, write another.


Returns a set of coordinates of nodes in the mesh, along with a elemental conection list.


Gets centroids of cells in the mesh.


Returns centroids of a structured mesh ordered in the natural ordering.
    order: a list given to numpy sort(), headings are "x","y","z".
           ["x","z"] (default) gives coordinates in z-fastest


Returns the volume of each cell.
    Note this is the cell volume in 3D or the face area in 2D surface mesh.


Generates the DayMet Rest API URL.


Checks that these are valid dates for use with DayMet


Stacks years and generates a total averaged precip rate for snow and rain.


Process the command line arguments and return them as a dict.


Build up the run command and run the job as a subprocess.


Reads the stdout of the run to get timestep history then writes them to hdf5 file


Parses the output of the run to collect the cycles that were written.


Adds the needed magic to a new xml file.


Opens the config file, creating it if need be, and appends the test.


Helper function to pull a version number from an executable.

    For now this is hard-coded and assumes standard ATS locations,
    which is VERY fragile, and may even provide incorrect info.
    This needs to be fixed to take the output of ats --version
    (which doesn't yet work, see ats ticket #12


Run the test.


Check the test results against the gold standard


        Update the gold standard test results to the current
        output. Both the current regression output and a gold file
        must exist.


        Test the output from the run against the known "gold standard"
        output and determine if the test succeeded or failed.

        We return zero on success, one on failure so that the test
        manager can track how many tests succeeded and failed.


Check that output hdf5 file has not changed from the baseline.


Parse crit_name for name,tag,entity,dof


Join split name back into single string


Custom search for split_name target in an iterable list of potential matches


Compare the values using the appropriate tolerance and criteria.


        Our preferred order for selecting test criteria is:
        (1) test data section of the config file
        (2) config-file wide defaults
        (3) hard coded class default


        Validate the tolerance string from a config file.

        Valid input configurations are:

        * key =
        * key = default
        * key = no
        * key = tolerance type
        * key = tolerance type [ min_threshold value [ max_threshold value ] ]

        where the first two use defaults, the third turns the test
        off, and the last two specify the tolerance explicitly, where
        min_threshold and max_threshold are optional


Run the test and check the results.


Recheck the regression files from a previous run.


Run the tests and create new gold files.


Run the tests and update the gold file with the current output


Add the current test status to the overall status for the file.


        Read the configuration file.

        Sections : The config file will have known sections:
        "suites", "default-test-criteria".

        All other sections are assumed to be test names.


        Check that the list of suites or tests passed from the command
        line are valid.


    Try to generate a list of configuration files from the commandline
    options.


Run some sanity checks on the commandline options.


Try to verify that we have something reasonable for the executable


Try to verify that we have something reasonable for the mpiexec executable


Overall summary of test results


Finds the last-in-time logfile from the LOGS directory.


    Given a logfile, searches for all failed tests.

    Failed tests will include an entry of the form:

    FAIL : TESTNAME : ...

    or

    ERROR : TESTNAME : ...


Clips a line to a rectangular area.

    This implements the Cohen-Sutherland line clipping algorithm.  left,
    top, right and bottom denote the clipping area, into which the line
    defined by x1, y1 (start point) and x2, y2 (end point) will be
    clipped.

    If the line does not intersect with the rectangular clipping area,
    four None values will be returned as tuple. Otherwise a tuple of the
    clipped line points will be returned in the form (cx1, cy1, cx2, cy2).


Generates an evaluator whose class is [name]Evaluator and model is [name]Model.

    This evaluator/model live in [namespace] and have key (for use in input spec) [descriptor].
    It evaluates the seconadary variable based on [dependencies], using [parameters]
    in the model.

    Inputs:
      name: name of the class, must meet C++ standards for class names

      namespace: containing context of the class, must meet C++ standards for namespaces

      descriptor: short (several word) string used in the input spec to refer to this evaluator

      my_key: key identifier of the variable to be evaluated, in base form (note this may be
              modified by a domain, etc, but is the base method used in the model to evaluate
              the model), e.g. "density"

      dependencies: list of strings or tuples, strings are the key identifier of the dependency,
                     or a tuple with (key identifier, variable name) where variable name is a
                     shorter version of the identifier used in argument lists, etc (must meet
                     C++ variable standards)

      parameters: list of tuples (name, type, descriptor) of parameters to be used by the model,
                  where name is the (C++ standard) variable name, type is one of {double, int,
                  bool, string, Array(double), ...} and descriptor is short string used in
                  pulling the value from the input spec.

      directory: directory where output files are created

    Outputs:
      writes files: [name]_evaluator.hh
                    [name]_evaluator.cc
                    [name]_evaluator_reg.hh
                    [name]_model.hh
                    [name]_model.cc


Converts an xml object, in-place


Converts manning coeficients from boundary face and cell back to just cell


initial time step' --> 'initial time step [s]


Generator over all PKs that have a time integrator list


[kg/m^3] --> [kg m^-3] to be consistent with all other units in ATS


Converts relative humidity to vapor pressure.


generic update calls all needed things


Find and revert the timestep from file option, moving it to the cycle driver list.

    Note, this was intermediary -- this changed a few times and is not
    relevant to users, only regression tests.


Many parameters changed "time step" --> "timestep"


This is only for regression tests -- should not override user.


Constructs an evaluator for function


Move ONE source terms from PK to evaluators.


Moves source terms from PK to evaluators, like all other ATS PKs.


Removes dead options from transport PK list.


Many changes to transport PK input spec...


Searches for all transport PKs and calls fixTransportPK


initial condition' --> 'initial conditions


This function always exists, and calls all other fix functions, allowing __main__ to be the same.


Fix the compressible porosity list


move a param from old to new, if it exists


This changes the old, 'Arctic' SEB model into a test-reproducing, same answer input file.


This changes the old, 'Arctic' SEB model into more robust variant that crashes less often.


Adds a default land-cover section that will be the same as the Arctic defaults.


Can turn off derivative of source terms


Overland conductivity evals now use 'mobile depth key' instead of 'depth key


Mass flux --> water flux to be consistent with sources, distinguish for reactive transport (what mass, C or H2O?)


Finds the list, either in a flow PK or in a saturation evaluator


Deals with changes to surface temperatures.


Converts mafic potential --> capillary pressure in land cover list


Change the transpiration eval from the old default to the new default.

    Old was based on only TRF, new is based on both TRF and soil k_rel


Soil resistance is now an evaluator, needed if using evap.

    Parameters
    ----------
    rs_option : string
      One of "Sakagucki-Zeng" or "Sellers"
    dessicated_zone_set : float, list, dict
      float: all soil types use the same dessicated_zone_thickness
      list: dessicated_zone_set = [] equal length with soil types
      dict: dessicated_zone_set = {key: soil_type, val: dessicated_zone_thickness}


Lifting WRM parameters from water retention in PK.

    Moves Richards PK-->water retention evaluator-->model parameters
    list to state->model parameters.


Removes the now-dead land cover parameters for dessicated zone thickness and C&H b


Ensures there is an evaluator for "relative_permeability"


Last step -- moves the list out of Richards PK to state


Changes any instances of "linear operator" to "linear solver",
    which is now standard across all PKs.


Adds options for max valid change, which aren't required, but are strongly suggested.


One spinup file commonly used includes a longwave radiation
    value that is totally wrong.  Not many runs actually used it.
    Some runs even had a spec for it in their file, but didn't include
    the necessary flag to use it.  So this just removes it to avoid
    confusion.


Add units, changed to pressure.


Plots e and wc at a range of saturations and temperatures


Reads a Gmsh msh file.


Generates a single surface cell, to be the top of the column

        Centered at x,y,z, with dx == dy == width.


Creates a 2D surface strip mesh from transect data


Write the 3D mesh to ExodusII using arbitrary polyhedra spec


        Regularly extrude a 2D mesh to make a 3D mesh.

        mesh2D              : a Mesh2D object
        layer_types         : either a string (type) or list of strings (types)
        layer_data          : array of data needed (specific to the type)
        ncells_per_layer    : either a single integer (same number of cells in all
                            : layers) or a list of number of cells in the layer
        mat_ids             : either a single integer (one mat_id for all layers)
                            : or a list of integers (mat_id for each layer)
                            : or a 2D numpy array of integers (mat_id for each layer and
                              each column: [layer_id, surface_cell_id])

        types:
          - 'constant'      : (data=float thickness) uniform thickness
          - 'function'      : (data=function or functor) thickness as a function
                            : of (x,y)
          - 'snapped'       : (data=float z coordinate) snap the layer to
                            : provided z coordinate, telescoping as needed
          - 'node'          : thickness provided on each node of the surface domain
          - 'cell'          : thickness provided on each cell of the surface domain,
                            : interpolate to nodes

        NOTE: dz is uniform through the layer in all but the 'snapped' case
        NOTE: 2D mesh is always labeled 'surface', extrusion is always downwards


    Summarizes extruded data by printing info to log file.

    This is useful in rapidly debugging and understanding the layering before
    you do the extrusion process.


Mocked AWS Credentials for moto.


Create a Kinesis stream and return its summary info.


Create an S3 buket and return the bucket name.


Create simple flightline test data.


Create more complex flightline with curves.


Create sparse flightline data.


Create large flightline dataset.


Create flightline that crosses antimeridian.


Generate various sample coordinate sets for testing.


Example CMR polygons in different formats.


Create a mock CMR client that doesn't make real API calls.


Simple performance timer for tests.


Mock UMM-G response.


Create a sample CMR polygon GeoJSON.


Create a sample generated polygon GeoJSON.


List all available collections based on INI files in configs directory.


Download all files for a collection from the staging server.

        Args:
            collection_name: Name of the collection
            output_dir: Directory to save downloaded files
            force_download: If True, re-download even if files exist

        Returns:
            List of downloaded file paths


Download all files from a subdirectory.

        Args:
            subdir_url: URL of the subdirectory
            output_dir: Directory to save downloaded files
            force_download: If True, re-download even if files exist

        Returns:
            List of downloaded file paths


Prepare INI file for testing by copying and updating paths.

        Args:
            collection_name: Name of the collection
            test_dir: Test directory containing downloaded data

        Returns:
            Path to prepared INI file


Run metgenc process command.

        Args:
            ini_file: Path to INI configuration file
            environment: Environment to use (uat, sit, prod)

        Returns:
            Tuple of (success, output_or_error)


Validate generated output files using metgenc validate.

        Args:
            config_file: Path to the INI configuration file
            output_dir: Directory containing output files

        Returns:
            Tuple of (success, list_of_issues)


Main entry point.