The User’s Guide to the Solar Dynamo Code

SURYA
Arnab Rai Choudhuri
Department of Physics
Indian Institute of Science
Bangalore - 560012, India
29 November 2005

1 Introduction
The code SURYA1 for studying the solar dynamo problem is the final version
of a code which was developed in several stages by me and my successive Ph.D.
students—Mausumi Dikpati, Dibyendu Nandy and Piyali Chatterjee—all work-
ing at the Indian Institute of Science, Bangalore. It is a FORTRAN code aimed
at solving the two-dimensional kinematic dynamo problem in a spherical shell
(appropriate for the solar convection zone) in the presence of a meridional cir-
culation. The basic mathematical equations have been discussed by Chatterjee,
Nandy & Choudhuri (2004, hereafter CNC). For the benefit of the users, we
present the equations in §2 of this user’s guide (without any detailed discus-
sion). CNC present a solution in §3.1 and §4 of their paper, which reproduces
many features of the solar cycle. CNC refer to this as their standard solution.
The various parameters in SURYA have been set to values which correspond to
this standard solution of CNC.
The code SURYA is being made available for public use from 1 December,
2005. We are sending the code and this Guide to anybody who sends a request
through e-mail to me at
arnab@physics.iisc.ernet.in
To the best of our knowledge, this is the first time a solar dynamo code is being
made public. Until we had made our code public, any new group planning to
work on the solar dynamo problem had to develop a code from scratch and
had to first repeat the calculations of other groups before getting into new
research problems. We hope that SURYA will help any group to get into the
field of solar dynamo quickly and we anticipate that many groups will soon get
into this field (at the end of 2005, too few groups in the world are working on
the important subject of the solar dynamo!). We have tried our best to make
SURYA sufficiently user-friendly. With the help of this user’s guide, any person
1 Surya is a Sanskrit word meaning the Sun.

1
familiar with the basic physics of the subject should be able to use this code.
Any person is most welcome to use this code for his or her research. You do not
have to include any of the originators of the code as co-authors. However, if you
publish a paper for which you have made use of SURYA, we request that you
mention it in the Abstract, Introduction and Acknowledgments of your paper,
and you refer to at least two of our papers (Nandy & Choudhuri 2002; CNC),
in which our model of the solar dynamo based on SURYA was presented. Enjoy
using SURYA!
When you use somebody else’s code, what do you want to do with it? Some
users may want to run the code treating it as a black box, at the most chang-
ing some parameters like the value of magnetic diffusivity or the amplitude of
meridional circulation. At the other extreme, there may be some users who may
want to understand every line of the code (I do hope that there will be some
like that!). Since I would like this user’s guide to be helpful for these extreme
kinds of users, I divide all potential users of SURYA into three levels. I now
describe these three levels, indicating which portions of this guide should be
read by users at these different levels.

• Level I Users. Users at this level may want to use the code as a black
box. Such users should be able to start using the code after reading only
§3, which describes how SURYA can be run (explaining such issues as what
sorts of input are needed or what will be nature of the outputs). I also
describe in §3 a small portion of SURYA where values are set for some of
the basic parameters. Users at this level may want to make changes only
in this small portion of SURYA and leave the rest of the code untouched.
It will not be necessary for readers at this level to read §4 or §5.
• Level II Users. Users at this level may want to make more substantial
changes without trying to understand everything. For example, they may
want to study the dynamo action in other stars by varying the depth of
the convection zone. They may also want to change the nature of the
meridional circulation (by making it two-celled instead of one-celled) or
the nature of the angular velocity distribution (making it constant over
cylinders rather than over cones). It will be necessary for such readers
to understand the structure of the code. Such readers should go beyond
§3 and read §4, where I explain how the code is structured. For users at
this level, it is still not necessary to understand how the partial differential
equations of the problem are treated by suitable difference schemes. Hence
this topic is not discussed in §4. After reading §3 and §4, users at this
level should be able to use the code without reading §5.
• Level III Users. A user at this final level may want to learn everything in
the code inside out as throughly as if the code has been written by him/her.
The heart of a numerical code lies in the difference schemes which are used
to replace the original differential equations. The difference schemes used
by us are explained in §5. Users at this level have to read §3, §4 and §5
to acquire a complete mastery over the code.

2
 I assume in this guide that you are already familiar with the solar dynamo
theory at a reasonable level of technical depth. Readers desirous of learning the
basics of the subject may first read Chapter 16 of Choudhuri (1998) and then a
review article by me (Choudhuri 2003). Afterwards, the reader should be able
to follow the papers by Nandy and Choudhuri (2002) and CNC. Several publi-
cations already resulted from SURYA, its earlier versions or modified versions
(Dikpati & Choudhuri 1994, 1995; Choudhuri, Schs̈sler & Dikpati 1995; Choud-
huri & Dikpati 1999; Nandy & Choudhuri 2001, 2002; Choudhuri & Konar 2002;
Konar & Choudhuri 2004; Chatterjee, Nandy & Choudhuri 2004; Choudhuri,
Chatterjee & Nandy 2004).
If any user finds any mistake in the code or the guide, or if something is not
clear in the guide, please inform me by sending an e-mail. While we have done
all reasonable checks, authors of a complicated code can never be 100% sure
that the code is completely free of errors!

