core
core
Functions
| Name | Description |
|---|---|
| build_conduit_data | Fetches an Nt-by-3 array of the requested property |
| filter_pores | Returns which of the supplied pores has the specified label(s) |
| flatten_dict | Takes a nested dict and returns a flattened version with the specified |
| flatten_list | Given a list of nested lists of arbitrary depth, returns a single |
| fold_dict | Takes a flat dict and converts it to a nested or folded one by |
| get_components | Returns a list of the component names associated with a given mixture |
| get_data | Retrieves data from the target dictionary utilizing pnmlib’s syntax |
| get_indices | |
| get_label_data | Returns a dictionary containing only boolean arrays |
| get_param_data | Returns a dictionary containing only scalar numerical values |
| get_pores | Returns pore indices where given labels exist, according to the logic |
| get_prop_data | Returns a dictionary containing only numerical arrays of the specified element(s) |
| get_throats | Returns throat locations where given labels exist, according to the |
| num_pores | Returns the number of pores of the specified label(s) |
| num_throats | Return the number of throats of the specified labels |
| set_data | Writes data to the target dictionary according to pnmlib’s rules |
| set_label | Creates or updates a label array |
build_conduit_data
core.build_conduit_data(target, group, propname)Fetches an Nt-by-3 array of the requested property
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| propname | str | The dictionary key of the property to fetch. | required |
Returns
| Name | Type | Description |
|---|---|---|
| data | ndarray | An Nt-by-3 array with each column containing the requested data for pore1, throat, and pore2 respectively. |
filter_pores
core.filter_pores(target, locs, labels, mode='or')Returns which of the supplied pores has the specified label(s)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pores | List of pores or throats to be filtered | required | |
| or | List of pores or throats to be filtered | required | |
| labels | list of strings | The labels to apply as a filter | required |
| mode | str | Controls how the filter is applied. The default value is ‘or’. Options include: ============== =================================================== mode Description ============== =================================================== ‘or’ Returns the labels that are assigned to any of the given locations. Also accepts ‘union’ and ‘any’ ‘and’ Labels that are present on all the given locations. also accepts ‘intersection’ and ‘all’ ‘xor’ Labels that are present on only one of the given locations. Also accepts ‘exclusive_or’ ‘nor’ Labels that are not present on any of the given locations. Also accepts ‘not’ and ‘none’ ‘nand’ Labels that are present on all but one of the given locations ‘xnor’ Labels that are present on more than one of the given locations. ============== =================================================== | 'or' |
Returns
| Name | Type | Description |
|---|---|---|
| A list of pores that have been filtered according the given criteria. | ||
| The returned list is a subset of the received list of pores. |
See Also
pores throats
flatten_dict
core.flatten_dict(d, delim='/')Takes a nested dict and returns a flattened version with the specified delimiter between keys
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| d | dict | A nested dictionary | required |
| delim | str | The character to use when joining nested keys | '/' |
flatten_list
core.flatten_list(input_list)Given a list of nested lists of arbitrary depth, returns a single level or ‘flat’ list.
fold_dict
core.fold_dict(d, delim='/')Takes a flat dict and converts it to a nested or folded one by creating a new level of dict for each occurrence of the delimiter found in the keys.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| d | dict | A dictionary which has | required |
| delim | str | The character that indicates where new levels should be created | '/' |
get_components
core.get_components(target, mixture)Returns a list of the component names associated with a given mixture
get_data
core.get_data(target, key)Retrieves data from the target dictionary utilizing pnmlib’s syntax
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| target | dict | The dictionary containing the simulation data | required |
| key | str | The name of the arrays to be retrieved. There are a number of syntactic shortcuts available: * If key is a numerical value it is returned directly, unchanged. * If key is blank, then target is returned directly. * If key contains @<label> then only values where <label> == True are returned * If key contains * then it is treated as a wildcard and a dictionary containing all arrays which match the key are returned. * If key contains \|, the keys in the returned dictionary will have the text preceding the ‘|’ trimmed. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| data | depends | The returned data will depend on what was requested. Could be a numpy array or a dictionary of arrays. Could also be a scalar or other object if parameters or attributes are requested. |
get_indices
core.get_indices(target, element=None, labels=['all'], mode='or')get_label_data
core.get_label_data(target, element=['pore', 'throat', 'conduit'])Returns a dictionary containing only boolean arrays
get_param_data
core.get_param_data(target, key=None)Returns a dictionary containing only scalar numerical values
get_pores
core.get_pores(target, labels='all', mode='or', asmask=False)Returns pore indices where given labels exist, according to the logic specified by the mode argument.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| labels | str or list[str] | The label(s) whose pores locations are requested. This argument also accepts ’*’ for wildcard searches. | 'all' |
| mode | str | Specifies how the query should be performed. The options are: ============== =================================================== mode meaning ============== =================================================== ‘or’ Returns the labels that are assigned to any of the given locations. Also accepts ‘union’ and ‘any’ ‘and’ Labels that are present on all the given locations. also accepts ‘intersection’ and ‘all’ ‘xor’ Labels that are present on only one of the given locations.Also accepts ‘exclusive_or’ ‘nor’ Labels that are not present on any of the given locations. Also accepts ‘not’ and ‘none’ ‘nand’ Labels that are present on all but one of the given locations ‘xnor’ Labels that are present on more than one of the given locations. ============== =================================================== | 'or' |
| asmask | bool | If True then a boolean array of length Np is returned with True values indicating the pores that satisfy the query. |
False |
Returns
| Name | Type | Description |
|---|---|---|
| A Numpy array containing pore indices filtered by the logic specified | ||
in mode. |
See Also
throats
Notes
Technically, nand and xnor should also return pores with none of the labels but these are not included. This makes the returned list more useful.
To perform more complex or compound queries, you can opt to receive the result a a boolean mask (asmask=True), then manipulate the arrays manually.
get_prop_data
core.get_prop_data(target, element=['pore', 'throat', 'conduit'])Returns a dictionary containing only numerical arrays of the specified element(s)
get_throats
core.get_throats(target, labels='all', mode='or', asmask=False)Returns throat locations where given labels exist, according to the logic specified by the mode argument.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| labels | str or list[str] | The throat label(s) whose locations are requested. If omitted, ‘all’ throat indices are returned. This argument also accepts ’*’ for wildcard searches. | 'all' |
| mode | str | Specifies how the query should be performed. The options are: ============== =================================================== mode meaning ============== =================================================== ‘or’ Returns the labels that are assigned to any of the given locations. Also accepts ‘union’ and ‘any’ ‘and’ Labels that are present on all the given locations. also accepts ‘intersection’ and ‘all’ ‘xor’ Labels that are present on only one of the given locations.Also accepts ‘exclusive_or’ ‘nor’ Labels that are not present on any of the given locations. Also accepts ‘not’ and ‘none’ ‘nand’ Labels that are present on all but one of the given locations ‘xnor’ Labels that are present on more than one of the given locations. ============== =================================================== | 'or' |
| asmask | bool | If True then a boolean array of length Nt is returned with True values indicating the throats that satisfy the query. |
False |
Returns
| Name | Type | Description |
|---|---|---|
| A Numpy array containing throat indices filtered by the logic specified | ||
in mode. |
See Also
pores
num_pores
core.num_pores(target, labels='all', mode='or')Returns the number of pores of the specified label(s)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| labels | list of strings | The pore labels that should be included in the count. If not supplied, all pores are counted. | 'all' |
| labels | list of strings | Label of pores to be returned | 'all' |
| mode | str | Specifies how the count should be performed. The options are: ============== =================================================== mode meaning ============== =================================================== ‘or’ Returns the labels that are assigned to any of the given locations. Also accepts ‘union’ and ‘any’ ‘and’ Labels that are present on all the given locations. also accepts ‘intersection’ and ‘all’ ‘xor’ Labels that are present on only one of the given locations.Also accepts ‘exclusive_or’ ‘nor’ Labels that are not present on any of the given locations. Also accepts ‘not’ and ‘none’ ‘nand’ Labels that are present on all but one of the given locations ‘xnor’ Labels that are present on more than one of the given locations. ============== =================================================== | 'or' |
Returns
| Name | Type | Description |
|---|---|---|
| Np | int | Number of pores with the specified labels |
See Also
num_throats count
Notes
Technically, ‘nand’ and ‘xnor’ should also count pores with none of the labels, however, to make the count more useful these are not included.
num_throats
core.num_throats(target, labels='all', mode='or')Return the number of throats of the specified labels
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| labels | list of strings | The throat labels that should be included in the count. If not supplied, all throats are counted. | 'all' |
| mode | str | Specifies how the count should be performed. The options are: ============== =================================================== mode meaning ============== =================================================== ‘or’ Returns the labels that are assigned to any of the given locations. Also accepts ‘union’ and ‘any’ ‘and’ Labels that are present on all the given locations. also accepts ‘intersection’ and ‘all’ ‘xor’ Labels that are present on only one of the given locations.Also accepts ‘exclusive_or’ ‘nor’ Labels that are not present on any of the given locations. Also accepts ‘not’ and ‘none’ ‘nand’ Labels that are present on all but one of the given locations ‘xnor’ Labels that are present on more than one of the given locations. ============== =================================================== | 'or' |
Returns
| Name | Type | Description |
|---|---|---|
| Nt | int | Number of throats with the specified labels |
See Also
num_pores count
Notes
Technically, ‘nand’ and ‘xnor’ should also count throats with none of the labels, however, to make the count more useful these are not included.
set_data
core.set_data(target, key, value, locs=...)Writes data to the target dictionary according to pnmlib’s rules
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| target | dict | The dictionary containing the simulation data | required |
| key | str | The dictionary key to use when storing the data. | required |
| value | scalar or array - like | The numerical value(s) to write. If a scalar then it is applied everywhere, if a vector then it must be the correct size (i.e. \(N_p-long\) or \(N_t-long\)), or its size must match locs if given. If value is a dict then each keyword is joined with key using a / meaning that key is the group. |
required |
| locs | ndarray or tuple | The locations to write value. If value is a 1D array, then locs can be an array-like object of indices. If value is >1D, then locs must be a tuple of index arrays similar to that returned by np.where, meaning the first array in the tuple specifies the the first axis of value and so on. |
... |
Returns
| Name | Type | Description |
|---|---|---|
| This function operates "in-place" so nothing is returned. |
set_label
core.set_label(target, label, locs=[], mode='add')Creates or updates a label array
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| label | str | The label to apply to the specified locations | required |
| pores | array_like | A list of pore indices or a boolean mask of where given label should be added or removed (see mode) |
required |
| throats | array_like | A list of throat indices or a boolean mask of where given label should be added or removed (see mode) |
required |
| mode | str | Controls how the labels are handled. Options are: =========== ====================================================== mode description =========== ====================================================== ‘add’ (default) Adds the given label to the specified locations while keeping existing labels ‘overwrite’ Removes existing label from all locations before adding the label in the specified locations ‘remove’ Removes the given label from the specified locations leaving the remainder intact ‘purge’ Removes the specified label from the object completely. This ignores the pores and throats arguments. ‘clear’ Sets all the labels to False but does not remove the label array =========== ====================================================== |
'add' |