C+
C NAME:
C	Time2CarringtonT0
C PURPOSE:
C	Calculate list of start times for subsequent 'Carrington rotations'
C CATEGORY:
C	Celestial mechanics
C CALLING SEQUENCE:
	subroutine Time2CarringtonT0(ScName,tt,dtt,ncar,jdcar)
C INPUTS:
C	ScName		double precision	external function; identifies spacecraft
C	tt(2)		integer			2-element standard time
C	dtt		integer			1-element time for required accuracy for start times
C	ncar		integer			# start times to be calculated
C OUTPUTS:
C	jdcar(2,ncar)	integer			Carrington start times as 2-element standard
C						times relative to current origin.
C INCLUDE:
	include		'fortime.h'
C CALLS:
C	ScName, Int2Str, Str2Str, Dbl2Str, Say
C PROCEDURE:
C >	ScName must be declared EXTERNAL in the calling program unit.
C	ScName is a user-written function which calculates the heliographic
C		longitude XLNG of a spacecraft for a given time iYr,Doy
C	The call to ScName has the form:
C		XLNG = ScName(itt)
C	where tt(2) is an integer 2-element standard time input and
C	XLNG (real*4) is output.
C >	itt(2) is the time where the search for start times begins.
C	the first nCar Carrington start times after iYr,Doy_IN are calculated
C >	The spacecraft is supposed to move in the ecliptic, circling the Sun in
C	the same direction as Earth (direct motion)
C >	The start time of a new Carrington rotation is defined as the time for
C	which the heliographic longitude of the spacecraft is zero.
C MODIFICATION HISTORY:
C	JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
C-
	    double precision	ScName
	    integer		tt(2)
	    integer		dtt
	    integer		ncar
	    integer		jdcar(2,ncar)

	character		cSay*17		/'Time2CarringtonT0'/

	integer			uu  (2)
	integer			uu0 (2)
	integer			uu1 (2)
	integer			drot(2)
	integer			delt(2)
	double precision	jd

	character		cStr*160
	integer			Str2Str
	integer			Dbl2Str
	integer			Time2Str

	if (TIME__ORIGIN(3) .lt. TIME__SECONDS_IN_DAY)
     &		call Say(cSay,'E','Time','resolution should be seconds or better')

	!-------
	! Sidereal solar rotation period at lat 16 deg (days)
	! (Does not have to be very accurate. Make sure to underestimate it.)

	PSolar = 25.339
	call Time2Day(1,drot,    PSolar)		! Convert to standard time
	call Time2Day(1,delt,0.1*PSolar)

	uu(1) = tt(1)
	uu(2) = tt(2)
	call Time2Delta(uu,drot,uu)

	!-------
	! Collect ncar start times for subsequent Carrington rotations

	n = 0

	do while (n .lt. ncar)

	    call Time2Add(uu,drot,uu1)
	    xlng1 = ScName(uu1)
	    xlng0 = xlng1+1.0		! Just to get into while loop

	    !-------
	    ! The spacecraft heliographic longitude is a decreasing function of time
	    ! within one Carrington rotation (the Sun catches up with the spacecraft).
	    !
	    ! Step forward in time from 'uu1' with step size 'del' until the heliographic
	    ! longitude jumps from (almost) 0 at time uu0 to (almost) 360 at time uu1.

	    do while (xlng1 .lt. xlng0)
		xlng0 = xlng1
		call Time2Add(uu1,delt,uu1)
		xlng1 = ScName(uu1)
	    end do
	    call Time2Delta(uu1,delt,uu0)

	    !-------
	    ! A new Carrington rotation starts between uu0 and uu1. Refine the
	    ! determination of the start time (until it is better than 'dtt') by repeated
	    ! bisection on the interval [uu0,uu1]

	    call Time2to1(delt,uu)		! Convert to 1-element time (in uu(1)

	    do while (uu(1) .gt. dtt)

		call Time2Interpolate(0.5d0,uu0,uu1,uu)
		xlng = ScName(uu)

		if (xlng .lt. xlng0) then
		    uu0(1) = uu(1)
		    uu0(2) = uu(2)
		    xlng0  = xlng
		else
		    uu1(1) = uu(1)
		    uu1(2) = uu(2)
		    xlng1  = xlng
		end if

	        call Time2Delta(uu1,uu0,uu)
	        call Time2to1(uu,uu)
	    
	    end do

	    !------
	    ! Take the center of the final interval [uu0,uu1] as the final estimate for
	    ! the start time of a new Carrington rotation.
	    ! The final start time is returned in jdcar(*,n).

	    n = n+1
	    call Time2Interpolate(0.5,uu0,uu1,uu)

	    jdcar(1,n) = uu(1)
	    jdcar(2,n) = uu(2)

	end do

	if (ncar .gt. 10) then

	    do n=1,ncar,ncar-1
		i = 0
		i = i+Time2Str('YYYY/MN/DD',jdcar(1,n),cStr(i+1:))
		i = i+Str2Str (' (jd' ,cStr(i+1:))+1
		call Time2JD  (0,jdcar(1,n),uu)
		call Time2Day8(0,uu,jd)
		i = i+Dbl2Str (jd,1,cStr(i+1:))
		i = i+Str2Str (')' ,cStr(i+1:))

		if (i .eq. 1) then
		    call Say(cSay,'I','start',cStr)
		else
		    call Say(cSay,'I','  end',cStr)
		end if
	    end do

	end if

	return
	end