2 Mathematical formulation
We now summarize the main equations in §2.1. Consult §2 of CNC for more
details. Then §2.2 lists the expressions we use in the code for the various quan-
tities.

2.1 The basic equations

An axisymmetric magnetic field can be represented in the form

B = B(r, θ)eφ + ∇ × [A(r, θ)eφ ], (1)

where B(r, θ) and A(r, θ) respectively correspond to the toroidal and poloidal
components. The standard equations for the so-called αω dynamo problem are:
µ ¶
∂A 1 1
+ (v.∇)(sA) = ηp ∇2 − 2 A + αB, (2)
∂t s s
· ¸ µ ¶
∂B 1 ∂ ∂ 2 1 1 dηt ∂
+ (rvr B) + (vθ B) = ηt ∇ − 2 B + s(Bp .∇)Ω + (rB)
∂t r ∂r ∂θ s r dr ∂r
(3)

where s = r sin θ. Here v is the meridional flow, Ω is the internal angular

velocity of the Sun and α is the coefficient which describes the generation of
poloidal field at the solar surface from the decay of bipolar sunspots. We allow
the turbulent diffusivities ηp and ηt for the poloidal and toroidal components
to be different. We describe below how we specify v, Ω, ηp , ηt , and α. Once
these quantities are specified, we can solve (2) and (3) to study the behaviour of
the dynamo. Apart from the specification of these parameters, we also include
magnetic buoyancy in a way described below. We carry out our calculations in
a meridional slab Rb = 0.55R⊙ < r < R⊙ , 0 < θ < π.

3
 Boundary conditions. At the poles (θ = 0, π) we have

A = 0, B = 0. (4)

Assuming a perfectly conducting solar core, the bottom boundary (r = Rb )

condition is taken as
A = 0, B = 0. (5)
At the top (r = R⊙ ), the toroidal field has to be zero (B = 0) and A has to
match smoothly to a potential field satisfying the free space equation
µ ¶
1
∇2 − 2 2 A = 0. (6)
r sin θ

Dikpati and Choudhuri (1994) describe how this is done.

Differential rotation. We use the following analytic form to represent the
solar internal rotation:
· µ ¶¸
1 r − rt
Ω(r, θ) = ΩRZ + 1 + erf [ΩSCZ (θ) − ΩRZ ] . (7)
2 dt

This analytical expression fits the results of helioseismology fairly closely for
the following values of parameters which we use: rt = 0.7R⊙ , dt = 0.025R⊙
ΩRZ /2π = 432.8 nHz, ΩSCZ (θ) = ΩEQ +α2 cos2 (θ)+α4 cos4 (θ), with ΩEQ /2π =
460.7 nHz, α2 /2π = −62.69 nHz and α4 /2π = −67.13 nHz. A contour plot of
Ω generated by the above expression is shown in Fig. 1 of CNC.
Meridional circulation. We now describe how the meridional circulation
is specified in the northern hemisphere. The circulation in the southern hemi-
sphere is simply obtained by a mirror reflection of the velocity field across the
equator. We get the meridional circulation from the stream function ψ defined
through the equation
ρv = ∇ × [ψ(r, θ)eφ ]. (8)
Assuming a density stratification
µ ¶m
R⊙
ρ=C −γ , (9)
r

we take
· ¸
π(r − Rp ) 2
{1 − e−β1 θ }{1 − eβ2(θ−π/2) }e−((r−r0)/Γ)
ǫ
ψr sin θ = ψ0 (r − Rp ) sin
(R⊙ − Rp )
(10)
with the following values of the parameters: β1 = 1.5, β2 = 1.8, ǫ = 2.0000001,
r0 = (R⊙ − Rb )/4.0, Γ = 3.47 × 108 m, γ = 0.95, m = 3/2. It is the parameter
Rp which determines the depth to which the meridional circulation penetrates
and is taken as Rp = 0.61R⊙ . Fig. 2 of CNC shows the streamlines of the
meridional circulation. It may be noted that the expression for ψ as given in
CNC had some typographical errors, and the values of β1 and β2 were also given

4
wrongly there (see Choudhuri, Nandy & Chatterjee 2005). The amplitude of the
meridional circulation is chosen such that vθ near the surface at mid-latitudes
is about 29 m s−1 . This is mistakenly quoted in CNC as 22 m s−1 .
Diffusivity. We take the diffusivity for the poloidal component to be
· µ ¶¸
ηSCZ r − rBCZ
ηp (r) = ηRZ + 1 + erf (11)
2 dt

