wepy.resampling.resamplers.resampler module

exception wepy.resampling.resamplers.resampler.ResamplerError

Bases: Exception

Error raised when some constraint on resampling properties is violated.

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class wepy.resampling.resamplers.resampler.Resampler(min_num_walkers=Ellipsis, max_num_walkers=Ellipsis, debug_mode=False, **kwargs)

Bases: object

Abstract base class for implementing resamplers.

All subclasses of Resampler must implement the ‘resample’ method.

If extra reporting on resampling and resampler updates desired subclassed resamplers should update the following class constants for specifying the decision class and the names, shapes, data types, and table-like records for each record group:

• DECISION

• RESAMPLING_FIELDS

• RESAMPLING_SHAPES

• RESAMPLING_DTYPES

• RESAMPLING_RECORD_FIELDS

• RESAMPLER_FIELDS

• RESAMPLER_SHAPES

• RESAMPLER_DTYPES

• RESAMPLER_RECORD_FIELDS

The DECISION constant should be a wepy.resampling.decisions.decision.Decision subclass.

This base class provides some hidden methods that are useful for various purposes.

To help maintain constraints on the number of walkers in a simulation the constructor allows for setting of a minimum and/or maximum of walkers.

These values are allowed to be either integers, None, or Ellipsis.

Integers set hard values for the minimum and maximum values.

None indicates that the min and max are unbounded. For the min this translates to a value of 1 since there must always be one walker.

Ellipsis is an indicator to determine the minimum and maximum dependent on the number of walkers provided for resampling.

If the max_num_walkers is Ellipsis and the number of walkers given is 10 then the maximum will be set to 10 for that resampling. Conversely, for if the minimum is Ellipsis.

If both the min and max are set to Ellipsis then the number of walkers is always kept the same.

Note that this does not implement any algorithm that actually decides how many walkers there will be but just checks that these constraints are met by those implementations in subclasses.

To allow for this checking the ‘_resample_init’ method should be called at the beginning of the ‘resample’ method and the ‘_resample_cleanup’ should be called at the end of the ‘resample’ method.

Constructor for Resampler class

Parameters:

• min_num_walkers (int or None or Ellipsis) – The minimum number of walkers allowed to have. None is unbounded, and Ellipsis preserves whatever number of walkers were given as input as the minimum.

• max_num_walkers (int or None or Ellipsis) – The maximum number of walkers allowed to have. None is unbounded, and Ellipsis preserves whatever number of walkers were given as input as the maximum.

• debug_mode (bool) – Expert mode stuff don’t use unless you know what you are doing.

DECISION

The decision class for this resampler.

alias of Decision

CYCLE_FIELDS = ('step_idx', 'walker_idx')

The fields that get added to the decision record for all resampling records. This places a record within a single destructured listing of records for a single cycle of resampling using the step and walker index.

CYCLE_SHAPES = ((1,), (1,))

Data shapes of the cycle fields.

CYCLE_DTYPES = (<class 'int'>, <class 'int'>)

Data types of the cycle fields

CYCLE_RECORD_FIELDS = ('step_idx', 'walker_idx')

Optional, names of fields to be selected for truncated representation of the record group.

RESAMPLING_FIELDS = ('decision_id', 'step_idx', 'walker_idx')

String names of fields produced in this record group.

Resampling records are typically used to report on the details of how walkers are resampled for a given resampling step.

Warning

This is a critical function of many other components of the wepy framework and probably shouldn’t be altered by most developers.

Thi is where the information about cloning and merging of walkers is given. Seeing as this is a most of the value proposition of wepy as a tool getting rid of it will render most of the framework useless.

But sticking to the ‘loosely coupled, tightly integrated’ mantra you are free to modify these fields. This would be useful for implementing resampling strategies that do not follow basic cloning and merging. Just beware, that most of the lineage based analysis will be broken without implementing a new Decision class.

RESAMPLING_SHAPES = ((1,), (1,), (1,))

