pypfilt.cache

pypfilt.cache.default(ctx, forecast_times)

Return the default (i.e., empty) cached state.

If no cache file is defined in ctx.settings['files']['cache_file'], this will create a temporary cache file that will be automatically deleted when the process terminates (either normally, or in response to the SIGTERM signal).

Parameters:
  • ctx – The simulation context.

  • forecast_times – The times at which forecasts will be run.

Returns:

A dictionary with keys:

  • 'state': Either a simulation state (see pypfilt.pfilter.run()) or None if there is no cached state from which to resume.

  • 'start': Either the time from which to begin the simulation, or None if there is no cached state.

  • 'end': Either the time at which to end the simulation, or None if there is no cached state.

  • 'fs_times': The times at which forecasts should be generated.

  • 'save_to': The filename for saving the particle history matrix.

  • 'clean': A cleanup function to remove any temporary files, and which will have been registered to execute at termination.

pypfilt.cache.save_state(cache_file, ctx, when, **kwargs)

Save the particle history matrix to a cache file, to allow future forecasting runs to resume from this point.

Parameters:
  • cache_file – The name of the cache file.

  • ctx – The simulation context.

  • when – The current simulation time.

  • **kwargs – The data sets to store in the cached state; at a minimum this should include 'hist' (the particle history matrix) and 'offset' (the index of the current time-step in the particle history matrix).

Examples:

cache_file = 'cache.hdf5'
cache.save_state(cache_file, context, current_time,
                 offset=np.int32(hist_ix),
                 hist=hist)
pypfilt.cache.load_state(cache_file, ctx, forecast_times)

Load the particle history matrix from a cache file, allowing forecasting runs to resume at the point of the first updated/new observation.

Parameters:
  • cache_file – The name of the cache file.

  • ctx – The simulation context.

  • forecast_times – The times at which forecasts will be run.

Returns:

Either None, if there was no suitable cached state, or a dictionary with following keys:

  • 'start': The time from which to begin the simulation.

  • 'end': The time from which to end the simulation.

  • 'state': A dictionary that contains the following keys:

    • 'hist': The particle history matrix.

    • 'offset': The index of the current time-step in the particle history matrix.

Note that if the cache file already contains a suitable state for each of the provided forecast times, this will return a dictionary as described above, where the 'start' and 'end' values are the same (i.e., there is no need to run an estimation pass).

pypfilt.cache.save_rng_states(group, dataset_name, rngs)

Save random number generator states to a cached dataset.

Parameters:
  • group – The HDF5 group that will contain the saved states.

  • dataset_name – The name of the HDF5 dataset to create.

  • rngs – A dictionary that maps names (strings) to random number generators.

pypfilt.cache.load_rng_states(group, dataset_name, rngs)

Restore random number generator states from a cached dataset.

Parameters:
  • group – The HDF5 group that contains the saved states.

  • dataset_name – The name of the HDF5 dataset.

  • rngs – A dictionary that maps names (strings) to random number generators, whose states will be updated.

Raises:

ValueError – if there are missing names or additional names in the dataset.