TidalPy v0.6.1

Changes

Benchmarks and Performance

• Added performance benchmark for TidalPy.RadialSolver.helpers.

Fixes

• Fixed memory leak that was occurring in the EOS Solver (therefore also RadialSolver) due to CyRK's CySolverSolution not being dereferenced (this is a problem with CyRK, but hack applied to TidalPy until a fix can be made to CyRK).

Performance

• Improved TidalPy.RadialSolver.helpers.build_rs_input_from_data performance by factor of 10x to 150x depending on layer structure.
• Improved TidalPy.RadialSolver.helpers.build_rs_input_homogeneous_layers performance by factor of 15% to 3.5x depending on layer structure.
• Improved TidalPy.RadialSolver.radial_solver performance by around 10% depending on layer structure.

GitHub Tracked Changes

• 0.6.1 - Improved RS Helper Performance by @jrenaud90 in #70

Full Changelog: v0.6.0...v0.6.1

TidalPy v0.6.0

Changes

Removed

• Removed support for the older non-cythonized TidalPy.radial_solver module in favor of TidalPy.RadialSolver

RadialSolver Changes

• Moved RadialSolver's Boundary Condition finder to its own function in TidalPy.RadialSolver.boundaries.surface_bc.pyx to allow it to be used by both the shooting and propagation matrix techniques.
• Decoupled radial solver from shooting method.
  • Moved the shooting method (formerly just called cf_radial_solver) to a dedicated file to prep for a different dedicated file for the prop matrix solver.
  • Now TidalPy.RadialSolver.solver only contains driver functions and output structures.
• Added Propagation Matrix technique to RadialSolver
  • This is simplified for now. Only planets with 1 solid, static, incompressible layer are allowed.
    • Other assumptions can be approximated, e.g., liquid layers use a small shear modulus.
    • Multiple layers should also work if you have discontinuities in density, shear, etc. within your "one layer".
  • A cythonized solid fundamental matrix implementation can be found in TidalPy.RadialSolver.PropMatrix.solid_matrix.
• New radial slicing scheme required:
  • TidalPy now requires radial_solver input arrays to be defined in a precise manner:
    • radius_array must start at 0.
    • Each layer's upper and lower radius must be in the radius_array. That means if there is more than one layer there will be two identical radius values!
      • E.g., if a planet has a ICB at 1000km and a CMB at 3500km. Then radius_array must be setup with 2 values of 1000km and 2 values of 3500km.
      • Other parameters should be defined on a "as layer" basis. So shear modulus at the 1st 1000km would be the shear of the inner core, at the 2nd 1000km it would be the shear modulus of the outer core. Likewise shear modulus at the 1st 3500km would be for the outer core and at the 2nd 3500km would be the shear modulus for the mantle. Same goes for density and bulk modulus.
• Added warning to check for instabilities (based on large number of steps taken; requires warnings=True).
• Changes to radial_solver arguments:
  • Many changes to the order as well as additions and removals of arguments to radial_solver highly suggest looking through the updated documentation.
  • radial_solver no longer requires gravity_array.
    • New with this update is a self-consistent equation of state solver (EOSS) that is called from radial_solver. This EOSS is used to find gravity(r).
  • Bulk modulus must now be provided as a complex-valued array
    • If a non-zero imaginary portion is provided (e.g., found via a rheology) then bulk dissipation is now tracked.
    • If imaginary portions are zero, then bulk dissipation is ignored as in TidalPy v0.5.x and earlier. (this is actually dependent on your bulk rheology; it could also cause infinities...)
  • Several arguments have had slight name refactors which will break calls that used keyword arguments. Review the RadialSolver documentation or "TidalPy/RadialSolver/solver.pyx" for the new argument names.
  • upper_radius_bylayer_array must now be provided as a numpy array (previously a tuple of floats was acceptable).
  • Added new optional argument surface_pressure (default=0.0) used with EOSS to find pressure convergence.
  • Added new optional argument core_model (default=0) used to set the lower boundary condition when the propagation matrix technique is used.
  • Added new optional argument starting_radius (default=0.0) to allow the user to set the initial radius for the radial solution.
    • Setting the solution radius higher in the planet can improve solution stability when using the shooting method. Particularly if looking at higher harmonic degree_ls. There is a trade off with accuracy so advise testing.
    • The starting radius must be >= 0.0, if 0.0 is provided (the default) then TidalPy will use the Martens technique to find a suitable starting radius (function of degree_l, planet radius, and the new optional argument start_radius_tolerance which defaults to 1.0e-5).
  • Removed limit_solution_to_radius argument.
  • Added new optional argument use_prop_matrix (default=False) to use the propagation matrix technique over the shooting method.
  • Equation of State Solver arguments:
    • eos_method_bylayer - EOSS method to use for each layer (currently only "interpolate" is supported).
    • eos_integration_method Runge-Kutta method to use for EOSS (default="RK45"). eos_rtol and eos_atol can also be provided to control integration error.
    • eos_pressure_tol (default=1.0e-3) and eos_max_iters (default=40) control the pressure convergence of the EOSS.
  • Added optional argument perform_checks (default=True) that performs many checks on the user input before running the solution (small performance penalty, but highly recommend leaving on until your inputs are tested).
  • Added optional argument log_info (default=False) that will log key physical and diagnostic information to TidalPy's log (which can be set to be consol print, log file, or both via TidalPy's configurations).
    • Note there is a performance hit when using this, particularly if logging to file is enabled.

