The JKTEBOP code is a tool for fitting the light curves of detached eclipsing binary star and transiting planetary systems in order to derive the physical properties of the component objects. If you have any problems then please check this FAQ first. If you don't find an answer to your question then feel free to contact me at the email address on my main page.

Do you have a users manual?

I can't compile JKTEBOP

Which is the primary star and which is the secondary star?

JKTEBOP returns a rubbish solution

I get "singular matrix in gaussj" error messages

Warning about log or cubic limb darkening

What is a good value for the integration ring parameter?

My model light curve from TASK2 does not match that from TASK3

I get the error message "### ERROR: adjustment integer adj(R1+R2) is 1000 and should be -1, 0, 1 or 2"

I get the error message "### ERROR: number of simulations/sets to do must be between +/-8 and +/-99999."

I get the error message "Retry: failed to converge after 101 iterations"

I get the error message "### WARNING: the total limb darkening at the limb of star A is greater than 1.0"

I get the error message "sh: jktld: command not found" when running TASK1

I get an error message when trying to fit for r1 and r2 instead of (r1+r2) and k

My fit includes a polynomial but the best fit does not account for it

Sorry, but this is unlikely to happen. In the next "few years" I am intending to completely rewrite JKTEBOP in a newer programming language and much greater capability, including the possibility to deal with multiple light curves and radial velocity curves. JKTEBOP will be gracefully retired, and therefore a user manual will be of lesser importance than writing the new code.

An eclipsing binary star system normally shows two eclipses: a deeper one (primary eclipse) and a shallower one (secondary eclipse).

The eclipse depths depend on the *temperatures* of the two stars: at primary eclipse the hotter star is eclipsed by the cooler star. The primary eclipse is therefore at *inferior conjunction* and the secondary eclipse is at *superior conjunction*. (Note: some eccentric systems do not follow this because eccentricity changes the amount of the stellar surfaces which are eclipsed).

In JKTEBOP I adopt the convention that star A is the primary (hotter) star and star B is the secondary (cooler) star. Thus primary eclipse occurs at phase 0.0 when star A is behind star B. The ratio of the radii, the surface brightness ratio, the light ratio and the mass ratio are therefore:

k = radius(B) / radius(A)

J = flux(B) / flux(A)

lrat = light(B) / light(A)

q = mass(B) / mass(A)

These four ratios (k, J, lrat, q) are usually below 1.0.

There are quite a few eclipsing binary systems where the more massive star has evolved to have a lower temperature and a much larger radius than the less massive star. In this situation star A (the hotter star) is actually the smaller and less massive star. This is because J is less than 1.0, by definition. The result is that k, lrat and q are greater than 1.0. The more massive star may still produce more light than the less massive star (thus confusing spectroscopic analyses), but it is still star B because it is cooler than star A.

JKTEBOP has no problem in situations where any or all of the ratios (J, k, lrat, q) are greater than 1.0. If you put the secondary (shallower) eclipse at phase 0.0 then this causes no difficulty for JKTEBOP. The only thing you need to do is be careful to remember that star A is actually star B and vice versa.

JKTEBOP is written in almost-standard FORTRAN 77 so should be extremely portable. It compiles on my Linux/kubuntu laptop using the f77 and gfortran compilers. It also compiles on my Scientific Linux workstation using ifort (you may need to specify the "-heap-arrays 1 " flag on the command line at present) and also g77 (note that you will have to slightly change the call to the date_and_time subroutine for this as described in the source code). If you have problems then the first thing to do is check that your compiler can compile other FORTRAN77 programs successfully.

In some cases JKTEBOP does not converge and the output parameters are either completely mad, or simply the initial parameters with bad errorbars. This sometimes also causes error messages such as:

### PROBLEM A: singular matrix in gaussj (parameter: <n>)

or

### PROBLEM B: singular matrix in gaussj (parameter: <n>)

where <n> is an integer. <n> refers to the number of the parameter, which is the same as in the output file **but** only counting the adjusted ones. In almost all cases this error message is caused by problems with the input data and parameters, so should be quite easy to sort out. If you have one of these problems then check the following things:

- Are your initial parameters good enough? If one or several are totally wrong then JKTEBOP might have convergence problems. This particularly applies for the time of minimum light: if you give a time which is away from any eclipses then JKTEBOP will not normally be able to find an eclipse itself.
- Are you trying to fit for too many parameters or for parameters which are not constrained by the data? An example would be trying to fit for orbital period when you only have data covering one eclipse.
- Do the times in the datafile match the time in the input file? It is easy to knock the first "24" off the HJD values in your light curve, but forget to do the same with the reference time of minimum light. Another possibility is that you have mixed HJD and MJD, which are separated by 2400000.5 days.
- Are your input data in magnitude units? If they are in flux units then the eclipses go the wrong way (i.e. to lower rather than higher values) and JKTEBOP will fail.
- Do you have observational errors which are very wrong? If they are far too small or far too large (i.e. by a factor of a 100 or more) then this can cause convergence problems. The worst case is that one has ended up being "NaN" for some reason. A mistake I made once was to put orbital phase in the third column in the input data file, which JKTEBOP interpreted as observational errors and duly returned a weird solution. If you want to check if the observational errors are the problem then you can force JKTEBOP to ignore them by putting the error of the first datapoint to be "noerror" (or any other character string which FORTRAN cannot interpret as a number).

If none of the above helps, then fix all of your input parameters (i.e. put "0" for all the adustment integers). Run JKTEBOP again, then check whether the fixed "solution" is close to what you think it should be. Make any appropriate changes to the input parameters, and try again. Once you have got manually got close to the solution, you can try fitting for one parameter, then two, then three, etc.

### WARNING: the logarithmic and cubic limb darkening law flux normalisation are only approximate. Do not use the laws if you need a precise (<1%) light ratio.

This is a minor problem with flux normalisation for two of the limb darkening laws. EBOP was originally shipped with the linear law, and Alvaro Giménez & J. Díaz-Cordoves added treatment of quadratic and square-root limb darkening. These three laws are fully integrated. I have since added logarithmic and cubic limb darkening to JKTEBOP, but have not yet got round to deriving the proper flux normalisation (including gravity darkening and asphericity). The light contributions of the two stars are therefore only approximate, but the geometrical parameters (radii, inclination, e, ω, etc.) should be fine.

INTRING is a fixed control parameter which governs the numerical accuracy needed in the solution. The fux from each star is a sum of the contributions from many concentric rings, and INTRING gives the size of these rings in degrees. If your data are of normal ground-based quality then using "5" for INTRING should be fine. If you have very good data (e.g. from space satellites) or are working on transiting planets, then I recommend that you use "1" instead. The solution will take a bit longer, but will have very good numerical accuracy.

This is a "feature" rather than a "bug". In TASK3 it is possible to fit directly for the reflection coefficients, whereas in TASK2 the input values are ignored and predicted values are used instead. So it is possible for input files with identical parameters to return different light curves, which might surprise some users. There are two options available if this is causing you a problem. Firstly, instead of running TASK2 to get a model light curve you could run TASK3 but with all parameters fixed. Secondly, you can comment out three specific lines in the TASK2 subroutine and recompile the code. If you are unsure about which lines to comment out then please contact me.

This normally happens if you try to use an input file from TASK3 unchanged for TASK4, TASK5, TASK7 or TASK8. The other tasks require one more line in the input file, after the Reference time of primary minimum, which TASK3 does not require. Otherwise the different input files are of identical format. If you are unsure about what to do, generate empty input files for each task and compare them to see how they differ.

This normally happens if you try to use an input file from TASK3 unchanged for TASK4, TASK5, TASK7 or TASK8. The other tasks require one more line in the input file, after the Reference time of primary minimum, which TASK3 does not require. Otherwise the different input files are of identical format. If you are unsure about what to do, generate empty input files for each task and compare them to see how they differ.

