TidalPy package

TidalPy.log_to_file()[source]: Quick switch to turn on saving logs to file

TidalPy.test_mode()[source]: Turn on test mode and reinitialize TidalPy

Subpackages

Submodules

TidalPy.cache module

TidalPy.cache.clear_cache(verbose: bool = True)[source]

Clears TidalPy’s cached functions (python cache and cached numba functions).

Parameters:: verbose (bool = True) – Prints the name of pycache directories as they are cleared.
Returns:: success
Return type:: bool

TidalPy.cache.clear_data(verbose: bool = True)[source]

Clears TidalPy’s data files.

Parameters:: verbose (bool = True) – Prints the name of directories as they are cleared.
Returns:: success
Return type:: bool

TidalPy.configurations module

Helper functions for loading TidalPy’s configurations.

It is recommended that you only change these once you have some experience with the package You can check their default values by examining the same file at https://github.com/jrenaud90/TidalPy/TidalPy/defaultc.py

TidalPy.configurations.check_config_version(config_path: str, allow_bugfix_difference: bool = True, warn_on_false: bool = True, raise_on_false: bool = False) → bool[source]

Checks a TidalPy configuration file to ensure that it is compatible with this version of TidalPy.

Parameters:

config_path (str) – Path to the configuration file to test.
allow_bugfix_difference (bool, default = True) – If true, then a config with version A.B.C will still be allowed for TidalPy version A.B.D
warn_on_false (bool, default = True) – If true, then a warning message will be shown if the config version check fails.
raise_on_false (bool, default = False) – If true, then an error message will be raised if the config version check fails.

Returns:

compatible – Flag for if this configuration file is compatible.

Return type:

bool

TidalPy.configurations.dict_replace_value(d_old: dict, d_new: dict) → dict[source]

TidalPy.configurations.get_default_config() → dict[source]: Loads TidalPy configurations that are found on the local disk. If no configuration file is found (likely when TidalPy is used for the first time) then default configurations will be saved to disk first.

TidalPy.configurations.get_default_world_dir() → str[source]: Find the directory containing TidalPy’s world configuration files. If no directory is found (likely when TidalPy is used for the first time) then default configurations will be saved to disk first.

TidalPy.configurations.save_dict_to_toml(dict_to_save: dict, file_path: str, overwrite: bool = True)[source]

Saves a python dictionary to a toml file at the specified file path.

Parameters:

dict_to_save (dict) – Python dictionary.
file_path (str) – Filepath to save to.
overwrite (bool, default = True) – If True, then the file will be overwritten if already present. by default True

TidalPy.configurations.set_config(new_config_path: str | dict) → dict[source]

Sets TidalPy’s configuration based on a provided configuration file path.

Parameters:: config_path (str) – Path to the configuration file the user wishes to use. if set to “default” then the default config will be used.

TidalPy.configurations.set_world_dir(world_dir_path: str)[source]

Sets TidalPy’s worlds config file directory based on a provided directory path.

Parameters:: world_dir_path (str) – Path to the worlds directory the user wishes to use. if set to “default” then the default directory will be used.

TidalPy.constants module

TidalPy.defaultc module

TidalPy.exceptions module

