Implementation of $S^1$ model

[robertjankowski]

This is an implementation of $\mathbb{S}^1$ model by [1]. It is a geometric soft configuration model which produces synthetic networks with similar properties as in real networks, i.e., high level of clustering, heterogeneous degree distribution, or small-world property.

[1] Serrano, M. Angeles, Dmitri, Krioukov, and Marián, Boguñá. "Self-Similarity of Complex Networks and Hidden Metric Spaces". Phys. Rev. Lett. 100 (2008): 078701.

[robertjankowski]

Hi! Can I ask for the code review? @MridulS

[MridulS]

Thank you for this PR @robertjankowski! It looks good!

I have made some comments about code/API organization in the review. Let me know what do you think.

Also I think we can speed up a bunch of calculations with numpy vectorisation but it's not a major blocker here. It's fine to keep this graph generator with vanilla python :)

[robertjankowski]

Thank you very much for the review @MridulS. Let me know if some more changes are needed :)

[dschult]

Ahh... thanks for the connection to H2 as well as S1. It gives be a better idea of what is crucial to the arrangement. It isn't specific to S1, or to H2. There are many other spaces that this geometry could be embedded inside. The crux is that the distance measure is periodic. How about the name: soft_random_periodic_geometric_graph.
That is getting a little long, so maybe soft_periodic_geometric_graph? But sometimes brevity causes confusion.

[robertjankowski]

Thank you for your comments!

I checked with the literature, and this kind of model is called the geometric soft configuration model. Hence, I propose to use it as a function name, i.e., geometric_soft_configuration_graph. What do you think?

I made beta as a keyword parameter and changed a few things in the doc string.

[dschult]

Nice Name! Thanks for coming up with that. :}

This review is getting into the weeds a little, but I think that means we are getting near the end. :)

It strikes me that kappa is always created by multiplying by kappa_0 and then used by dividing by kappa_0. Could we just scale out the kappa_0? Also the kappa_0 used when creating it is from a formula, while when dividing by it it seems to be the minimum value of all kappas. So, I might be getting confused by all that. But it seems that we could scale all the kappas by kappa_0 at some poin and reduce a lot of computation.

I was surprised to find that (kappa_c / kappa_0) ** (1 - gamma) is just 1 / n. Is this really right? or did I do some algebra mistake... That simplifies formulas quite a bit. I'm used to published formulas already being simplified. Are these from the publication?

It'd be great if we had test(s) which tested values. We've got a few checking e.g. that increasing beta decreases average clustering, and that beta<1 gives positive average clustering. Are there others? Perhaps with average degree while changing either the kappas or mean_degree?

[robertjankowski]

Thanks @dschult for the review! I think now it looks better.

Regarding the kappas you're right and we can simplify it. The equation I used allowed us to change the kappa cutoff (kappa_c), but in our case, it is defined using kappa_0.

I added a few more tests to check the connectivness and mean degree of the generated networks.

I hope we are close to finishing this PR :)

[robertjankowski]

Hi @dschult, do you have any further comments?

[dschult]

Two other nit-picky algebra simplifying comments.
We really are close... :)

[robertjankowski]

Thanks @dschult! I think this will be the last round :)

[dschult]

This looks good to me! Thanks @robertjankowski !!

[dschult]

minor tweaks -- spelling and add dispatch decorator support.

[rossbar]

Generally LGTM, thanks @robertjankowski

I left one minor comment inline, but my only real comment is that I'm not crazy about the overloaded signature - i.e. the fact that you use different incantations of the same function (either with n, gamma, and mean_degree or by directly providing the degree of each node with kappas). OTOH I can't really think of a better way to do it. The only idea that comes to mind is to create two functions, one named geometric_soft_configuration_graph which accepts kappa as input, and a second geometric_soft_configuration_from_powerlaw (e.g.) that accepts n, gamma, and mean_degree. YMMV on whether that's really any different/better (seems pretty subjective to me).

Another option would be to just drop the kappas route entirely. In your experience, is it common to have hidden-degree distributions known a priori? If this is a "someone might in principle want this" feature, then I'd be inclined to drop it for now and add it at the point where there's demand. If, however, this is something that comes up all the time in applications then dropping it would not make sense. I'm no expert so I defer to your opinion!

[rossbar]

Just a nit, but I don't think the list is necessary here - min should work over dict views.

Suggested change

	kappa_min = min(list(kappas.values()))
	kappa_min = min(kappas.values())

[robertjankowski]

Hi @rossbar! Thanks for your comment!

I would be more inclined to keep the definition of the function as it is, even though it might not be super clear for everyone. The point I wanted here to make is that this model is general enough to take any sequence of hidden degrees, and powerlaw distribution is just a particular (however often used) case. Splitting it into two functions might confuse some people since the logic would be the same in both functions. From my experience, it is useful to generate the graph from the predefined hidden degrees. For instance, you can first infer the kappas from the real network and use them as the input here to generate similar synthetic networks to your network.

[rossbar]

Sounds reasonable for me, thanks for taking the time to put together the summary!