Numpy-style shapes of all fields produced in records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A tuple of ints that specify the shape of the field element array.

2. Ellipsis, indicating that the field is variable length and limited to being a rank one array (e.g. (3,) or (1,)).

3. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

Note that the shapes must be tuple and not simple integers for rank-1 arrays.

Option B will result in the special h5py datatype ‘vlen’ and should not be used for large datasets for efficiency reasons.

RESAMPLING_DTYPES = (<class 'int'>, <class 'int'>, <class 'int'>)

Specifies the numpy dtypes to be used for records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A numpy.dtype object.

4. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

RESAMPLING_RECORD_FIELDS = ('decision_id', 'step_idx', 'walker_idx')

Optional, names of fields to be selected for truncated representation of the record group.

These entries should be strings that are previously contained in the ‘FIELDS’ class constant.

While strictly no constraints on to which fields can be added here you should only choose those fields whose features could fit into a plaintext csv or similar format.

RESAMPLER_FIELDS = ()

String names of fields produced in this record group.

Resampler records are typically used to report on changes in the state of the resampler.

Notes

These fields are not critical to the proper functioning of the rest of the wepy framework and can be modified freely.

However, reporters specific to this resampler probably will make use of these records.

RESAMPLER_SHAPES = ()

Numpy-style shapes of all fields produced in records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A tuple of ints that specify the shape of the field element array.

2. Ellipsis, indicating that the field is variable length and limited to being a rank one array (e.g. (3,) or (1,)).

3. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

Note that the shapes must be tuple and not simple integers for rank-1 arrays.

Option B will result in the special h5py datatype ‘vlen’ and should not be used for large datasets for efficiency reasons.

RESAMPLER_DTYPES = ()

Specifies the numpy dtypes to be used for records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A numpy.dtype object.

4. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

RESAMPLER_RECORD_FIELDS = ()

Optional, names of fields to be selected for truncated representation of the record group.

These entries should be strings that are previously contained in the ‘FIELDS’ class constant.

While strictly no constraints on to which fields can be added here you should only choose those fields whose features could fit into a plaintext csv or similar format.

DEBUG_MODES = (True, False)

property decision

The decision class for this resampler.

resampling_field_names()

Access the class level FIELDS constant for this record group.

resampling_field_shapes()

Access the class level SHAPES constant for this record group.

resampling_field_dtypes()

Access the class level DTYPES constant for this record group.

resampling_fields()

Returns a list of zipped field specs.

Returns:

record_specs – A list of the specs for each field, a spec is a tuple of type (field_name, shape_spec, dtype_spec)

Return type:

list of tuple

resampling_record_field_names()

Access the class level RECORD_FIELDS constant for this record group.

resampler_field_names()

Access the class level FIELDS constant for this record group.

resampler_field_shapes()

Access the class level SHAPES constant for this record group.

resampler_field_dtypes()

Access the class level DTYPES constant for this record group.

resampler_fields()

Returns a list of zipped field specs.

Returns:

record_specs – A list of the specs for each field, a spec is a tuple of type (field_name, shape_spec, dtype_spec)

Return type:

list of tuple

resampler_record_field_names()

Access the class level RECORD_FIELDS constant for this record group.

property is_debug_on

set_debug_mode(mode)

Parameters:

mode

debug_on()

debug_off()

property max_num_walkers_setting

The specification for the maximum number of walkers for the resampler.

property min_num_walkers_setting

The specification for the minimum number of walkers for the resampler.

max_num_walkers()

“ Get the max number of walkers allowed currently

min_num_walkers()

“ Get the min number of walkers allowed currently

_set_resampling_num_walkers(num_walkers)

Sets the concrete number of walkers constraints given a number of walkers and the settings for max and min.

Parameters:

num_walkers (int)

_unset_resampling_num_walkers()

_resample_init(walkers, **kwargs)

Common initialization stuff for resamplers.

Sets the number of walkers in this round of resampling.

Parameters:

walkers (list of Walker objects)