with the following values of the parameters: ηSCZ = 2.6 × 1012 cm2 s−1 , ηRZ =
2.2 × 108 cm2 s−1 , rBCZ = 0.7R⊙ , dt = 0.025R⊙. The diffusivity of the toroidal
component is given by
′
· µ ¶¸ · µ ¶¸
ηSCZ1 r − rBCZ ηSCZ r − rT CZ
ηt (r) = ηRZ + 1 + erf + 1 + erf
2 dt 2 dt
(12)
with ηSCZ1 = 4 × 1010cm2 s−1 , rBCZ′
= 0.72R⊙ and rT CZ = 0.975R⊙, the value
of ηSCZ being 2.6 × 1012 cm2 s−1 as specified earlier. Plots of ηp (r) and ηt (r)
are shown in Fig. 4 of CNC. A wrong value rT CZ = 0.95R⊙ was mistakenly
given in CNC. It may also be noted CNC took ηSCZ = 2.4 × 1012cm2 s−1 . Even
this value of ηSCZ gives good results with preference for a solution which is
approximately dipolar. However, on increasing ηSCZ slightly (as we have done
now), the preferred solution is more strictly dipolar.
α coefficient. The α coefficient is taken in the form
· µ ¶¸ · µ ¶¸
1 r − r1 r − r2
α(r, θ) = α0 cos θ 1 + erf × 1 − erf . (13)
4 d1 d2

The parameters we use are r1 = 0.95R⊙ , r2 = R⊙ , d1 = d2 = 0.025R⊙ , α0 = 25

m s−1 . Note that we have not included α quenching. The nonlinear suppression
of magnetic field growth is provided by magnetic buoyancy in our problem.
Magnetic buoyancy. We prescribe magnetic buoyancy in a way which has
been discussed in detail by Nandy & Choudhuri (2001). We search for toroidal
field B exceeding the critical field Bc = 105 G, above the base of the SCZ taken
at r = 0.71R⊙ at intervals of time τ = 8.8 × 105 s. Wherever B exceeds Bc , a
fraction f = 0.5 of it is made to erupt to the surface layers, with the toroidal
field values adjusted appropriately to ensure flux conservation. Although A and
B in general evolve according to (2) and (3), we allow abrupt changes in B after
intervals of τ to take account of magnetic buoyancy.

2.2 Representation of various quantities in the code

The code solves the equations over a n+1 times n+1 grid in the r and θ direc-
tions. We have nmax = n+1 = 129 as the default setting. We use the index
i to denote successive grid points in the r direction and the index j to denote
successive grid points in the θ direction. Table I lists how various quantities
(denoted by different symbols in CNC and §2.1 above) are represented in our
code.

5
 r p
θ q
A(r, θ) u(i,j)
B(r, θ) ub(i,j)
R⊙ pm
Rb pb
α(r, θ) al(i,j)
α0 al0
Ω(r, θ) dom(i,j)
ηp (r) eta(i,j)
ηt (r) etab(i,j)
ηSCZ et0
ηSCZ1 et1
r sin θψ(r, θ) psi(i,j)
Rp pp
β1 beta1
β2 beta2
Γ gam
ǫ del
vr (r, θ) vp1(i,j)
vθ (r, θ) vq1(i,j)
∆r dp
∆θ dq

Table 1: Symbols used in the code for various quantities. The first column
indicates the symbols used in CNC as well as this guide, whereas the second
column indicates the symbols used in the code.

