Libration of SSP and additional spin-orbit resonances

[hersfeldtn]

Two additions for synchronous planets:

• Allow for libration of substellar point due to both obliquity and eccentricity, controlled by the allowlibrate parameter (True by default).
• Allow for specifying a number of solar days per orbit for synchronous planets (with the soldaysperorb parameter), allowing for spin-orbit resonances other than 1:1; Default is 0.0, which keeps the default tidal-locked behavior.

Neither interfere with the existing desynchronization system and they both use the year fraction, so shouldn't be affected by compounding timekeeping errors.

These changes were tested with 3.2.4 (as I can't seem to get 3.3.0 running) but I've tried to ensure they don't interfere with the new aerosol changes.

[alphaparrot]

A few questions:

1. This appears to add offsets to the hour angle in order to achieve the desired effect; how is this different from behaviour that can already be achieved in the model through either careful setting of rotation rate, orbital period, and eccentricity, or the desynchronization parameter? Additionally, this seems to allow only a fixed direction of substellar drift (similar to the desynchronization parameter); true libration should permit motion of the SSP both backwards and forwards.

2. These changes disconnect the declination and obliquity for fixed-SSP planets when allowlibrate == True (the default), but I don't see added code defining declination elsewhere. Is this intentional?

3. An upcoming version of ExoPlaSim (see the 'nbody' development branch) will allow both orbits and the orientation of the planet's rotational axis to be prescribed externally, such as e.g. through an N-body integrator and/or a tidal dissipation code. I think libration and precession would probably be possible to a higher degree of accuracy and complexity for a larger variety of systems than a linear offset to the hour angle with the nbody changes (libration arises in nature from the physics of orbital dynamics and tidal interactions). Is there a need or use case being met here that won't be met by just adding convenience functions to the upcoming orbital dynamics changes?

I'm happy to make changes if something's currently broken or there are use cases that won't be met by the upcoming features, but otherwise I would far prefer to further generalize the model and address those use cases organically than build in additional specific use cases. There is likely no end to the specific use cases that would need to be hard-coded; whereas if we just add support for this in the basic physics of the model, then most such use cases are supported natively.

[alphaparrot]

Also, if you're encountering issues getting 3.3.0 to work, please either email me or open an Issue (just enabled for the repository, along with a discussion board)--those changes are relatively new to the main branch, and have been tested extensively in the specific use cases relevant to the aerosol module's development, but not necessarily in other use cases. If there are bugs, we want to know about them!

[hersfeldtn]

1. In principle any type of synchronization could be achieved with specific rotation rates and orbital periods but you've previously indicated to me that compounding timekeeping errors in the model make this an unreliable option, and I was given to believe that was why the fixed longitude option was added in the first place. With fixed longitude, libration due to eccentricity is not represented, and desync can be used as an ad hoc implementation of other spin-orbit resonances, but (unless I've misunderstood) is subject to the same timekeeping issues. To clarify the implementation, longitude offset due to the soldaysperorb parameter is calculated first in a way that should ensure an exact number of rotations per orbit regardless of any timekeeping issues step-to-step, and it follows the sign of that parameter (or rather its inverse so that the substellar point moves west; negative soldaysperorb should cause retrograde apparent motion of the sun but I'm not sure if it's actually a good representation for retrograde rotation--though it should work for something like 1 prograde rotation ever 2 orbits). Longitude offset due to libration is then determined by the difference between the true anomaly and mean anomaly, which will be positive or negative at different points in the orbit, and added to the same lonoffset parameter. In my testing for soldaysperorb=0.0 this shows the substellar point moving west and east of the fixed longitude as expected.

2. This is something that confused me actually because it seemed that previously, with keplerian=True, for fixed longitude the declination was being set to a constant value equal to the obliquity. I'm not sure if this was intended, but disabling that line and allowing gen_orb_dec to run fully with fixed longitude appears to allow the declination to change through the year as expected, calculated by the same procedure as for unfixed planets. I left the old behavior in place with allowlibrate=false in the off chance someone wants to be able to fix the substellar point to an arbitrary latitude and longitude.

3. Depends on how the nbody update and its inputs are implemented, but this may be simpler for someone who wants to try a specific spin-orbit resonance or isolate the effect of different eccentricities or resonances without worrying about broader orbital context, precession, or more complex inputs involving other software? At any rate, adding proper libration for tidal-locked planets seemed like a good fix now that higher eccentricities are allowed and I figured I'd add in the soldaysperorb option while I was at it.

I can raise issues for the specific errors I'm getting with 3.3.0, but while I'm writing: my issue is a prompt crash with an error something like "[errno2]: cannot find file MOST.0000" (I can try again and get the exact log), and a couple others who have got it running have seen outputs with extremely uniform temperatures across all landmasses and zero soil albedo at high latitude.