# Introduction

MobilityDB is an extension of PostgreSQL and PostGIS that provides temporal types. Such data types represent the evolution on time of values of some element type, called the base type of the temporal type. For instance, temporal integers may be used to represent the evolution on time of the the gear used by a moving car. In this case, the data type is temporal integer and the base type is integer. Similarly, a temporal float may be used to represent the evolution on time of the speed of a car. As another example, a temporal point may be used to represent the evolution on time of the location of a car, as reported by GPS devices. Temporal types are useful because representing values that evolve in time is essential in many applications, for example in mobility applications. Furthermore, the operators on the base types (such as arithmetic operators and aggregation for integers and floats, topological and distance relationships for geometries) can be intuitively generalized when the values evolve in time.

MobilityDB provides the temporal types `tbool`, `tint`, `tfloat`, `ttext`, `tgeometry`, `tgeography`, `tgeompoint`, and `tgeogpoint`. These temporal types are based, respectively, on the `bool`, `integer`, `float`, and `text` base types provided by PostgreSQL, and on the `geometry` and `geography` base types provided by PostGIS, where `tgeometry` and `tgeography` accept arbitrary geometries/geographies, while `tgeompoint` and `tgeogpoint` only accept 2D or 3D points.

Although 4D temporal points can be represented, the M dimension is currently not taken into account.

Furthermore, MobilityDB provides set, span, and span set template types for representing, respectively, sets of values, ranges of values, and sets of ranges of values of base types or time types. Examples of values of set types are `intset`, `floatset`, and `tstzset`, where the latter represents set of `timestamptz` values. Examples of values of span types are `intspan`, `floatspan`, and `tstzspan`. Examples of values of span set types are `intspanset`, `floatspanset`, and `tstzspanset`.

## Project Steering Committee

The MobilityDB Project Steering Committee (PSC) coordinates the general direction, release cycles, documentation, and outreach efforts for the MobilityDB project. In addition, the PSC provides general user support, accepts and approves patches from the general MobilityDB community and votes on miscellaneous issues involving MobilityDB such as developer commit access, new PSC members or significant API changes.

The current members in alphabetical order and their main responsibilities are given next:

- Mohamed Bakli: MobilityDB-docker, cloud and distributed versions, integration with Citus

- Krishna Chaitanya Bommakanti: MEOS (Mobility Engine Open Source), pyMEOS

- Anita Graser: integration with Moving Pandas and the Python ecosystem, integration with QGIS

- Darafei Praliaskouski: integration with PostGIS

- Mahmoud Sakr: co-founder of the MobilityDB project, MobilityDB workshop, co-chair of the OGC Moving Feature Standard Working Group (MF-SWG)

- Vicky Vergara: integration with pgRouting, liason with OSGeo

- Esteban Zimányi (chair): co-founder of the MobilityDB project, overall project coordination, main contributor of the backend code, BerlinMOD generator

## Other Code Contributors

- Arthur Lesuisse

- Xinyiang Li

- Maxime Schoemans

## Sponsors

These are research funding organizations (in alphabetical order) that have contributed with monetary funding to the MobilityDB project.

- European Commission

- Fonds de la Recherche Scientifique (FNRS), Belgium

- Innoviris, Belgium

These are corporate entities (in alphabetical order) that have contributed developer time or monetary funding to the MobilityDB project.

- Adonmo, India

- Georepublic, Germany

- Université libre de Bruxelles, Belgium

## Licenses

The following licenses can be found in MobilityDB:

Resource | Licence
MobilityDB code | PostgreSQL Licence
MobilityDB documentation | Creative Commons Attribution-Share Alike 3.0 License

## Installation from Sources

### Short Version

To compile assuming you have all the dependencies in your search path

    git clone https://github.com/MobilityDB/MobilityDB
    mkdir MobilityDB/build
    cd MobilityDB/build
    cmake  ..
    make
    sudo make install

The above commands install the `master` branch. If you want to install another branch, for example, `develop`, you can replace the first command above as follows

    git clone --branch develop https://github.com/MobilityDB/MobilityDB

You should also set the following in the `postgresql.conf` file depending on the version of PostGIS you have installed (below we use PostGIS 3):

    shared_preload_libraries = 'postgis-3'
    max_locks_per_transaction = 128

If you do not preload the PostGIS library with the above configuration you will not be able to load the MobilityDB library and will get an error message such as the following one:

    ERROR:  could not load library "/usr/local/pgsql/lib/libMobilityDB-1.1.so":
      undefined symbol: ST_Distance

You can find the location of the `postgresql.conf` file as given next.

    $ which postgres
    /usr/local/pgsql/bin/postgres
    $ ls /usr/local/pgsql/data/postgresql.conf
    /usr/local/pgsql/data/postgresql.conf

