Implement a function to aggregate control energy over time points

[JohannesWiesner]

Hi Team Bassett, first of all, thank you very much for implementing this package in Python! That really helps me to integrate NCT-computing into all my other Python scripst :) I am using network_control.energies.mininum_energy to obtain my energy matrix and we would like to aggregate the computed control energy over each node:

In the documentation it says:

Typically, to summarize over these values, you will calculate the area under the curve, or sum of squared values divded by the number of time points, for each node.

However, the package currently does not include a function that does this job. Also, here in Mannheim, we were wondering how to optimally implement the second variant (there was also the suggestion to take the log of the sum of squares). Perhaps the whole thing is too trivial to have its own function, on the other hand - Maybe it would make sense to provide some community "standards" in this Python package (since there seem to be various ways to do it)?:

def aggregate_energy(u,method='auc',absolute_values=True):
    '''Aggregate control energy over all timepoints.
    https://github.com/BassettLab/control_package/blob/main/docs/pages/getting_started.rst    

    Parameters
    ----------
    u : numpy.array
        NxT array with control energies as returned from network_control.energies.minimum_energy 
        or network_control.energies.optimal_energy.

    method: str
        Method for aggregating energy for each node over time. User can choose
        between 'auc' (computing area under the curve), or 'log_ss'
        for computing the logarithm of sum of squares divided by the number of
        time points (Default = 'auc')

    absolute_values: boolean
        Transform the resulting vector to absolute values (Default: True)

    Returns
    -------
    u_agg : numpy.array
        Aggregated array

    '''
    if method == 'auc':
        u_agg = np.trapz(u**2,axis=0)
    elif method == 'log_ss':
        u_agg = np.log(np.sum(u**2,axis=0) / len(u))

    if absolute_values:
        u_agg = np.abs(u_agg)

    return u_agg

[jastiso]

Thank you so much for testing using the package and making suggestions! We really appreciate it!

We think it's a good idea to add a function that integrates over the output of minimum/optimal energy functions. In order to be consistent with the mathematical definition of what an "energy", we'll probably only add integration as a method of summarizing the input. Other summaries certainly might be useful, but they aren't technically "energy". We'll add this functionality soon!

[jastiso]

the latest push has this (and it will be included in the next package release), so I'm marking this as resolved :)