6
3 Instructions for Level I Users
All the parameters which Level I Users may like to play with are put in PART I
at the beginning of the code.
Let me begin by explaining the parameter irelax, which has to be set to
either 0 or 1. If α is super-critical (the code is set with a super-critical α), then
you will get a relaxation to a periodic solution starting from any arbitrary initial
state. If irelax = 0 (which is the present setting), then the code generates an
initial state (in PART III) and advances it in time to relax to a periodic solution.
On the other hand, sometimes you may want to begin with a previous solution
and advance it for some more time. Then you have to set irelax = 1 and have
to provide the initial state in a file init.dat in the same directory (no extra file is
required if the code is run with the setting irelax = 0). We shall discuss below
the output files which are generated by the code. Whenever the code runs, the
final state is written in a file final.dat. When you want to run the code with
irelax = 1 setting, you usually copy some final.dat file produced in an earlier
run as your init.dat file.
Before telling you about the other parameters, I have to specify the units
used in the code. We take 1010 cm as the unit of length and 108 s as the unit
of time. Hence the radius of the Sun is 6.96 in our units and a year is equal to
0.315. The unit of velocity is m s−1 , whereas the unit of diffusivity is 1012 cm2
s−1 . We get ηSCZ = 2.6 × 1012 cm2 s−1 by setting et0=2.6d0. We now explain
the significances of the various parameters in PART I.
• v0 : This is the amplitude of meridional circulation, which is essentially
the poleward velocity near the surface at mid-latitudes. We take this
velocity to be 29 m s−1 .
• et0 : This is ηSCZ appearing in (11), which is the diffusivity of the poloidal
field within the convection zone. This is taken as 2.6×1012 cm2 s−1 , which
is slightly higher than what was used by CNC.
• et1 : This is ηSCZ1 appearing in (12), which is the diffusivity of the
toroidal field within the convection zone (except a shallow layer near the
surface). This is taken as 4.0 × 1010 cm2 s−1 in the standard solution.
• al0 : This is the amplitude of α (i.e. α0 appearing in (13)). The standard
solution uses α0 = 25 m s−1 , which makes the dynamo somewhat super-
critical—though not very highly so.
The other parameters in PART I are dt and tmax, which respectively give the
time step and the time interval for which the code is run. In case you increase v0,
you need to ensure that dt satisfies the Courant condition. We have presently
set tmax=50.0d0. If you run the code with irelax=0, then this tmax provides
sufficient time in which the initial state generated by the code (which is of
quadrupolar nature) relaxes to a periodic dynamo solution with quadrupolar
parity. If you want to see how the quadrupolar parity changes over to a dipolar

7
parity, then you have to give a run with tmax=1000.0d0 (which is about 3000
yr).
We now describe the output files which are generated when you run the code.
• psi.dat : The 3 columns in this file are θ, r and r sin θψ(r, θ). If you plot
contours of the quantity in the third column in the r-θ plane, then you
will get the streamlines of meridional circulation.
• diffrot.dat : The 3 columns in this file are θ, r and Ω(r, θ). If you plot
contours of the quantity in the third column in the r-θ plane, then you
will get the differential rotation which is a close representation of what is
found from helioseismology.
• final.dat : The final state at the end of the run is put in this file. The 4
columns give θ, r, r sin θA(r, θ) and B(r, θ). You can get the poloidal field
lines by plotting contours of the quantity in the third column in the r-θ
plane, whereas the contours of the quantity in the fourth column tell you
how the toroidal field is distributed.
• run.dat : The first column is time, whereas the other columns give values
of A and B at some points. By plotting the numbers from any of these
other columns against the numbers from the first column, you can check
if the code is relaxing to a periodic solution.
• ber.dat : Whenever B exceeds the critical value Bc at some point with
r > 0.71R⊙ and a buoyant eruption takes place (see Magnetic buoyancy
in §2.1), an entry is made into this file. The first column is the time t of
eruption, the second column is the co-latitude θ of eruption and the last
column gives the value of B just before the eruption. The first two columns
of each line will give a point in the t–θ plane. By plotting all such points
from the different lines of ber.dat, you can get the butterfly diagram.
• butbot.dat : After every few time steps, the values of B(r = rBCZ , θ)
at the bottom of the convection zone are written in this file. The three
columns give t, θ and B(r = rBCZ , θ). You can plot the contours of
B(r = rBCZ , θ) in the t–θ plane. The eruptions take place (as given in
the file ber.dat) where B is strongest.
• rad.dat : After every few time steps, the values of Br (R⊙ , θ), i.e. the
radial magnetic field at the solar surface, are written in this file. The three
columns give t, θ and Br (R⊙ , θ). By plotting the contours of Br (R⊙ , θ)
in the t–θ plane, you can see how the radial field at the surface is evolving
with time.
You obviously need some graphics software to produce appropriate plots
from the output files. We have used MATLAB to generate the plots presented
in CNC. You can use your favourite graphics software to write some programmes
which will take the output files and produce the necessary plots.

8
 Once you have developed the plotting programmes to produce the necessary
plots, you will be ready to use the code and study its output. I suggest the
following exercises to acquire some familiarity with the code. First run the
code as it is. Since we have set irelax=0 in the code, no additional files are
required to run the code. You will see that the code will generate the output
files described above. You can produce the various plots from the output data
using the plotting programmes you have developed. Then you change irelax
from 0 to 1 in the code and create the init.dat file with the Unix command
cp final.dat init.dat
You now run the code again after setting tmax to a smaller value. You will see
that the code will now advance the initial state in time. If you want to get the re-
laxation to a dipolar state, then you have to run the code with tmax=1000.0d0,
which will take several hours in a typical workstation.

4 Instructions for Level II Users

