Common interface for all g-function boundary conditions

[MassimoCimmino]

With the multiplication of borehole boundary conditions, a centralize function would simplify the use of pygfunction.

[MassimoCimmino]

Since a need for this feature was brought up in #56. There are a few issues that could be addressed here to make the g-function call future-proof.

Boundary conditions - Different boundary conditions require different inputs (e.g. The uniform inlet fluid temperature method requires a list of pipes in addition to the list of boreholes).
Solution algorithm - At the moment only the similarities method is available in addition to a detailed method. Other methods will surely be implemented at some point, especially if inclined boreholes or processes like groundwater flow are to be implemented.

The common interface could be inspired by scipy.optimize.minimize which also has the need for method-dependent inputs.

[j-c-cook]

As far as future proofing goes; it should be possible to query a function for its inputs. Since everything in Python is an object, the inputs to a function could be successively looped over and pulled from the common interface class (probably by use of getattr). Thus, the goal of the common interface could be that the only necessary modifications moving forward would be additional instances not already prescribed.

P.S. Your "common interface could be inspired by..." link is broken on my end.

[MassimoCimmino]

I like your first draft of the common interface. I would suggest that __init__ keeps common parameters in addition to **kwargs (or an options dict). This helps for auto-completion. My proposal :

class gFunction(object):
    """
    Draft for gFunction class.

    Attributes
    ----------
    boreholes_or_network : list of Borehole objects or NEtwork object
        List of boreholes included in the bore field, or network of boreholes
        and pipes.
    alpha : float
        Soil thermal diffusivity (in m2/s).
    time : float or array, optional
        Values of time (in seconds) for which the g-function is evaluated. The
        g-function is only evaluated at initialization if a value is provided.
    method : str, optional
        Method for the evaluation of the g-function. Should be one of
            - 'similarities'
            - 'detailed'
        Default is 'similarities'.
    boundary_condition : str, optional
        Boundary condition for the evaluation of the g-function. Should be one
        of
            - 'UHTF' : Uniform heat transfer rate.
            - 'UBWT' : Uniform borehole wall temperature.
            - 'MIFT' : Mixed inlet fluid temperatures.
        If not given, chosen to be ''UBWT'' if a list of boreholes is provided
        or ''MIFT'' if a Network object is provided.
    options : dict, optional
        A dictionary of solver options. All methods accept the following
        generic options:
            nSegments : int, optional
                Number of line segments used per borehole.
                Default is 12.
            processes : int, optional
                Number of processors to use in calculations. If the value is
                set to None, a number of processors equal to cpu_count() is
                used.
                Default is None.
            disp : bool, optional
                Set to true to print progression messages.
                Default is False.
            profiles : bool, optional
                Set to true to keep in memory the temperatures and heat
                extraction rates.
                Default is False.
        For method-specific options, see ..............
        (method-specific options are the tolerances for the similarities
        method)

    """

    def __init__(self, boreholes_or_network, alpha, time=None,
                 method='similarities', boundary_condition=None, options=None):
        # Initialization of g-function parameters, calls
        # self._check_assertions():

        # If time is not None, calls self.evaluate_g_function(time)
        return True or gFunc

    def __call__(self, time):
        return gFunc

    def evaluate_g_function(self, time):
        # Calculates the g-function using the correct method and boundary
        # condition
        return gFunc

    def visualize_g_function(self):
        return fig

    def visualize_heat_extraction_rate_profiles(self, time=None, iBoreholes=None):
        return fig

    def visualize_temperature_profiles(self, time=None, iBoreholes=None):
        return fig

    def visualize_heat_extraction_rates(self, iBoreholes=None):
        return fig

    def visualize_temperatures(self, iBoreholes=None):
        return fig


    def check_assertions(self):
        """
        This method ensures that the instances filled in the gFunction object are what is expected.
        Returns
        -------
        True
        """
        # [...]
        return True

This interface could easily deal with the different boundary conditions, using the flexible boreholes list or network object as the first parameter. For fluid temperature boundary conditions, m_flow, cp and borehole_connectivity would be required. The Network object can easily be modified to accept nominal values for the first two at initialization (borehole_connectivity is already required).

I would argue that the 'UIFT' boundary condition should be deprecated, since it is a special case of the mixed inlet condition with all boreholes in parallel (the default option of the Network class).

A nice feature here would be to add a __call__(self, time) that interpolates within the last computed g-function values.

[MassimoCimmino]

@j-c-cook Is your interface still on any of your branches?

[j-c-cook]

Yes, I have tried to straighten things out here.

The commits associated with reverting the file mod changes (#55 (comment)) was not completely straightforward, so that could cause confusion.

I have created a pull request to your master. The only differences between your master and my issue_33 branch (pull request #63) is my initial recommendation for a common g-function interface.

I didn't see an issue33 branch of your own for me to pull request to.

[MassimoCimmino]

@j-c-cook I created the missing issue33 branch and simply pushed your commits there. Your PR (#63, now closed) shows no merge conflicts so it is fine to work on this issue from there.

The work plan would be as follows :

• Add parameters for nominal values of m_flow, cp and nSegments in the Network class
  This should be as simple as adding m_flow=None, cp=None, nSegments=None to the __init__ method and calling all coefficients_[...] methods (through a new _initialize_coefficients method) if values are provided for all three.

• Configure calls to the already-implemented g-function calculation functions using the new interface
  This includes the configuration of the interface (__init__), the assertions (_check_assertions), and the evaluation of the g-function (evaluate_gfunction). The _check_assertions method should check for valid inputs (including the borefield layout).

• Implement visualization options for the g-function and other advanced metrics (heat extraction rates and borehole wall temperatures)
  First step here would be to add a profiles=False parameter to the g-function calculation functions. If True, then the functions return a tuple (gFun, Tb[nSegments,Nt], Qb[nSegments,Nt]) instead of gFun. Methods can then be implemented to visualize the evolution of the borehole-averaged heat extraction rates or borehole wall temperatures vs. time, and the heat extraction rates and borehole wall temperature profiles vs z at a specified time.

• Update the examples and the documentation of pygfunction to use the new interface
  This is self-explanatory.

[MassimoCimmino]

As for future-proofing for eventual new calculation methods, this can be addressed when they are developed and we have a better idea of what is required.