_resample_cleanup(**kwargs)

Common cleanup stuff for resamplers.

Unsets the number of walkers for this round of resampling.

resample(walkers, debug_mode=False)

Perform resampling on the set of walkers.

Parameters:

• walkers (list of Walker objects) – The walkers that are to be resampled.

• debug_mode (bool) – Expert mode debugging setting, only forif you know exactly what you are doing.

Returns:

• resampled_walkers (list of Walker objects) – The set of resampled walkers

• resampling_data (list of dict of str: value) – A list of destructured resampling records from this round of resampling.

• resampler_data (list of dict of str: value) – A list of records recording how the state of the resampler was updated.

class wepy.resampling.resamplers.resampler.NoResampler(min_num_walkers=Ellipsis, max_num_walkers=Ellipsis, debug_mode=False, **kwargs)

Bases: Resampler

The resampler which does nothing.

Constructor for Resampler class

Parameters:

• min_num_walkers (int or None or Ellipsis) – The minimum number of walkers allowed to have. None is unbounded, and Ellipsis preserves whatever number of walkers were given as input as the minimum.

• max_num_walkers (int or None or Ellipsis) – The maximum number of walkers allowed to have. None is unbounded, and Ellipsis preserves whatever number of walkers were given as input as the maximum.

• debug_mode (bool) – Expert mode stuff don’t use unless you know what you are doing.

CYCLE_DTYPES = (<class 'int'>, <class 'int'>)

Data types of the cycle fields

CYCLE_FIELDS = ('step_idx', 'walker_idx')

The fields that get added to the decision record for all resampling records. This places a record within a single destructured listing of records for a single cycle of resampling using the step and walker index.

CYCLE_RECORD_FIELDS = ('step_idx', 'walker_idx')

Optional, names of fields to be selected for truncated representation of the record group.

CYCLE_SHAPES = ((1,), (1,))

Data shapes of the cycle fields.

DEBUG_MODES = (True, False)

RESAMPLER_DTYPES = ()

Specifies the numpy dtypes to be used for records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A numpy.dtype object.

4. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

RESAMPLER_FIELDS = ()

String names of fields produced in this record group.

Resampler records are typically used to report on changes in the state of the resampler.

Notes

These fields are not critical to the proper functioning of the rest of the wepy framework and can be modified freely.

However, reporters specific to this resampler probably will make use of these records.

RESAMPLER_RECORD_FIELDS = ()

Optional, names of fields to be selected for truncated representation of the record group.

These entries should be strings that are previously contained in the ‘FIELDS’ class constant.

While strictly no constraints on to which fields can be added here you should only choose those fields whose features could fit into a plaintext csv or similar format.

RESAMPLER_SHAPES = ()

Numpy-style shapes of all fields produced in records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A tuple of ints that specify the shape of the field element array.

2. Ellipsis, indicating that the field is variable length and limited to being a rank one array (e.g. (3,) or (1,)).

3. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

Note that the shapes must be tuple and not simple integers for rank-1 arrays.

Option B will result in the special h5py datatype ‘vlen’ and should not be used for large datasets for efficiency reasons.

_resample_cleanup(**kwargs)

Common cleanup stuff for resamplers.

Unsets the number of walkers for this round of resampling.

_resample_init(walkers, **kwargs)

Common initialization stuff for resamplers.

Sets the number of walkers in this round of resampling.

Parameters:

walkers (list of Walker objects)

_set_resampling_num_walkers(num_walkers)

Sets the concrete number of walkers constraints given a number of walkers and the settings for max and min.

Parameters:

num_walkers (int)

_unset_resampling_num_walkers()

debug_off()

debug_on()

property decision

The decision class for this resampler.

property is_debug_on

max_num_walkers()

“ Get the max number of walkers allowed currently

property max_num_walkers_setting

The specification for the maximum number of walkers for the resampler.

min_num_walkers()

“ Get the min number of walkers allowed currently

property min_num_walkers_setting

