Home › installation

Installation

One wheel, two required dependencies, no build step. If pip finishes without warnings you are done; the rest of this page is for people in conda environments, on old interpreters, or with ten-year records.

With pip

python -m pip install tidalcore

This pulls a pure-Python wheel. There is nothing to compile, no system libraries to find and no platform-specific build, so the same artefact is used on Linux, macOS and Windows.

Extras

The base install deliberately stays small. Everything that is convenient rather than necessary sits behind an extra.

Install several at once in the usual way, for example `pip install "tidalcore[frames,plots]"`.
Extra	Pulls in	What it unlocks
frames	pandas >= 2.0	`Record.to_frame()` and `Solution.to_frame()`; readers accept a frame directly
plots	matplotlib >= 3.7	the three plot helpers used on the tutorial page
netcdf	netCDF4 >= 1.6	the `netcdf-cf` reader described under formats
dev	pytest, hypothesis, ruff	test suite and linters; not needed to use the library

Inside a conda environment

There is no conda channel package yet. A recipe exists and has not been submitted, and we would rather say so than let you search for a package that is not there.

Until it lands, install into the environment with pip, which is well-behaved here because the wheel has no compiled parts to conflict with conda-provided libraries:

conda create -n tides python=3.12 numpy scipy
conda activate tides
python -m pip install --no-deps tidalcore

The --no-deps flag keeps pip from replacing the NumPy and SciPy that conda just installed. Check the floors in the table below if you do that, because pip will no longer check them for you.

Requirements

Floors are tested in continuous integration; newer versions are expected to work and the oldest listed is the one the suite actually runs against.
Requirement	Minimum	Why that floor
Python	3.10	pattern matching in the reader dispatch; 3.9 was dropped in 0.9.0
NumPy	1.24	`np.datetime64` behaviour relied on by the time handling
SciPy	1.10	the least-squares solver and the filter used before decimation
pandas	2.0	optional, extra `frames`; needed only for frame conversion
matplotlib	3.7	optional, extra `plots`

From a source archive

Each release ships a source archive next to the wheel. Unpack it and install the directory; the build backend is standard and needs no extra tooling.

python -m pip install ".[dev]"
python -m pytest -q
# 212 passed in 6.1s

The suite includes a 48-hour synthetic record with known constituent amplitudes, so a failing test usually means a numerical regression rather than a flaky fixture. If the synthetic test fails and nothing else does, check your SciPy build first.

Verifying the install

python -c "import tidalcore as tc; print(tc.__version__)"
# 0.9.3
tidalcore --version
# tidalcore 0.9.3

Both should print the same string. If the module imports but the command is missing, the entry point was not installed, which normally means the package was unpacked by hand instead of installed.

Memory on long records

The fit builds a design matrix with one row per sample and two columns per constituent. A ten-year record at six-minute sampling is 876 000 samples, and against the full 68-constituent catalogue that matrix would be 0.96 GB in double precision.

Since 0.9.2 the normal equations are accumulated in blocks of 50 000 samples instead, which brought the peak for that record down to 88 MB and made the fit 3.4 times faster. You do not have to configure this; it is the only code path. The practical limit is now the record itself rather than the constituent count.

Three errors people hit first

ShortRecordError: The record is too short to resolve the constituents you asked for. Either shorten the list or let constituents="auto" choose a set that the record length supports.
CoverageError: After excluding bad and missing samples, less than 75 % of the span is usable. Lower the bar with --min-coverage if you know what you are doing, and say so in whatever you publish.
UnknownConstituentError: A name is not in the bundled catalogue. Names are case-sensitive and follow the table on the constituents page; MU2 and NU2 are spelled out rather than written with Greek letters.