diff --git a/Portable/Portable.ipynb b/Portable/Portable.ipynb new file mode 100644 index 0000000..ea7b6d8 --- /dev/null +++ b/Portable/Portable.ipynb @@ -0,0 +1,139 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Portable bare-name dialect\n", + "\n", + "Every MobilityDB operator is callable in PyMEOS under a single, stable\n", + "**portable bare name** (`overlaps`, `contains`, `teq`,\n", + "`nearestApproachDistance`, ...). The mapping is the cross-binding source\n", + "of truth ([RFC #920](https://github.com/MobilityDB/MobilityDB);\n", + "contract: `MobilityDB/MEOS-API` `meta/portable-aliases.json`), so the\n", + "*same* names work identically on every binding/engine (PyMEOS, JMEOS,\n", + "MEOS.NET, MobilityDuck, MobilitySpark, ...): a user learns one reference\n", + "and assumes the rest.\n", + "\n", + "The 29 bare names are **type-agnostic** — one name covers every temporal\n", + "type family (temporal, geo, cbuffer, npoint, pose, rgeo). Each bare name\n", + "dispatches, by the runtime type of its arguments, to the *exact* function\n", + "the operator is backed by, so it is identical to the operator by\n", + "construction (nothing is reimplemented).\n", + "\n", + "> Requires the portable dialect (`pymeos.portable`), added on the PyMEOS\n", + "> 1.4 line by PR #87. Until that release is published, install PyMEOS\n", + "> from the PR branch:\n", + "> `pip install \"git+https://github.com/MobilityDB/PyMEOS@feat/portable-aliases\"`" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pymeos import (\n", + " pymeos_initialize,\n", + " pymeos_finalize,\n", + " TsTzSpan,\n", + " TFloatSeq,\n", + " TGeomPointSeq,\n", + ")\n", + "from pymeos.portable import (\n", + " overlaps,\n", + " teq,\n", + " nearestApproachDistance,\n", + ")\n", + "\n", + "pymeos_initialize()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## One bare name, any type family\n", + "\n", + "The same callable works regardless of the argument types — it resolves\n", + "the matching backing function at call time." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Topology on time spans -> backed by overlaps_span_span\n", + "s1 = TsTzSpan(\"[2000-01-01, 2000-01-03]\")\n", + "s2 = TsTzSpan(\"[2000-01-02, 2000-01-05]\")\n", + "print(\"overlaps(span, span) :\", overlaps(s1, s2))\n", + "\n", + "# Temporal comparison on temporal floats -> backed by teq_temporal_temporal\n", + "a = TFloatSeq(\"[1@2000-01-01, 3@2000-01-03]\")\n", + "b = TFloatSeq(\"[2@2000-01-01, 2@2000-01-03]\")\n", + "print(\"teq(tfloat, tfloat) :\", teq(a, b))\n", + "\n", + "# Spatial distance on temporal points -> backed by the nad_* family\n", + "p1 = TGeomPointSeq(\"[Point(0 0)@2000-01-01, Point(2 2)@2000-01-03]\")\n", + "p2 = TGeomPointSeq(\"[Point(1 0)@2000-01-01, Point(3 0)@2000-01-03]\")\n", + "print(\"nearestApproachDistance(tgeompoint, tgeompoint) :\",\n", + " nearestApproachDistance(p1, p2))" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Identical to the operator by construction\n", + "\n", + "A bare name reuses the operator's own backing function — the same native\n", + "call the type-qualified API makes — so results match exactly." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Portable bare name vs. the type-qualified API: same backing call.\n", + "print(\"portable :\", overlaps(s1, s2))\n", + "print(\"type-qualified :\", s1.overlaps(s2)) # Span.overlaps\n", + "\n", + "print(\"portable :\", teq(a, b))\n", + "print(\"type-qualified :\", a.temporal_equal(b)) # Temporal.temporal_equal" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "pymeos_finalize()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The full set of 29 portable bare names is `pymeos.portable.__all__`." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "version": "3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/Portable/requirements.txt b/Portable/requirements.txt new file mode 100644 index 0000000..96d849e --- /dev/null +++ b/Portable/requirements.txt @@ -0,0 +1,5 @@ +# Requires the portable bare-name dialect (`pymeos.portable`), added on the +# PyMEOS 1.4 line by PR #87. Until that release is published, install +# PyMEOS from the PR branch: +# pip install "git+https://github.com/MobilityDB/PyMEOS@feat/portable-aliases" +pymeos>=1.4.0a1 diff --git a/README.md b/README.md index 7fc04b6..a11705c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # PyMEOS Examples -The examples provided are divided in two folders: +The examples provided are divided in three folders: - [PyMEOS Examples](./PyMEOS_Examples) Replicas of [Tutorial Programs of MEOS](https://www.libmeos.org/tutorialprograms/) using PyMEOS. - [AIS](./PyMEOS_Examples/AIS.ipynb): Contains the PyMEOS examples using AIS data @@ -16,3 +16,8 @@ The examples provided are divided in two folders: - [Temporal Aggregation of Trips](https://libmeos.org/tutorialprograms/meos_aggregate_berlinmod/) - [MovingPandas](./MovingPandas): Replicas of [MovingPandas examples](https://github.com/anitagraser/movingpandas-examples) using PyMEOS. (WIP) +- [Portable](./Portable): + The portable bare-name dialect — every MobilityDB operator under one + stable, cross-binding name, type-agnostic across all temporal families. + - [Portable](./Portable/Portable.ipynb): Calling operators by their + canonical portable bare name in PyMEOS (`pymeos.portable`).