Level II Users should understand the structure of the code and should be able
to make changes in PART II, which prescribes the α coefficient, the diffusivity,
the differential rotation and the meridional circulation. Let us first describe the
various parts of the code, which will give an idea of its structure.
• PART I : This part specifies the values of some basic parameters which
Level I Users may wish to change. This part has already been described
in §3 above.
• PART II : It is this part which prescribes the α coefficient, the diffusivity,
the differential rotation and the meridional circulation. Level II Users may
wish to make changes in this part. Some more discussion of this part will
be given below. This part also generates the output files diffrot.dat and
psi.dat, which can be used to plot the profiles of differential rotation and
meridional circulation (see §3).
• PART III : The initial magnetic field which will be advanced by the code
is made ready here. If you have given irelax = 0 in PART I, then a
quadrupolar initial state will be generated. On the other hand, if you
have given irelax = 1, then the code reads the initial state from the file
init.dat.
• PART IV : The code replaces the differential equations by certain dif-
ference schemes. These difference schemes, which are described in detail
in §5, lead to certain matrix equations. The coefficients of these matrix
equations are calculated and stored in this part. The expressions for these
matrix coefficients are given in §5.
• PART V : At last we are ready to advance the initial state through suc-
cessive time steps, which is done here inside a mammoth do loop. This do
loop begins with the statement

9
 do k=1,kend
at the very beginning of this part and ends at the end. As we shall see in
§5, advancing the magnetic field at an interior grid point involves solving
a tridiagonal matrix. §5 describes this and explains in more detail what
is done in Part V. As the magnetic field is advanced in time, some rele-
vant data are continously written in the output files ber.dat, butbot.dat,
rad.dat and run.dat, which have been described in §3.
• PART VI : When the run is finished, the final magnetic field at the end
is written in the file final.dat (described in §3).

PART I, the only part which can be modified by Level I Users, has already
been discussed in §3. On the other hand, only Level III Users would like to
know in detail what is in PARTS IV or V. So these parts will be discussed in
§5. It is unlikely that anybody would want to modify PART III or PART VI.
In any case, these parts are small and easy to understand. So we now turn to
the only remaining part—PART II—which Level II Users may want to change.
At the very beginning of PART II, α(r, θ), ηp (r), ηb (r) and Ω(r, θ) (check
Table I to figure out how they are represented in the code), as given by (13),
(11), (12) and (7) respectively, are calculated at all the grid points and are
stored. Users who wish to use different forms of these parameters will have to
make changes here. We then calculate and store ∂Ω/∂r and ∂Ω/dθ, denoted
by dror(i,j) and drot(i,j), since these derivatives are often needed. Finally, a
large portion of PART II is devoted to calculating the velocity field. We first
calculate ψr sin θ, as given by (10) and denoted as psi(i,j) in the code. Then the
components of velocity vr and vθ , denoted in the code by vp1(i,j) and vq1(i,j),
are calculated by making use of (8) and (9). The multiplication by the factor
0.95d0 in the code ensures that the maximum value of vθ near the surface turns
out to be equal to v0. Finally, vp(i,j) and vq(i,j) correspond to

vr ∆t vθ ∆t
and .
r 2∆r r sin θ 2∆θ
These appear in the expressions of matrix coefficients, as we shall see in §5.
One extremely important point to note here is that the difference schemes
used by us require values of ηb (r), vr and vθ in the mid-points of the grid in
addition to the grid points. Values of ηb (r) calculated at intervals of ∆r/2 are
stored as etab2(i,j). While calculating the stream function and the velocity
components, we use a 2*n +1 by 2*n +1 matrix which includes both the grid-
points and their mid-points. It should be kept in mind that the value of psi(i,j)
(for example) at the grid point (i+1, j+1) is stored as psi(2*i+1,2*j+1).

5 Instructions for Level III Users

We now discuss how the differential equations are replaced by difference equa-
tions and how these are used to advance the magnetic field in time. These are

10
implemented in PARTS IV and V of the code. We first discuss the basic princi-
ples of how these are done. Then we shall make a few comments on the contents
of PARTS IV and V at the end of this section.
To advance the magnetic field in time, we have to solve (2) and (3), which
are of the form
∂A
= [Lr + Lθ ] A + QA , (14)
∂t
∂B
= [Mr + Mθ ] B + QB . (15)
∂t
Here Lr and Mr are the operators involving r derivatives, while Lθ and Mθ are
the operators involving θ derivatives; QA = αB and QB = s(Bp .∇)Ω are the
source terms for A and B respectively.
We now discuss in some detail how (14) is solved by using a suitable dif-
ferencing scheme. Since (15) has a similar form and is solved by an exactly
analogous method, a detailed discussion of the solution of (15) is unnecessary.
As it is straightforward to handle the source terms QA and QB explicitly, we
first discuss the solution of (14) as if the source term QA is not present. One
can easily see from (2) that the operators Lr and Lθ are given by
· 2 ¸
vr ∂ ∂ A 2 ∂A A
Lr A = − (rA) + η + − 2 2 , (16)
r ∂r ∂r2 r ∂r 2r sin θ