As can be seen, the PostgreSQL binaries are in the `bin` subdirectory while the `postgresql.conf` file is in the `data` subdirectory.

Once MobilityDB is installed, it needs to be enabled in each database you want to use it in. In the example below we use a database named `mobility`.

    createdb mobility
    psql mobility -c "CREATE EXTENSION PostGIS"
    psql mobility -c "CREATE EXTENSION MobilityDB"

The two extensions PostGIS and MobilityDB can also be created using a single command.

    psql mobility -c "CREATE EXTENSION MobilityDB cascade"

### Get the Sources

The MobilityDB latest release can be found in

wget

To download this release:

    wget -O mobilitydb-1.3.tar.gz https://github.com/MobilityDB/MobilityDB/archive/v1.3.tar.gz

Go to short_version to the extract and compile instructions.

git

To download the repository

    git clone https://github.com/MobilityDB/MobilityDB.git
    cd MobilityDB
    git checkout v1.3

Go to short_version to the compile instructions (there is no tar ball).

### Enabling the Database

MobilityDB is an extension that depends on PostGIS. Enabling PostGIS before enabling MobilityDB in the database can be done as follows

    CREATE EXTENSION postgis;
    CREATE EXTENSION mobilitydb;

Alternatively, this can be done in a single command by using `CASCADE`, which installs the required PostGIS extension before installing the MobilityDB extension

    CREATE EXTENSION mobilitydb CASCADE;

### Dependencies

Compilation Dependencies

To be able to compile MobilityDB, make sure that the following dependencies are met:

- `CMake` cross-platform build system.

- C compiler `gcc` or `clang`. Other ANSI C compilers can be used but may cause problems compiling some dependencies.

- GNU Make (`gmake` or `make`) version 3.1 or higher. For many systems, GNU make is the default version of make. Check the version by invoking `make -v`.

- PostgreSQL version 12 or higher. PostgreSQL is available from http://www.postgresql.org.

- PostGIS version 3 or higher. PostGIS is available from https://postgis.net/.

- GNU Scientific Library (GSL). GSL is available from https://www.gnu.org/software/gsl/. GSL is used for the random number generators.

Notice that PostGIS has its own dependencies such as Proj, GEOS, LibXML2, or JSON-C, and these libraries are also used in MobilityDB. Refer to http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS for a support matrix of PostGIS with PostgreSQL, GEOS, and Proj.

Optional Dependencies

For the user's documentation

- The DocBook DTD and XSL files are required for building the documentation. For Ubuntu, they are provided by the packages `docbook` and `docbook-xsl`.

- The XML validator `xmllint` is required for validating the XML files of the documentation. For Ubuntu, it is provided by the package `libxml2`.

- The XSLT processor `xsltproc` is required for building the documentation in HTML format. For Ubuntu, it is provided by the package `libxslt`.

- The program `dblatex` is required for building the documentation in PDF format. For Ubuntu, it is provided by the package `dblatex`.

- The program `dbtoepub` is required for building the documentation in EPUB format. For Ubuntu, it is provided by the package `dbtoepub`.

For the developers's documentation

- The program `doxygen` is required for building the documentation. For Ubuntu, it is provided by the package `doxygen`.

Example: Installing dependencies on Linux

Database dependencies

    sudo apt-get install postgresql-16 postgresql-server-dev-16 postgresql-16-postgis

Build dependencies

    sudo apt-get install cmake gcc libgsl-dev

### Configuring

MobilityDB uses the `cmake` system to do the configuration. The build directory must be different from the source directory.

To create the build directory

    mkdir build

To see the variables that can be configured

    cd build
    cmake -L ..

### Build and Install

Notice that the current version of MobilityDB has been tested on Linux, MacOS, and Windows systems. It may work on other Unix-like systems, but remain untested. We are looking for volunteers to help us to test MobilityDB on multiple platforms.

The following instructions start from `path/to/MobilityDB` on a Linux system

    mkdir build
    cd build
    cmake ..
    make
    sudo make install

When the configuration changes

    rm -rf build

and start the build process as mentioned above.

### Testing

MobilityDB uses `ctest`, the CMake test driver program, for testing. This program will run the tests and report results.

To run all the tests

    ctest

To run a given test file

    ctest -R '021_tbox'

To run a set of given test files you can use wildcards

    ctest -R '022_*'

### Documentation

MobilityDB user's documentation can be generated in HTML, PDF, and EPUB format. Furthermore, the documentation is available in English and in other languages (currently, only in Spanish). The user's documentation can be generated in all formats and in all languages, or specific formats and/or languages can be specified. MobilityDB developer's documentation can only be generated in HTML format and in English.

