Package: kuramoto
kuramotoPython implementation of the Kuramoto model.InstallpipinstallkuramotoFeaturesInteractions are represented as an adjacency matrixA, a 2D numpy ndarray.Interactions between oscillators are symmetric (i.e.,A = AT)Usageimportnumpyasnpimportmatplotlib.pyplotaspltimportnetworkxasnximportseabornassnsfromkuramotoimportKuramoto,plot_phase_coherence,plot_activitysns.set_style("whitegrid")sns.set_context("notebook",font_scale=1.6)# Instantiate a random graph and transform into an adjacency matrixgraph_nx=nx.erdos_renyi_graph(n=100,p=1)# p=1 -> all-to-all connectivitygraph=nx.to_numpy_array(graph_nx)# Instantiate model with parametersmodel=Kuramoto(coupling=3,dt=0.01,T=10,n_nodes=len(graph))# Run simulation - output is time series for all nodes (node vs time)act_mat=model.run(adj_mat=graph)# Plot all the time seriesplot_activity(act_mat)# Plot evolution of global order parameter R_tplot_phase_coherence(act_mat)# Plot oscillators in complex plane at times t = 0, 250, 500fig,axes=plt.subplots(ncols=3,nrows=1,figsize=(15,5),subplot_kw={"ylim":(-1.1,1.1),"xlim":(-1.1,1.1),"xlabel":r'$\cos(\theta)$',"ylabel":r'$\sin(\theta)$',})times=[0,200,500]forax,timeinzip(axes,times):ax.plot(np.cos(act_mat[:,time]),np.sin(act_mat[:,time]),'o',markersize=10)ax.set_title(f'Time ={time}')As a sanity check, let's look at the phase transition of the global order parameter (Rt) as a function of coupling (K) (find critical couplingKc) and compare with numerical results already published by English, 2008 (see Ref.) – we will match those model parameters.# Instantiate a random graph and transform into an adjacency matrixn_nodes=500graph_nx=nx.erdos_renyi_graph(n=n_nodes,p=1)# p=1 -> all-to-all connectivitygraph=nx.to_numpy_array(graph_nx)# Run model with different coupling (K) parameterscoupling_vals=np.linspace(0,0.6,100)runs=[]forcouplingincoupling_vals:model=Kuramoto(coupling=coupling,dt=0.1,T=500,n_nodes=n_nodes)model.natfreqs=np.random.normal(1,0.1,size=n_nodes)# reset natural frequenciesact_mat=model.run(adj_mat=graph)runs.append(act_mat)# Check that natural frequencies are correct (we need them for prediction of Kc)plt.figure()plt.hist(model.natfreqs)plt.xlabel('natural frequency')plt.ylabel('count')# Plot all time series for all coupling values (color coded)runs_array=np.array(runs)plt.figure()fori,couplinginenumerate(coupling_vals):plt.plot([model.phase_coherence(vec)forvecinruns_array[i,::].T],c=str(1-coupling),# higher -> darker)plt.ylabel(r'order parameter ($R_t$)')plt.xlabel('time')# Plot final Rt for each coupling valueplt.figure()fori,couplinginenumerate(coupling_vals):r_mean=np.mean([model.phase_coherence(vec)forvecinruns_array[i,:,-1000:].T])# mean over last 1000 stepsplt.scatter(coupling,r_mean,c='steelblue',s=20,alpha=0.7)# Predicted Kc – analytical result (from paper)Kc=np.sqrt(8/np.pi)*np.std(model.natfreqs)# analytical result (from paper)plt.vlines(Kc,0,1,linestyles='--',color='orange',label='analytical prediction')plt.legend()plt.grid(linestyle='--',alpha=0.8)plt.ylabel('order parameter (R)')plt.xlabel('coupling (K)')sns.despine()Kuramoto model 101TheKuramoto modelis used to study a wide range of systems with synchronization behaviour.It is a system ofNcoupled periodic oscillators.Each oscillator has its ownnatural frequencyomegai, i.e., constant angular velocity.Usually, the distribution of natural frequencies is choosen to be a gaussian-like symmetric function.A random initial (angular) positionthetaiis assigned to each oscillator.The oscillator's state (position)thetaiis governed by the following differential equation:where K is the coupling parameter andMiis the number of oscillators interacting with oscillatori.Ais theadjacency matrixenconding the interactions - typically binary and undirected (symmetric), such that if nodeiinteracts with nodej,Aij= 1, otherwise 0.
The basic idea is that, given two oscillators, the one running ahead is encouraged to slow down while the one running behind to accelerate.In particular, the classical set up hasM = N, since the interactions are all-to-all (i.e., a complete graph). Otherwise,Miis the degree of nodei.Kuramoto model 201A couple of facts in order to gain intuition about the model's behaviour:If synchronization occurs, it happens abruptly.That is, synchronization might not occur.Partial synchronization is a possible outcome.The order parameterRtmeasures global synchronization at timet. It is basically the normalized length of the sum of all vectors (oscillators in the complex plane).About the global order parameterRt:constant, in the double limit N -> inf, t -> infindependent of the initial conditionsdepends on coupling strengthit shows a sharp phase transition (as function of coupling)Steady solutions can be computed assumingRtconstant. The result is basically that each oscillator responds to the mean field produced by the rest.In the all-to-all connected scenaria, the critical couplingKccan be analytically computed and it depends on the spread of the natural frequencies distribution (see English, 2008)The higher the dimension of the lattice on which the oscillators are embedded, the easier it is to synchronize. For example, there isn't any good synchronization in one dimension, even with strong coupling. In two dimensions it is not clear yet. From 3 dimensions on, the model starts behaving more like the mean field prediction.For more and better details,this talkby the great Steven Strogatz is a nice primer.RequirementsnumpyscipymatplotlibFor the examples:bctpynetworkxseabornTestsRun tests withmaketestCitingIf you find this package useful for a publication, then please use the following BibTeX to cite it:@misc{kuramoto,
  author = {Damicelli, Fabrizio},
  title = {Python implementation of the Kuramoto model},
  year = {2019},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/fabridamicelli/kuramoto}},
}References & linksEnglish, 2008. Synchronization of oscillators: an ideal introduction to phase transitions.Dirk Brockmann's explorable. “Ride my Kuramotocycle!”.Math Insight - applet. The Kuramoto order parameters.Kuramoto, Y. (1984). Chemical Oscillations, Waves, and Turbulence.Steven Strogatz - talk. Coupled Oscillators That Synchronize Themselves