1 ∂2A
· ¸
vθ ∂ cot θ ∂A A
Lθ A = − (sin θA) + η 2 + 2 − 2 2 . (17)
r sin θ ∂θ r ∂θ2 r ∂θ 2r sin θ
We employ the Alternating Direction Implicit (ADI) method of differencing
(Press et al. 1988, §17.6) to solve (14). In this method, each time-step is divided
into two half-steps. In the first half-step, any one direction (say r) is advanced
explicitly and the other direction (say θ) is advanced implicitly. In the second
half-step, the treatment of the two different dimensions are reversed, i.e., the r
direction is treated implicitly and the θ direction explicitly. Suppose that Am i,j
is the value of A at the grid point (i, j) at time step m. Then the ADI scheme
consists of the following two time steps:

m+ 12 m+ 12 ∆t
Ai,j − Am m
i,j = (Lr Ai,j + Lθ Ai,j ) , (18)
2
m+ 12 m+ 12 ∆t
Am+1
i,j − Ai,j = (Lr Am+1
i,j + Lθ Ai,j ) , (19)
2
if we do not include the source term QA for the time being. Here Lr and Lθ are
the difference forms of the operators Lr and Lθ , which have to be worked out
from some suitable differencing schemes.
We handle the diffusion terms through fairly straightforward differencing
schemes in which ∂ 2 A/∂r2 is replaced by

Ai+1,j + Ai−1,j − 2Ai,j

.
(∆r)2

11
Differencing the diffusion term in this way, if we treat it explicitly in one half-
step and implicitly in the next half-step, then the whole process is analogous
to treating the diffusion term through the Crank–Nicholson scheme (Press et
al. 1988, §17.2). The advection terms are handled by the Lax–Wendroff scheme
(Press et al. 1988, §17.1), which is a little bit more complicated. To explain how
we handle the
vr ∂
− (rA)
r ∂r
term in (16), let us consider the equation

∂A vr ∂
=− (rA), (20)
∂t r ∂r
which we want to difference by the Lax-Wendroff scheme and advance by half-
step ∆t/2. Then we first have to advance by quarter-step using the scheme

m+ 1 1 m ∆t vr (i + 12 ) £
(Ai+1 + Am (r + ∆r) Am m
¤
Ai+ 1 4 = i )− ∆r i+1 − rAi . (21)
2 2 4∆r r + 2

The advance by half-step is then given by

·µ ¶ µ ¶ ¸
m+ 1 ∆t vr (i) ∆r m+ 14 ∆r m+ 14
Ai 2 = Am i − r + Ai+ 12
− r − Ai− 12
(22)
2∆r r 2 2
m+ 1 m+ 1
Using (21) to substitute for Ai+ 1 4 and Ai− 1 4 in (22), we can have the full
2 2
expression for advancement by half time-step. Treating the various terms as
explained above, it can be shown that Lr and Lθ introduced in (18) and (19)
have the following forms:
∆t
− Lr Am m m m
i,j = d(i, j)Ai−1,j + e(i, j)Ai,j + f (i, j)Ai+1,j , (23)
2
∆t
− Lθ Am m m m
i,j = a(i, j)Ai,j−1 + b(i, j)Ai,j + c(i, j)Ai,j+1 . (24)
2
The coefficients appearing in the above matrix equations, a(i, j), b(i, j),
c(i, j), d(i, j), e(i, j) and f (i, j), can be evaluated by some messy but straight-
forward algebra. They are
·
2 η Uθ (i, j) ∆θ 1
− a(i, j) = + sin(θ − )
∆t (r∆θ)2 ∆θ 2 2
¸
∆t 1
+ Uθ (i, j − ) sin(θ − ∆θ) , (25)
4∆θ 2
2 2η η cot θ η
− b(i, j) = − − 2 − 2 2
∆t (r∆θ)2 r ∆θ 2r sin θ
· ½
Uθ (i, j) ∆θ 1
− sin(θ + )
∆θ 2 2

12
 ¾
∆t 1
+ Uθ (i, j + ) sin θ
4∆θ 2
½
∆θ 1
− sin(θ − )
2 2
¾¸
∆t 1
− Uθ (i, j − ) sin θ , (26)
4∆θ 2
·
2 η η cot θ Uθ (i, j) ∆θ 1
− c(i, j) = + − sin(θ + )
∆t (r∆θ)2 r2 ∆θ ∆θ 2 2
¸
∆t 1
− Uθ (i, j + ) sin(θ + ∆θ) , (27)
4∆θ 2
·
2 η Ur (i, j) ∆r 1
− d(i, j) = + (r − )
∆t (∆r)2 ∆r 2 2
¸
∆t 1
+ Ur (i − , j)(r − ∆r) , (28)
4∆r 2
·
2 2η 2η η Ur (i, j) ∆r
− e(i, j) = − − − −
∆t (∆r)2 r∆r 2r2 sin2 θ ∆r 2
½
∆t 1 ∆r
+ r Ur (i + , j)(r + )
4∆r 2 2
¾¸
1 ∆r
+Ur (i − , j)(r − ) , (29)
2 2
·
2 η 2η Ur (i, j) ∆r 1
− f (i, j) = + − (r + )
∆t (∆r)2 r∆r ∆r 2 2
¸
∆t 1
− Ur (i + , j)(r + ∆r) , (30)
4∆r 2
where Ur (i, j) and Uθ (i, j) respectively give the values of vr /r and vθ /(r sin θ)
at the grid point i, j.
We are now ready to explain how the magnetic field is advanced in time in
the code. On making use of (23) and (24), we can write (18) in the form
m+ 1 m+ 12 m+ 1
a(i, j)Ai,j−12 + [1 + b(i, j)]Ai,j + c(i, j)Ai,j+12 = Φ(i, j), (31)