The specification for the minimum number of walkers for the resampler.

resampler_field_dtypes()

Access the class level DTYPES constant for this record group.

resampler_field_names()

Access the class level FIELDS constant for this record group.

resampler_field_shapes()

Access the class level SHAPES constant for this record group.

resampler_fields()

Returns a list of zipped field specs.

Returns:

record_specs – A list of the specs for each field, a spec is a tuple of type (field_name, shape_spec, dtype_spec)

Return type:

list of tuple

resampler_record_field_names()

Access the class level RECORD_FIELDS constant for this record group.

resampling_field_dtypes()

Access the class level DTYPES constant for this record group.

resampling_field_names()

Access the class level FIELDS constant for this record group.

resampling_field_shapes()

Access the class level SHAPES constant for this record group.

resampling_fields()

Returns a list of zipped field specs.

Returns:

record_specs – A list of the specs for each field, a spec is a tuple of type (field_name, shape_spec, dtype_spec)

Return type:

list of tuple

resampling_record_field_names()

Access the class level RECORD_FIELDS constant for this record group.

set_debug_mode(mode)

Parameters:

mode

DECISION

alias of NoDecision

RESAMPLING_FIELDS = ('decision_id', 'target_idxs', 'step_idx', 'walker_idx')

String names of fields produced in this record group.

Resampling records are typically used to report on the details of how walkers are resampled for a given resampling step.

Warning

This is a critical function of many other components of the wepy framework and probably shouldn’t be altered by most developers.

Thi is where the information about cloning and merging of walkers is given. Seeing as this is a most of the value proposition of wepy as a tool getting rid of it will render most of the framework useless.

But sticking to the ‘loosely coupled, tightly integrated’ mantra you are free to modify these fields. This would be useful for implementing resampling strategies that do not follow basic cloning and merging. Just beware, that most of the lineage based analysis will be broken without implementing a new Decision class.

RESAMPLING_SHAPES = ((1,), Ellipsis, (1,), (1,))

Numpy-style shapes of all fields produced in records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A tuple of ints that specify the shape of the field element array.

2. Ellipsis, indicating that the field is variable length and limited to being a rank one array (e.g. (3,) or (1,)).

3. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

Note that the shapes must be tuple and not simple integers for rank-1 arrays.

Option B will result in the special h5py datatype ‘vlen’ and should not be used for large datasets for efficiency reasons.

RESAMPLING_DTYPES = (<class 'int'>, <class 'int'>, <class 'int'>, <class 'int'>)

Specifies the numpy dtypes to be used for records.

There should be the same number of elements as there are in the corresponding ‘FIELDS’ class constant.

Each entry should either be:

1. A numpy.dtype object.

4. None, indicating that the first instance of this field will not be known until runtime. Any field that is returned by a record producing method will automatically interpreted as None if not specified here.

RESAMPLING_RECORD_FIELDS = ('decision_id', 'target_idxs', 'step_idx', 'walker_idx')

Optional, names of fields to be selected for truncated representation of the record group.

These entries should be strings that are previously contained in the ‘FIELDS’ class constant.

While strictly no constraints on to which fields can be added here you should only choose those fields whose features could fit into a plaintext csv or similar format.

resample(walkers, **kwargs)

Perform resampling on the set of walkers.

Parameters:

• walkers (list of Walker objects) – The walkers that are to be resampled.

• debug_mode (bool) – Expert mode debugging setting, only forif you know exactly what you are doing.

Returns:

• resampled_walkers (list of Walker objects) – The set of resampled walkers

• resampling_data (list of dict of str: value) – A list of destructured resampling records from this round of resampling.

• resampler_data (list of dict of str: value) – A list of records recording how the state of the resampler was updated.

_init_walker_actions(n_walkers)

Returns a list of default resampling records for a single resampling step.

Parameters:

n_walkers (int) – The number of walkers to generate records for

Returns:

decision_records – A list of default decision records for one step of resampling.

Return type:

list of dict of str: value