The variables used for generating user's and the developer's documentation are as follows:

### Variables for the user's and the developer's documentation

Variable | Default value | Comment
`DOC_ALL` | `BOOL=OFF` | The user's documentation is generated in HTML, PDF, and EPUB formats.
`DOC_HTML` | `BOOL=OFF` | The user's documentation is generated in HTML format.
`DOC_PDF` | `BOOL=OFF` | The user's documentation is generated in PDF format.
`DOC_EPUB` | `BOOL=OFF` | The user's documentation is generated in EPUB format.
`LANG_ALL` | `BOOL=OFF` | The user's documentation is generated in English and in all available translations.
`ES` | `BOOL=OFF` | The user's documentation is generated in English and in Spanish.
`DOC_DEV` | `BOOL=OFF` | The English developer's documentation is generated in HTML format.

Generate the user's and the developer's documentation in all formats and in all languages.

    cmake -D DOC_ALL=ON -D LANG_ALL=ON -D DOC_DEV=ON ..
    make doc
    make doc_dev

Generate the user's documentation in HTML format and in all languages.

    cmake -D DOC_HTML=ON -D LANG_ALL=ON ..
    make doc

Generate the English user's documentation in all formats.

    cmake -D DOC_ALL=ON ..
    make doc

Generate the user's documentation in PDF format in English and in Spanish.

    cmake -D DOC_PDF=ON -D ES=ON ..
    make doc

## Installation from Binaries

### Debian-based Linux Distributions

Support for Debian-based Linux systems, such as Ubuntu and Arch Linux, is being developed.

### Windows

Since PostGIS version 3.3.3, MobilityDB is distributed in the PostGIS Bundle for Windows, which is available on application stackbuilder and OSGeo website. For more information, refer to the PostGIS documentation.

## Support

MobilityDB community support is available through the MobilityDB github page, documentation, tutorials, mailing lists and others.

### Reporting Problems

Bugs are reported and managed in an issue tracker. Please follow these steps:

1. Search the tickets to see if your problem has already been reported. If so, add any extra context you might have found, or at least indicate that you too are having the problem. This will help us prioritize common issues.

2. If your problem is unreported, create a new issue for it.

3. In your report include explicit instructions to replicate your issue. The best tickets include the exact SQL necessary to replicate a problem. Please also, note the operating system and versions of MobilityDB, PostGIS, and PostgreSQL.

4. It is recommended to use the following wrapper on the problem to pin point the step that is causing the problem.

       SET client_min_messages TO debug;
       <your code>
       SET client_min_messages TO notice;

### Mailing Lists

There are two mailing lists for MobilityDB hosted on OSGeo mailing list server:

- User mailing list: http://lists.osgeo.org/mailman/listinfo/mobilitydb-users

- Developer mailing list: http://lists.osgeo.org/mailman/listinfo/mobilitydb-dev

For general questions and topics about how to use MobilityDB, please write to the user mailing list.

## Migrating from Version 1.2 to Version 1.3

MobilityDB 1.3 is a major revision with respect to version 1.2. The most important change in version 1.3 was to enable new spatiotemporal types. While version 1.2 defined the spatiotemporal types `tgeompoint` (temporal geometry point), `tgeogpoint` (temporal geography point), and `tnpoint` (temporal network point), version 1.3 added the new types `tgeometry` (temporal geometry), `tgeography` (temporal geography), `tcbuffer` (temporal circular buffer), `tpose` (temporal pose), and `trgeometry` (temporal rigid geometry). At a conceptual level, all the spatiotemporal types are organized in the hierarchy depicted in tspatial_fig.

In order to enable the above, a refactoring of the code base was necessary. All the types provided by version 1.2 in addition to the new types `tgeometry` and `tgeography` are defined as core types and thus, are always included in the building process. Each one of the other spatiotemporal types can be included in the building process by setting its corresponding compilation flag. For example, when adding `-DCBUFFER=1` the types built upon the `cbuffer` base type, that is `cbuffer`, `cbufferset`, and `tcbuffer`, will be included in the building process. The possibility to select the types to be included in the executable program is important in particular for stream processing, due to the limited capability of the edge devices. Please notice that the new types `tcbuffer`, `tpose`, and `trgeometry` are still in development and will be finalized in a forthcoming release.

In addition, the API of MobilityDB and MEOS was extended with new functionality and streamlined to improve usability. Finally, version 1.3 also enables the latest versions PostgreSQL 18 and PostGIS 3.6.0. For all these reasons, the binary format of the temporal types have changed from version 1.2 to 1.3 and thus a backup and restore is needed for migrating to the newer version 1.3 of MobilityDB.