where
Φ(i, j) = −d(i, j)Am m m
i−1,j + [1 − e(i, j)]Ai,j − f (i, j)Ai+1,j . (32)
Suppose we know the magnetic field at all grid points at time step m, i.e. we
know Am
i,j for all (i, j). Then we can easily evaluate Φ(i, j) at any grid point by
m+ 1
using (32). Our job now is to find Ai,j 2 at all grid points at time step m + 12 .
Incidentally, the source term QA appearing in (14) can be easily included in the
computations by evaluating QA at all grid points at time m and then adding a
term QA ∆t/2 on the right hand side of (32). This is done in the code. To solve
m+ 1
for Ai,j 2 , we note that we get an equation of type (31) for each value of j. The
coefficients of all these equations make up a tridiagonal matrix. This matrix

13
 m+ 1
equation is solved in the code by using a subroutine and the values of Ai,j 2
at all grid points are obtained. To advance for the next half-step, we have to
use (19) instead of (18). This leads to equations slightly different from (31) and
(32), which are handled in a similar way.
There is no need to discuss in detail how the toroidal field B is advanced in
time by solving (15), since the procedure is completely analogous. On differenc-
ing the various terms in the equations suitably, Mr and Mθ lead to operators of
the form
∆t m m m m
− M r Bi,j = db (i, j)Bi−1,j + eb (i, j)Bi,j + fb (i, j)Bi+1,j , (33)
2
∆t m m m m
−M θ Bi,j = ab (i, j)Bi,j−1 + bb (i, j)Bi,j + cb (i, j)Bi,j+1 . (34)
2
These matrix elements for the toroidal field can be calculated in exactly the
same way as the other matrix elements for the poloidal field. Here we only give
the expressions of the matrix elements for the toroidal field.

Uθ (i, j − 12 )
·
2 ηb ∆θ 1
− ab (i, j) = + sin(θ − ) +
∆t (r∆θ)2 ∆θ 2 2
¸
∆t
Uθ (i, j − 1) sin(θ − ∆θ) (35)
4∆θ
2 2ηb ηb cot θ ηb
− bb (i, j) = − 2
− 2 − 2 2 −
∆t (r∆θ) r ∆θ 2r sin θ
Uθ (i, j + 12 )
· ½
∆θ 1
sin(θ + ) +
∆θ 2 2
Uθ (i, j − 12 )
¾
∆t
Uθ (i, j) sin θ −
4∆θ ∆θ
½ ¾¸
∆θ 1 ∆t
sin(θ − ) − Uθ (i, j) sin θ (36)
2 2 4∆θ
2 ηb ηb cot θ Uθ (i, j + 12 )
− cb (i, j) = + −
∆t (r∆θ)2 r2 ∆θ ∆θ
· ¸
∆θ 1 ∆t ∆θ
sin(θ + ) − Uθ (i, j + 1) sin(θ + ) (37)
2 2 4∆θ 2

2 ηb U r (i, j) ∆r
− db (i, j) = 2 + (r − )
∆t ∆r 2
·∆r ¸
1 ∆t 1
+ U r (i − , j)(r − ∆r) (38)
2 4∆r 2
2 2ηb 2ηb ηb
− eb (i, j) = − 2− − 2 2
∆t ∆r r∆r 2r sin θ
·
′
U r (i, j) ∆r r∆t
−U r (i, j) − +
∆r 2 4∆r

14
 ½