New RadialSolver Helpers

• To assist with the generation of valid inputs to radial_solver, TidalPy now provides two helper functions:
  • For planets with homogeneous layers: from TidalPy.RadialSolver import build_rs_input_homogeneous_layers takes in attributes for a planet made of layers with constant physical properties and then provides the arrays and other required radial_solver inputs that conform to the new radius_array scheme.
  • For planets with inhomogeneous layers: from TidalPy.RadialSolver import build_rs_input_from_data which parses data arrays (loaded from a file or built elsewhere like using a more robust EOS than TidalPy offers) and makes changes to ensure they will work with radial_solver.

Expanded RadialSolverSolution Attributes and Methods

• The output of radial_solver, an instance of the RadialSolverSolution, has been greatly expanded to provide much more data and functionality to the user. Full details can be found in the new RadialSolver documentation. Highlights include:
  • EOSS results like <solution>.mass, <solution>.moi, <solution>.moi_factor, <solution>.central_pressure, <solution>.surface_gravity.
  • Diagnostic data like number of integration steps required per layer to find a solutions <solution>.steps_taken, or EOSS diagnostics: <solution>.eos_iterations, <solution>.eos_pressure_error, <solution>.eos_success, <solution>.eos_message, <solution>.eos_steps_taken.
    • Much of the new diagnostic data as well as key results can now be quickly printed using <solution>.print_diagnostics().
  • Method to quickly plot the viscoelastic-gravitational solution y's <solution>.plot_ys().
  • Method to quickly plot the EOS results <solution>.plot_interior().
  • In addition to the previously provided attributes like <solution>.love, <solution>.k, <solution>.h, <solution>.l, <solution>.result.

Cython / C Changes

• Shifted away from PyMem_Free to CyRK.utils.mem_free to allow for consistency in future development.
  • Avoiding using these manual heap allocations whenever possible. Many new uses of smart pointers and C++ vectors.

Other Changes

• Updated GitHub actions.
• Moved to more consistent and robust types (e.g., int for degree_l vs. prior unsigned-char; unsigned-int).
• Added inverse function cinv in TidalPy.utilities.math.complex.
• New "TidalPy/constants.pyx" isolates all TidalPy constants. Available to both Python and Cython. Refactored all files to use the constants in this file.
• New numerics module TidalPy.math.numerics for low-level floating point functions.
  • New cythonized isclose function that matches functionality of python's math.isclose
• Cythonized radial sensitivity to shear/bulk functions in TidalPy.tides.multilayer.sensitivity (based on Tobie+2005)
• Cythonized radial heating functions that use the sensitivity to shear/bulk functions in TidalPy.tides.multilayer.heating (based on Tobie+2005)
• Improved logging so it is less spammy.
• Logger now logs all exceptions raised.
• Moved TidalPy's default config and world config dir to user's "Documents" folder (from system appdata folder).
  • If upgrading from previous version of TidalPy, you can safely delete the old config directory.
    • On Windows the old dir was: "'C:\Users\\AppData\Local\TidalPy'"; The new dir is "'C:\Users\\Documents\TidalPy'"
    • On Mac the old dir was: "'/Users//Library/Application Support/TidalPy'"; The new dir is "'/Users//Documents/TidalPy'"
    • On Linux the old dir was: "'/Users//.local/share/TidalPy'"; The new dir is "'/home//Documents/TidalPy'"