A maximum of 100 of iterations are allowed in JKTEBOP for a fit to be regarded as successful. In TASK8, any fit which has more than this number of iterations is assumed to have failed. Failed fits trigger this warning message on the screen, but are not recorded in the .out file and are not included in the uncertainty estimates from the Monte Carlo simulations. They can therefore be ignored if they do not occur very often.

If you are getting a large number of these warning messages then this usually means that the data are not good enough to constrain all of the fitted parameters. Sometimes this is due to poor data quality (so may be unavoidable) but it can also be due to trying to fit for too many parameters. You can therefore try to fit for just the most important parameters and see if this makes the results better.

### WARNING: the total limb darkening at the limb of star A is greater than 1.0, ### so the limb darkening coefficient(s) for this star are physically impossible

This means that the limb darkening coefficients are physically impossible, because the limb of the star is predicted to be producing negative light. This normally happens if you are trying to fit for one or both limb darkening coefficients, and the best-fitting values are unreasonable. JKTEBOP does not force the limb darkening to be physically reasonable, as this causes problems for deriving errorbars. The implication is that your data are not good enough to fit for the limb darkening coefficients in the way you have attempted. The solution is to fix one (or both) of the limb darkening coefficients to reasonable values.

### WARNING: the total limb darkening at the limb of star A is less than 0.0, so ### the limb darkening coefficient(s) fo r this star are physically improbable.

This means that the limb darkening coefficients are physically unreasonable because they predict an overall limb brightening (the limb of the star is brighter than the centre). In rare cases this might be reasonable, such as Hα observations of active stars, but normally it indicates that the limb darkening coefficients are bad. As above, the implication is that your data are not good enough to fit for the limb darkening coefficients in the way you have attempted. The solution is to fix one (or both) of the limb darkening coefficients to reasonable values.

TASK1 originally produced a range of limb darkening coefficients via interpolation in tables of theoretical coefficients. I then split this out into a separate program called JKTLD. TASK1 now tries to use the JKTLD program by issuing a Fortran SYSTEM command to the shell. If JKTLD is not available then you will get the error message above. To solve this program you can download and install JKTLD from this page.

By default JKTEBOP fits for the sum and ratio of the fractional radii, (r1+r2) and k=r2/r1. The fractional radii are the true radii of the components divided by the orbital semimajor axis. This is because the parameters (r1+r2) and k tend to be less strongly correlated than r1 and r2 themselves, leading to a better-behaved solution. If you want to fit for r1 and r2 instead of (r1+r2) and k, then set the value of (r1+r2) in the input file to be equal to the negative of r1, i.e. you input -r1 and r2. The relevant line in the input file would therefore look something like this:

-0.153 0.126 Sum of the radii Ratio of the radii

where the desired input values are r1=0.153 and r2=0.126.

If you instead put the value of k to be negative, e.g.

0.153 -0.126 Sum of the radii Ratio of the radii

then JKTEBOP will only return an error:

### ERROR: the value of RADIIRATIO is -0.126 The allowed range is 0.00000 to 100.00000

Fix this by putting the value of (r1+r2) to be negative instead.

If you plot the best fit from the .fit file then this does not include the polynomial fitted to the data. This is a choice made during the implementation process, and arises because I did not want to JKTEBOP to have to output multiple best fits when multiple polynomials were used.

If you check the .out file then you will find that column 6 is marked (O-C). This gives the difference between each datapoint and the best-fit model value for the datapoint. If you plot columns 2 and 5 in the .out file you will be able to see what the fit looks like compared to the data.

This does create a small complication when plotting your results. If there is a gap in the data, then ideally we want to show how the fit varies through the gap even if there are no datapoints there. This is most obviously true if your data cover only half a transit but you want to see the shape of the whole transit. There are two ways of dealing with this:

- Plot the best fit from the .fit file but apply your polynomial to the best fit before plotting it.

- The way I do it is to remove the polynomial from the data before plotting it with the best fit. This is good particularly when you have several transits with different polynomials for each. I have an IDL code which automatically does this, so I do not need to worry about the polynomial coefficients. The code is available on request, but is not well commented.

* Last modified: 2016/08/31 John Southworth (Keele University, UK) *