Clarify terms 'subdomain', 'prop', 'info', 'locations' and 'label'

[jgostick]

We seem to be using the terms 'subdomain', 'prop', 'locations' and 'info' interchangeably. I have also started using the phrase subdomain label in the docs.

Proposal: use the word 'label' universally. This would required

1. renaming the pore/throat_info arrays
2. renaming the set_info and get_info methods,
3. changing the method definitions to accept label instead of prop or subdomain
4. changing many places in the code

[jgostick]

@maghighi and I discussed this a bit today: 1 & 2. leave the method and dictionary names the same (ie. keep using info) but probably change arguments to labels (see 3). Keeping it pore_info instead of pore_labels is more logical since we're storing info here (and data on pore_data).

3. This lead to a larger discussion about how the subdomain feature has crept into the code and is being used in ways we didn't plan or foresee. I will discuss this below.
4. @maghighi will impliment this soon.

[jgostick]

Here is my current view: We should more or less abandon the 'subdomain' argument, and instead use 'locations' and 'labels'. We weren't really using 'subdomain' in any meaningful way. It was just helping to direct physics data to the fluid and geometry data to the network, but was starting to get messy. In fact, it was possible to write data anywhere one wished just by changing what arguments were given. In other words, the user has to know where data goes and why, which makes me think it should be more transparent.

Instead we should keep it simple: when a fluid argument is given, the data is written to that fluid, when not given it's written to the object that calls the setter (usually network, but also fluid and algorithm). Simple, and adheres to pythons 'we're all consenting adults here' ideology.

However, we still need ways to control data setting and getting bit. We can use a 'locations' argument for that. Locations is an explicit list of where data should go (either boolean or inidices). A locations array can be produced using by passing any desired labesl to get_pore_indices, which is pretty nifty now. So, labels can be used to define entire sub-domains, small subsets, label special pores, etc, and these can be converted into a locations array for use in the setter and getter.

Interestingly, we already started implementing 'locations' with geometry, where we needed argument called 'locations' where geometry applies. The generator automatically creates an info array with the geometry name as a label, so one can recover a list of there the 'subdomain' is active by passing the geometry label to get_pore_indices.

So here are the pore setter and getters:

ind = pn.get_pore_indices(['top','front'],mode='union') pn.set_pore_data(prop='diameter',data=sizes,locations=ind)

Note, I thought about adding the option for 'labels', but using get_pore_indices to create ind is perfect. Also, locations should accept a boolean mask or indices, and the setter should sort it out.

pn.get_pore_info(prop='diameter',locations=ind)

If locations is left out, then all diameters are returned.

For set_pore_info, we originally made the analogous to set_pore_data, which made for some odd arguments. I now think we should change them as follows:

ind = pn.get_pore_data(prop='diameter')<r_val pn.set_pore_info(label='small_pores',locations=ind)

label is currently called a 'prop' and locations is 'data'. This very confusing. This new logically consistent with the data setter and getter even if the syntax is not the same.

[jgostick]

Small admendment to setters and getters... @maghighi and I have decided that locations should accept indices, boolean mask resulting from the get_pore_indices query (as above), but also should accept a label string or list of strings, as well as objects (which have a name attribute). This will allow different use conventions in different parts of the code, like in geometry methods you send the geometry object as locations. (the setter will read geometry.name, then find corresponding indices using get_pore_indices).

[jgostick]

OK, so the final situation is this:

1. There are two main classes of information: 'data' and 'info'
2. 'info' contains dictionaries whose names are 'labels'
3. Wherever these dictionaries are True, then that 'label' applies to that 'location'
4. 'locations' is a deliberately chosen word that refers to the index 'location' in the array, BUT also alludes to the fact that each element in an array represents a 'location' in the real network...'location' is not to be confused with coordinate.
5. 'data' contains dictionaries with any numerical values (i.e. pore size)
6. 'locations' also applies to the 'data' arrays to specify index location and allude to a real physical location
7. We now use 'labels' to declare which pores/throat 'locations' belong to which subdomain. A subdomain can be anything from a large region where a geometry object applies, or just pores on a single face.