• New switch TidalPy.log_to_file() to quickly turn on saving log to file (this can also be adjusted in the TidalPy configurations).
• TidalPy now looks for an environment variable "TIDALPY_TEST_MODE" to turn on test mode during first initialization (can later be changed using the TidalPy.test_mode() command or setting TidalPy._test_mode = False; TidalPy.reinit()).
• Made use of more TidalPy-specific exceptions.
• Tweaked the TidalPy.utilities.graphics -> yplot.
• User can now override TidalPy.config using TidalPy.reinit(<new config toml file path; or dictionary of configs>).
• Refactored and made improvements to TidalPy.utilities.graphics.planet_plot.

Dependencies

• Added support for CyRK v0.12.x
• Added support for Burnman v0.2.x

Documentation

• Reworked TidalPy's documentation structure in prep for a shift to Sphinx in the future.
• Greatly expanded and improved RadialSolver documentation which can be found in "TidalPy...

TidalPy v0.5.5

Changes

Fixes:

• Fixed dependency compatibility issues.
• Fixed incorrect function signature type for scipy's spherical_jn. SciPy v.1.14.X uses a new signature which is breaking on MacOS. Limiting to "SciPy<1.14" for now.

GitHub Tracked Changes:

Full Changelog: v0.5.4...v0.5.5

v0.5.4

Changes

Fixes:

• Fixed RadialSolver frequency warning message for dynamic liquid layers not displaying for correct layer types.

Additions:

• Added way to suppress warning messages in RadialSolver.
  • To turn this suppression on, pass warnings=False to RadialSolver.radial_solver.

GitHub Tracked Changes

• FIX: Bug in warning system for RadialSovler by @jrenaud90 in #58

Full Changelog: v0.5.3...v0.5.4

TidalPy v0.5.3

Changes

Fixes:

• RadialSolver: Fixed bug where solutions between liquid and solid layers were not propagating correctly.

Additions:

• New Love number benchmarks for Earth provided by Nick Wagner in Benchmarks & Performance\RadialSolver\Earth Love Numbers.ipynb (Jupyter Notebook).

Changes:

• Pre-allocated several cythonized arrays to nans to help with debugging.
• Provided more error messages to improve user experience.
• Cythonized non-dim function now takes in the planet's density and radius as variables to change.
• Improved the Tobie and Roberts benchmarks for radial solver.

Other:

• Updated to work with CyRK 0.8.7

GitHub Tracked Changes

• Updated NaN troublshooting in RadialSolver.md by @nlwagner in #52
• Radialsolver-benchmarking by @jrenaud90 in #56
• Add files via upload by @nlwagner in #54
• Ver0.5.3 by @jrenaud90 in #57

Full Changelog: v0.5.2...v0.5.3

TidalPy v0.5.2

Changes

Documentation

• Improved RadialSolver documentation regarding higher degree-l.
• Added info about issues that can arise from using non C-continguous arrays in cythonized functions.

Fixes:

• Added error message to RadialSolver.radial_solver if length of provided assumption tuples is not the same.
• Fixed issue where non C-continguous arrays were allowed in cythonized functions that required them.

GitHub Tracked Changes

• Update Using RadialSolver.md by @nlwagner in #49
• Ver 0.5.2 by @jrenaud90 in #51

New Contributors

• @nlwagner made their first contribution in #49

Full Changelog: v0.5.1...v0.5.2

TidalPy v0.5.1

Changes

Removed Python 3.8 support due to issues with building SciPy.

GitHub Tracked Changes

• DEPS: Removed py 3.8 support by @jrenaud90 in #47

Full Changelog: v0.5.0...v0.5.1

v0.5.0

Changes

This version is likely to break code based on TidalPy v0.4.X and earlier

Cythonizing TidalPy

• A major change starting with v0.5.0 is the switch from numba.njited functions to cython precompiled functions and
  extension classes. The reasons for doing this are numerous. This transition will be completed in stages
  with minor versions (v0.X.0) each bringing a new set of cythonized updates until all njited functions are retired.
• For this version:
  • Converted TidalPy.radial_solver.radial_solver to cythonized TidalPy.RadialSolver.radial_solver.
    • The old radial solver method will be removed in TidalPy version 0.6.0.
  • Added new cython-based TidalPy.utilities.classes.base_x base cython extension class that other classes are built off of.
  • Converted TidalPy.rheology.complex_compliances.compliance_models to cythonized TidalPy.rheology.models.
    • Improved the new rheology methods to better handle extreme values of frequency and modulus.
    • The old rheology solvers will be removed in a future release of python.
  • Added several new cython-based helper functions in the utilities package.