exception TidalPy.exceptions.ArgumentException(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'There was an error with one or more of a function or method arguments.'

exception TidalPy.exceptions.AttributeException(*args, **kwargs)[source]

Bases: TidalPyOOPException

default_message = 'There was a problem with one or more class attributes or methods.'

exception TidalPy.exceptions.AttributeNotSetError(*args, **kwargs)[source]

Bases: AttributeException

default_message = 'An attribute has not been changed from its default value.'

exception TidalPy.exceptions.BadArrayShape(*args, **kwargs)[source]

Bases: TidalPyValueException

default_message = 'TidalPy requires certain arrays maintain the same shape for all layers and planets. It has found an array with an unexpected shape.'

exception TidalPy.exceptions.BadAttributeValueError(*args, **kwargs)[source]

Bases: AttributeException

default_message = 'Bad value found in attribute setter.'

exception TidalPy.exceptions.BadValueError(*args, **kwargs)[source]

Bases: TidalPyValueException

default_message = 'An unrealistic value was encountered.'

exception TidalPy.exceptions.BadWorldSignature(*args, **kwargs)[source]

Bases: TidalPyOrbitError

default_message = 'A bad world signature was provided to an orbit class.'

exception TidalPy.exceptions.BadWorldSignatureType(*args, **kwargs)[source]

Bases: BadWorldSignature

default_message = 'An unexpected type was encountered for a world signature provided to an orbit class.'

exception TidalPy.exceptions.ConfigPropertyChangeError(*args, **kwargs)[source]

Bases: ImproperPropertyHandling

default_message = "Attempted to change a configuration class property. These must be changed in the world/layer's configuration (`<instance>.config`) followed by a call to its `reinit` method."

exception TidalPy.exceptions.ConfigurationException(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'An error was encountered when handling a configuration, parameter, or model.'

exception TidalPy.exceptions.FailedForcedStateUpdate(*args, **kwargs)[source]

Bases: TidalPyOOPException

default_message = 'The state of a class was forced to update but was unable to do so.'

exception TidalPy.exceptions.IOException(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'An issue arose when accessing system disk (either loading or saving data)'

exception TidalPy.exceptions.ImplementedBySubclassError(*args, **kwargs)[source]

Bases: TidalPyOOPException

default_message = 'Trying to access sub-class functionality from a base class.'

exception TidalPy.exceptions.ImproperGeometryPropertyHandling(*args, **kwargs)[source]

Bases: ConfigPropertyChangeError

default_message = 'The attribute you are attempting to set must be set by the set_geometry method or in the configurations.'

exception TidalPy.exceptions.ImproperPropertyHandling(*args, **kwargs)[source]

Bases: AttributeException

default_message = 'The attribute you are attempting to set must be set by a different class or method.'

exception TidalPy.exceptions.IncompatibleModelConfigError(*args, **kwargs)[source]

Bases: ConfigurationException

default_message = 'One or more model parameters are not compatible with each other'

exception TidalPy.exceptions.IncompatibleModelError(*args, **kwargs)[source]

Bases: ModelException

default_message = 'One or more model parameters are not compatible with each other'

exception TidalPy.exceptions.IncorrectArgumentType(*args, **kwargs)[source]

Bases: ArgumentException

default_message = 'A method or function argument was provided the incorrect type.'

exception TidalPy.exceptions.IncorrectAttributeType(*args, **kwargs)[source]

Bases: AttributeException

default_message = 'An attribute was set with incorrect type.'

exception TidalPy.exceptions.IncorrectMethodToSetStateProperty(*args, **kwargs)[source]

Bases: ImproperPropertyHandling

default_message = 'This particular state property is set by a different method than the one attempted. It may be set by a different object entirely.'

exception TidalPy.exceptions.InitializationError(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'An issue occurred during TidalPy initialization.'

exception TidalPy.exceptions.InitiatedPropertyChangeError(*args, **kwargs)[source]

Bases: ImproperPropertyHandling

default_message = "Attempted to change an initiated class property. These are set when an instance is created and can only be changed by that object's methods (or not at all). Try to make a new instance or use the object's methods instead of changing its initiated properties."

exception TidalPy.exceptions.InnerscopePropertySetError(*args, **kwargs)[source]

Bases: ImproperPropertyHandling

default_message = 'Attempted to set a property of an object that is inside the scope of the object where the setter was called from. Try to set this property to the object of interest.'

exception TidalPy.exceptions.IntegrationFailed(*args, **kwargs)[source]

Bases: TidalPyIntegrationException

default_message = 'Integration was not successful'

exception TidalPy.exceptions.IntegrationTimeOut(*args, **kwargs)[source]

Bases: TidalPyIntegrationException

default_message = 'Integration was stopped due to long integration time'

exception TidalPy.exceptions.MissingArgumentError(*args, **kwargs)[source]

Bases: ArgumentException

default_message = 'One or more required argument(s) and/or key-word argument(s) were not provided.'

exception TidalPy.exceptions.MissingAttributeError(*args, **kwargs)[source]

Bases: AttributeException

default_message = 'The attribute you are attempting to access has not been set.'

exception TidalPy.exceptions.ModelException(*args, **kwargs)[source]

Bases: ConfigurationException

default_message = 'An error was encountered when handling a model.'

exception TidalPy.exceptions.NotYetImplementedError(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'Tried to use functionality that is not yet implemented.'

exception TidalPy.exceptions.OuterscopePropertySetError(*args, **kwargs)[source]

Bases: ImproperPropertyHandling

default_message = 'Attempted to set a property of an object from a separate object that is inside the scope of the first. Try to set this property to the outer object.'

exception TidalPy.exceptions.ParameterException(*args, **kwargs)[source]

Bases: ConfigurationException

default_message = 'An error was encountered when handling a parameter.'

exception TidalPy.exceptions.ParameterMissingError(*args, **kwargs)[source]

Bases: ParameterException

default_message = 'One or more parameter(s) or configuration(s) are missing and have no defaults. Check that keys have correct spelling and capitalization.'

exception TidalPy.exceptions.ParameterTypeError(*args, **kwargs)[source]

Bases: ParameterException

default_message = 'One or more parameters were found to have an incorrect type.'

exception TidalPy.exceptions.ParameterValueError(*args, **kwargs)[source]

Bases: ParameterException

default_message = 'One or more parameter values are invalid or not supported.'

exception TidalPy.exceptions.ReinitError(*args, **kwargs)[source]

Bases: TidalPyOOPException

default_message = 'One or more critical parameters have changed since planet was made. Construct new planet instead.'

exception TidalPy.exceptions.ReinitNotAllowedError(*args, **kwargs)[source]

Bases: ReinitError

default_message = 'This class should be fully re-initialized upon load. Partial reinit (via self.reinit()) is not supported.'

exception TidalPy.exceptions.SolutionFailedError(*args, **kwargs)[source]

Bases: TidalPyIntegrationException

default_message = 'A solution was not able to be found.'

exception TidalPy.exceptions.TidalPyException(*args, **kwargs)[source]

Bases: Exception

Default exception for all TidalPy-specific errors

default_message = 'A Default TidalPy Error Occurred.'

exception TidalPy.exceptions.TidalPyIntegrationException(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'An issue arose during time integration.'

exception TidalPy.exceptions.TidalPyLayerError(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'There was a problem related to the functionality or building of a TidalPy layer.'

exception TidalPy.exceptions.TidalPyOOPException(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'There was an error with a TidalPy class or OOP process.'

exception TidalPy.exceptions.TidalPyOrbitError(*args, **kwargs)[source]

Bases: TidalPyOOPException

default_message = 'There was a problem related to the functionality or building of a TidalPy orbit.'

exception TidalPy.exceptions.TidalPyValueException(*args, **kwargs)[source]

Bases: TidalPyException

default_message = 'There is an issue with the value of a variable.'

exception TidalPy.exceptions.TidalPyWorldError(*args, **kwargs)[source]

Bases: TidalPyOOPException

default_message = 'There was a problem related to the functionality or building of a TidalPy world.'

exception TidalPy.exceptions.UnknownModelError(*args, **kwargs)[source]

Bases: ModelException

default_message = 'A selected model, parameter, or switch is not currently supported.'

exception TidalPy.exceptions.UnknownTidalPyConfigValue(*args, **kwargs)[source]

Bases: ConfigurationException

default_message = 'A configuration set in TidalPy.configurations is not know or has not yet been implemented.'

exception TidalPy.exceptions.UnknownWorld(*args, **kwargs)[source]

Bases: TidalPyWorldError

default_message = 'User provided world name does not match any prebuilt world configs. Check name or provide a manual configuration dictionary.'

exception TidalPy.exceptions.UnknownWorldType(*args, **kwargs)[source]

Bases: TidalPyWorldError

default_message = 'A world type was encountered that is either unknown, contains a typo, or is not yet implemented.'

exception TidalPy.exceptions.UnusualRealValueError(*args, **kwargs)[source]

Bases: TidalPyValueException

default_message = 'An usually large or small value was encountered for a parameter. Confirm proper dimensional units.'

TidalPy.initialize module

Functions used to initialize/reinitialize TidalPy

TidalPy.initialize.initialize(provided_config_file=None)[source]

Initialize (or reinitialize) TidalPy based on information stored in TidalPy.config

Items in TidalPy.config are identical to those in the TidalPy_Config.toml unless the user changed them and called: TidalPy.reinit()

See more information about TidalPy_Config.toml in TidalPy.configurations.py

TidalPy.initialize.is_notebook() → bool[source]

TidalPy.logger module

class TidalPy.logger.DeltaTimeFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)[source]

Bases: Formatter

format(record)[source]

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

TidalPy.logger.get_console_handler(error_stream=False)[source]

TidalPy.logger.get_file_handler() → FileHandler[source]: Get file handler for TidalPy’s logger.

TidalPy.logger.get_header_text() → str[source]

TidalPy.logger.get_logger(logger_name: str) → Logger[source]

TidalPy.logger.handle_exception(exc_type, exc_value, exc_traceback)[source]

TidalPy.logger.initialize_handlers()[source]

TidalPy.logger.is_notebook() → bool[source]

TidalPy.output module

TidalPy.output.create_output_dir() → str[source]

Creates an output directory for TidalPy data.

Returns:: Path to output directory.
Return type:: str

TidalPy.output.set_output_dir(new_output_dir: str) → str[source]

Sets new output directory for TidalPy data and logs.

Parameters:: new_output_dir (str) – New output directory. TidalPy will create a new directory if it does not exist.
Returns:: New output directory.
Return type:: str

TidalPy.paths module

TidalPy.paths.create_data_dirs()[source]: Creates TidalPy data directories if not already present.

TidalPy.paths.get_config_dir() → str[source]: TidalPy directory containing global configurations.

TidalPy.paths.get_log_dir() → str[source]: TidalPy directory containing log files.

TidalPy.paths.get_worlds_dir() → str[source]: TidalPy directory containing configurations for various pre-built worlds.

TidalPy.paths.timestamped_str(string_to_stamp: str = '', date: bool = True, time: bool = True, second: bool = False, millisecond: bool = False, preappend: bool = True, separation: str = '_', provided_datetime=None) → str[source]

Creates a timestamp string at the current time and date.

Parameters:

string_to_stamp (str = None) – Another string to add before or after timestamp
date (bool = True) – Whether or not the date will be included in the timestamp
time (bool = True) – Whether or not the time will be included in the timestamp
second (bool = False) – Whether or not the second will be included in the timestamp
millisecond (bool = False) – Whether or not the date will be included in the timestamp
preappend (bool = True) – Determines where the timestamp will be appended relative to the provided string
separation (str = '_') – Character that separates the timestamp and any provided string
provided_datetime (datetime.datetime = None) – A datetime.datetime object. If none provided the function will use call time

Returns:

timestamped_str – String with the current date and/or time added on.

Return type:

str

TidalPy.paths.unique_path(attempt_path: str, is_dir: bool = None, make_dir: bool = False) → str[source]

Creates a unique directory or filename with appended numbers if file/dir already exists.

Parameters:

attempt_path (str) – Desired Name. This could be a path itself.
is_dir (bool = None) – Is this a directory or file? If left as None the function will try to guess.
make_dir (bool = False) – If is_dir and make_dir are both True then an attempt to mkdir will be made.

Returns:

dir_file_path – The new, unique, path to the directory or file.

Return type:

str