1 ∆r
U r (i + , j)(r + )
2 2
¾¸
∆r 1
+(r − )U r (i − , j) (39)
2 2
2 ηb ηb U r (i, j)
− fb (i, j) = + −
∆t ∆r2 r∆r· ∆r ¸
∆r 1 ∆t 1 ∆r
(r + ) − U r (i + , j)(r + ) , (40)
2 2 4∆r 2 2
where U r = (Ur − dη/dr)/r.
We are now ready to look at PARTS IV and V in the code, which implement
what we have so far discussed in this section. In the beginning of PART IV, the
coefficients a(i, j), b(i, j), c(i, j), d(i, j), e(i, j) and f (i, j), as given by (25)–(30),
are calculated at all the grid points and stored for future use. After that, the
other coefficients ab (i, j), bb (i, j), cb (i, j), db (i, j), eb (i, j) and fb (i, j), as given by
(35)–(40), are calculated and stored. Once we have all these matrix coefficients,
we are ready to advance the magnetic field in time, which is done in PART V.
PART V is essentially a mammoth do loop, in which each count of the
counter k advances the magnetic field by a time interval ∆t. Various sub-parts
inside this mammoth do loop (PARTS V-A, V-B, V-C and V-D) do various
things which we describe now. PART V-A advances the magnetic field in the
interior grid points, which involves the following four successive operations: (i)
advancing A through a half-step using (18); (ii) advancing B similarly through
the half-step; (iii) advancing A through the next half-step using (19); and (iv)
advancing B similarly through the next half-step. Each of these operations in-
volves solving a tridiagonal matrix equation of the form (31). This is done with
the subroutine tridag. The boundary conditions are implemented in PART V-B
by advancing A and B suitably on the boundaries. All the boundary conditions
except the condition for A on the upper boundary are completely straightfor-
ward. The upper boundary condition for A is that it has to smoothly match
a potential field outside. Dikpati and Choudhuri (1994) describe how this is
done. We need to use Legendre polynomials which are calculated and stored
in PART II-A with the help of some subroutines at the end of the programme.
Although A and B usually evolve smoothly, we check after intervals of time
8.8 × 105 s if B has exceeded Bc at any point above 0.71R⊙ and implement
magnetic buoyancy as described in §2.1. This is done in PART V-C, which
also writes the necessary data about eruptions in the file ber.dat. Finally, with
the advance in time, some data are written in the files butbot.dat, rad.dat
and run.dat in PART V-D. The output files ber.dat, butbot.dat, rad.dat and
run.dat are all described in §3.

6 Conclusion
It will be helpful to keep in mind that this code was developed by working
dynamo theorists and not by professional numerical analysts. Also, the code

15
evolved over the years, different people contributing different parts, written with
the assumption that only insiders who knew the code completely would ever use
it. Although I have tried my best to overhaul the code completely and make
it sufficiently user-friendly, traces of the historical process by which the code
evolved are still too apparent in its body. It is certainly not a code designed
from the beginning for public use and written with uniformity of style or strict
logical consistency. Virtually all the comment statements have been introduced
by me recently. In spite of some awkwardnesses remaining, it should be possible
for somebody familiar with the solar dynamo problem to master the code with
the help of this guide and thereby save several months of work, which would
have been necessary to develop such a code from scratch.
A user may first wish to reproduce some of the results reported in the solar
dynamo literature before getting into other things. You may verify that the
quadrupolar mode gets preferred on reducing the value of ηSCZ (et0 in the code).
Remember to run for at least tmax = 1000 to check the preferred parity. Also,
the nature of the solution depends on the penetration depth of the meridional
circulation. This you can change by varying Rp (pp in the code) and see the
outcome. Most importantly, you may be intrigued to discover for yourself that
the solution changes dramatically on treating the magnetic buoyancy differently,
following the approach of Dikpati & Charbonneau (1999). Dikpati et al. (2005)
were unable to reproduce the results of CNC—primarily because they treated
the magnetic buoyancy differently (see Choudhuri, Nandy & Chatterjee 2005).
If you want to reproduce the results which Dikpati et al. (2005) presented in
their paper, then first delete or comment out PART V-C completely. Check
that al(i,j)*ub(i,j) occurs twice in PART V-A while calculating phi(i,j). In
those places, replace al(i,j)*ub(i,j) by
al(i,j)*ub(45,j)/(1.0d0+ub(45,j)*ub(45,j))
(assuming that you have left nmax unchanged from the value 129). Note that
it is now necessary to include the α-quenching, which was not needed in our
standard model because our buoyancy mechanism provided the nonlinear sup-
pression of dynamo growth. On running the code with these small changes, you
will get the solution presented in §3.2 and §3.3 of Dikpati et el. (2005).
The number of people around the world working on different aspects of the
solar cycle is quite large. In contrast, the number of persons who actually try to
understand the origin of this cycle is completely insignificant. This has always
seemed like a paradox to me. This situation should change as solar dynamo
models become more realistic and it becomes possible to compare different as-
pects of observational data with detailed predictions of dynamo models. Solar
and stellar dynamo theory is currently at a stage of rapid development. How-
ever, until we made this code public, it was not possible to get into this field
very quickly, since it required several months’ initial investment to develop a
code, and only a handful of groups around the world had a monopoly. I hope
that our making the code public would induce several other groups to get into
this important field. Also, we expect that some people will try to understand
the code completely and not use it merely as a black box. Although several

16