Other Major Changes

• Added support for Python 3.11 and 3.12. TidalPy now runs on Python 3.8--3.12.
  • Note that currently the Burnman package does not support 3.12 so that functionality is limited to python 3.8-3.11.
• Removed support for solver_numba in the radial_solver module.
• Removed some imports from main package and sub modules' __init__ to avoid slow load times.
• Moved conversion tools from TidalPy.toolbox.conversions to TidalPy.utilities.conversions.
• Changed setup files so that cython code can be compiled.
  • special - for high-performance, general, scientific functions.
• Moved TidalPy configs to a standard user directory by default. The specific location will depend on the OS.
  • Default configs will be installed on the first import TidalPy call after installation.
    • These defaults are stored in the TidalPy.defaultc.py as a string which is copy and pasted to the new TidalPy_Configs.toml.
  • There is a new TidalPy.clear_data() function to delete all data stored in these locations. Data will be rebuilt the next time TidalPy is imported.
  • New TidalPy.set_config(config_path) to change the active configuration file used by TidalPy.
    • Note that TidalPy.reinit() should be called after changing the configurations.
  • New TidalPy.set_world_dir(world_dir_path) to change which directory to pull world configs from.
  • Moved away from the system of default.py configurations for sub modules. All default configs are stored in the same TidalPy_Config.toml
• Shifted from json to toml files for world configs.
  • Store all world configs to a zip file for easier distribution.
• TidalPy now requires:
  • CyRK>=0.8.6
  • Cython>=3.0.0
• Moved BurnMan 3rd party dependence to a more dedicated Extending folder for future development.
• To make TidalPy lighter weight we are starting to remove a lot of 3rd party packages.

Minor Changes and New Features

• complex_compliance configurations are now stored in the top level rheology in all configs.
  • For example, in prior TidalPy versions you would need to change the complex compliance model by editing config['layers']['mantle']['rheology']['complex_compliance']['model'] = 'andrade'. Now this would be: config['layers']['mantle']['rheology']['model'] = 'andrade'.
• Added unique frequency finder functions to the modes module.
• Moved most of the type hints behind the typing.TYPE_CHECKING flag.
• Moved non-critical files out of repository.
• Created a new tides.heating module and moved the volumetric heating calculations there.
• Expanded the performance suite to better track the radial_solver module.
• Moved cache.py to top-level.
• Turned off numba cacheing on several functions that may be used in the radial solver.
  • rheology
    • complex compliance functions
  • radial_solver.numerical
    • initial guess functions
    • interface functions
• Converted radial_solver.numerical initial guess and interface functions output to np.ndarrays rather than numba lists.
• Removed config_helper.py and the functions defined within.
• New RadialSolver class now supports more than just boolean inputs.
  • Future proofing to allow for a greater variety of layer types.
• Added exoplanet archive download functionality in TidalPy.utilities.exoplanets.

Bug Fixes

• Fixed floating point comparison bug in multilayer_modes solver.
• Fixed obliquity not being used issue in quick tides calculator.
• Fixed issue in incorrect TidalPy version being loaded into the package.

Performance Improvements

• Improved the performance of the stress and strain calculator by ~20%.
• Cythonize Performance Increases:
  • New RadialSolver.radial_solver leads to a ~50x performance boost.
  • New cythonized rheology models are 500% faster for arrays; 40,000% faster for scalars (not a typo!)

GitHub Tracked Changes

• Fixing slow package load by @jrenaud90 in #38
• Cythonizing_radial_solver by @jrenaud90 in #39
• Changing-planet-configs by @jrenaud90 in #40
• TidalPy version 0.5.0 by @jrenaud90 in #46

Full Changelog: v0.4.1...v0.5.0

TidalPy v0.4.1

Changes

• Version 0.4.0 of TidalPy has brought a large number of changes to various models. Many of which will break old code. Please review the full change log for details: https://github.com/jrenaud90/TidalPy/blob/main/CHANGES.md

GitHub Auto Generated Change Log

• TidalPy v0.4.0 by @jrenaud90 in #36
• Moved radial_solver to a top level module. by @jrenaud90 in #37

Full Changelog: v0.3.5.beta...v0.4.1

TidalPy v0.3.5-beta

What's Changed

Fixes issues introduced in 0.3.4

• v0.3.5 by @jrenaud90 in #34

Full Changelog: v0.3.4-beta...v0.3.5.beta