Skip to content

Commit

Permalink
Merge pull request #167 from Stanford-NavLab/v1.0.3
Browse files Browse the repository at this point in the history
In line with user requests, we are now updating our GNSS library to support Python 3.12! The library is still compatible with Python 3.9, 3.10, and 3.11 across Linux, MacOS, Windows, and Google Colab (Python 3.10). But, if you wish to continue using Python 3.8, we recommend that you stay with v1.0.2.

Please see the upcoming v1.0.3 release for more information.
  • Loading branch information
danineamati authored Aug 27, 2024
2 parents f778d6e + 87428c4 commit aed0a74
Show file tree
Hide file tree
Showing 74 changed files with 3,800 additions and 1,966 deletions.
14 changes: 7 additions & 7 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,18 @@ jobs:
runs-on: ${{ matrix.os }}
strategy:
matrix:
python-version: ["3.8", "3.11"]
python-version: ["3.9","3.10","3.11","3.12"]
os: [ubuntu-latest, macos-latest, windows-latest]
fail-fast : false
defaults:
run:
shell: bash

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
id: setup-python
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install Poetry
Expand All @@ -43,7 +43,7 @@ jobs:
# Load cached environment, if it exists
- name: Load cached poetry environment
id: cached-poetry-dependencies
uses: actions/cache@v3
uses: actions/cache@v4
with:
path: .venv
key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
Expand All @@ -68,7 +68,7 @@ jobs:
source $VENV
poetry run pytest --cov=gnss_lib_py/algorithms --cov=gnss_lib_py/navdata --cov=gnss_lib_py/parsers --cov=gnss_lib_py/utils --cov=gnss_lib_py/visualizations --cov-report=xml
- name: Upload coverage report to code-cov
uses: codecov/codecov-action@v3
uses: codecov/codecov-action@v4
with:
fail_ci_if_error: true
token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
Expand All @@ -79,13 +79,13 @@ jobs:
runs-on: ubuntu-latest
name: Check if index.rst and README.md weren't changed together
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Get changed files since last remote commit
id: changed-files
uses: tj-actions/changed-files@v34
uses: tj-actions/changed-files@v44

- name: Check if index.rst changed when README.md file changes
if: contains(steps.changed-files.outputs.modified_files, 'README.md') && !contains(steps.changed-files.outputs.modified_files, 'docs/source/index.rst')
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/pip-install.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,13 @@ jobs:
runs-on: ${{ matrix.os }}
strategy:
matrix:
python-version: ["3.8"]
python-version: ["3.9"]
os: [ubuntu-latest]

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install using pip
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/pylint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8"]
python-version: ["3.9"]
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
id: setup-python
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install Poetry
Expand All @@ -29,7 +29,7 @@ jobs:
installer-parallel: true # default option selected currently
- name: Load cached poetry environment
id: cached-poetry-dependencies
uses: actions/cache@v3
uses: actions/cache@v4
with:
path: .venv
key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/pypi-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ jobs:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Set up Python 3.10
uses: actions/setup-python@v4
uses: actions/setup-python@v5
with:
python-version: "3.10"

Expand Down
3 changes: 0 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -151,9 +151,6 @@ target/
profile_default/
ipython_config.py

# pyenv
# .python-version

# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
Expand Down
2 changes: 1 addition & 1 deletion .python-version
Original file line number Diff line number Diff line change
@@ -1 +1 @@
3.8.9
3.9.19
2 changes: 1 addition & 1 deletion .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ version: 2
build:
os: ubuntu-20.04
tools:
python: "3.8"
python: "3.9"

# Build documentation in the docs/ directory with Sphinx
sphinx:
Expand Down
39 changes: 27 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,31 @@ gnss_lib_py
`gnss_lib_py` is a modular Python tool for parsing, analyzing, and
visualizing Global Navigation Satellite Systems (GNSS) data and state
estimates.
It also provides an intuitive and modular framework allowing users to
It also provides an intuitive and modular framework which allows users to
quickly prototype, implement, and visualize GNSS algorithms.
`gnss_lib_py` is modular in the sense that multiple types of
algorithms can be easily exchanged for each other and extendable in
facilitating user-specific extensions of existing implementations.
algorithms or datasets can be easily exchanged for each other.
It is extendable in facilitating user-specific extensions of existing
implementations.

<img src="https://raw.githubusercontent.com/Stanford-NavLab/gnss_lib_py/main/docs/source/img/skyplot.png" alt="satellite skyplot" width="600"/>
<img src="https://raw.githubusercontent.com/Stanford-NavLab/gnss_lib_py/main/docs/source/img/glp_architecture.svg" alt="Architecture of gnss-lib-py library" width="800"/>

`gnss_lib_py` contains parsers for common file types used for
storing GNSS measurements, benchmark algorithms for processing
measurements into state estimates and visualization tools for measurements
and state estimates.
The modularity of `gnss_lib_py` is made possibly by the unifying
`NavData` class, which contains methods to add, remove and modify
numeric and string data consistently.
We provide standard row names for `NavData` elements on the
`NavData` class, with accompanying standard nomenclature, which can be
found in the
[reference page](https://gnss-lib-py.readthedocs.io/en/latest/reference/reference.html).
These names ensure cross compatibility between different datasets and
algorithms.
The standard nomenclature ensures cross compatibility between different
datasets and algorithms.

`NavData` combines the readability of `pandas.DataFrame` with `numpy.ndarray`
allowing for easy and fast access of numbers or strings.
We also provide functionality to add, remove and modify numeric and
string data consistently along with commonly needed supporting
functionality.

Documentation
-------------
Expand All @@ -51,7 +57,7 @@ Code Organization
├── parsers/ # Data parsers
├── utils/ # GNSS and common utilities
├── visualizations/ # plotting functions
└── __init__.py
└── __init__.py # Initialize gnss_lib_py
├── notebooks/ # Interactive Jupyter notebooks
├── tutorials/ # Notebooks with tutorial code
├── results/ # Location for result images/files
Expand All @@ -61,7 +67,7 @@ Code Organization
├── parsers/ # Tests for files in parsers
├── utils/ # Tests for files in utils
├── visualizations/ # Tests for files in visualizations
└── test_gnss_lib_py.py # High level checks for repository
└── conftest.py # Common methods for tests
├── CONTRIBUTORS.md # List of contributors
├── build_docs.sh # Bash script to build docs
├── poetry.lock # Poetry specific Lock file
Expand All @@ -70,14 +76,19 @@ Code Organization
```
In the directory organization above:

* The `algorithms` directory contains localization algorithms that
* The `algorithms` directory contains algorithms that
work by passing in a `NavData` class. Currently, the following
algorithms are implemented in the `algorithms`:

* Weighted Least Squares
* Extended Kalman Filter
* Calculating pseudorange residuals
* Fault detection and exclusion

* The `navdata` directory defines the `NavData` class, its methods, and
functions that operate on `NavData` instances, like `sort`, `concat`,
and others.

* The data parsers in the `parsers` directory allow for either loading
GNSS data into `gnss_lib_py`'s unifying `NavData` class or parsing
precise ephemerides data.
Expand All @@ -96,6 +107,10 @@ In the directory organization above:
visualizations, calculating multi-GNSS satellite PVT information,
satellite simulation, file operations, etc.

* The `visualizations` directory contains methods for plotting quantities
in `NavData`. It includes methods to plot metrics, positions on maps,
and skyplots of satellites visible from the receiver position.

Installation
------------

Expand Down
1 change: 1 addition & 0 deletions build_docs.sh
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
#!/bin/bash
# export requirements.txt for buildings docs
poetry config warnings.export false
poetry export -f requirements.txt --output ./docs/source/requirements.txt --with dev --without-hashes
# export requirements.txt for Conda environment setup
poetry export -f requirements.txt --output ./requirements.txt --without-hashes
Expand Down
2 changes: 1 addition & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
# -- Project information -----------------------------------------------------

project = 'gnss_lib_py'
copyright = '2022, Stanford NAV Lab'
copyright = '2024, Stanford NAV Lab'
author = 'Ashwin Kanhere, Derek Knowles'


Expand Down
12 changes: 8 additions & 4 deletions docs/source/contributing/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,15 @@ In your issue, please include:
* Your operating system name and version.
* Any details about your local setup that might be helpful in
troubleshooting.
* A minimal working example to reproduce the bug.
* A minimal working example (MWE) to reproduce the bug. An MWE
helps us reproduce the bug and troubleshoot the problem.
For more details on how to create an MWE, see
`this Stack Overflow guide <https://stackoverflow.com/help/minimal-reproducible-example>`.

Feature requests and feedback
-----------------------------

The best way to send feedback is to file an issue on
The best way to any send feedback is to file an issue on
`GitHub <https://github.com/Stanford-NavLab/gnss_lib_py/issues>`__.

If you are proposing a feature:
Expand All @@ -31,8 +34,9 @@ If you are proposing a feature:
* Keep the scope as narrow as possible, which will make it easier to
implement.
* This is a volunteer driven project and most contributions are a
result of other research projects. If you implement your requested
feature and submit a pull request, we will incorporate it.
result of other research projects. We welcome outside implementations
of additional features. If you implement your requested feature
and submit a pull request, we will incorporate it.

Additional Contributing Pages
-----------------------------
Expand Down
51 changes: 34 additions & 17 deletions docs/source/contributing/development.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,12 @@ Standard GitHub Workflow
2. If using poetry, follow the :ref:`developer install instructions<developer install>`
to install pyenv, poetry, and the python dependencies. If using
:code:`pip` or :code:`conda` for package management instead, use
:code:`pip install -r requirements.txt` to install dependencies.
:code:`pip` or :code:`conda` for package management instead, install
dependencies using

.. code-block:: bash
pip install -r requirements.txt
3. Create a local branch:

Expand All @@ -36,16 +40,21 @@ Standard GitHub Workflow

If the feature branch includes new functionality, you must also:

* update the "Code Organization" section of the :code:`README.md`
* update the "Code Organization" section of
:code:`docs/source/index.rst` to match the :code:`README.md`
* add a section in the appropriate tutorial notebook located in
:code:`notebooks/tutorials/*`
* if the feature is in a new file, import the file in the
`module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.

If directory level changes were made, you must also:

* update the "Code Organization" section of the :code:`README.md`
* update the "Code Organization" section of
:code:`docs/source/index.rst` to match the :code:`README.md`


5. Add tests for the newly added code and ensure the new code is covered.
See the :ref:`Testing<testing>` section for more details.
See the :ref:`Testing<testing>` and :ref:`Coverage<coverage>` pages
for more details.

6. When you're done making changes run all the tests with:

Expand Down Expand Up @@ -93,9 +102,10 @@ Standard GitHub Workflow
in the pull request, select the latest version release branch :code:`vX.Y.Z`
(with the highest number of all such branches). *Do not target the*
:code:`main` *branch in your pull request.* In the pull request,
add a code review request for a current maintainer of the repository.
The reviewers might add comments to ensure compliance with the rest
of the code.
add a code review request for a current maintainer of the repository
and provide a brief description of the implemented features.
The reviewers might add comments or suggest changes to ensure
compliance with the rest of the code.

.. _navlab_dev:

Expand All @@ -119,14 +129,18 @@ NAVLab GitHub Workflow

If the feature branch includes new functionality, you must also:

* update the "Code Organization" section of the :code:`README.md`
* update the "Code Organization" section of
:code:`docs/source/index.rst` to match the :code:`README.md`
* add a section in the appropriate tutorial notebook located in
:code:`notebooks/tutorials/*`
* if the feature is in a new file, import the file in the
`module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.

If directory level changes were made, you must also:

* update the "Code Organization" section of the :code:`README.md`
* update the "Code Organization" section of
:code:`docs/source/index.rst` to match the :code:`README.md`


5. Add tests for the newly added code and ensure the new code is covered.
See the :ref:`Testing<testing>` section for more details.

Expand Down Expand Up @@ -214,19 +228,22 @@ Pull Request Review Workflow
3. Verify that documentation is complete and updated if necessary. See
the :ref:`Documentation<documentation>` section for more details on
what is expected.

If the feature branch included new functionality, the following
should have also been updated:

* the "Code Organization" section of the :code:`README.md`
* the "Code Organization" section of
:code:`docs/source/index.rst` to match the :code:`README.md`
* the appropriate tutorial notebook located in
:code:`notebooks/tutorials/*` with a simple example of the new
functionality
* if a new file was created, it should likely be imported in the
`module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.

If the directory structure was modified, the following should also have
been updated:

* the "Code Organization" section of the :code:`README.md`
* the "Code Organization" section of
:code:`docs/source/index.rst` to match the :code:`README.md`

4. Verify that all tests run on your system:

.. code-block:: bash
Expand All @@ -243,7 +260,7 @@ Pull Request Review Workflow

.. code-block:: bash
poetry run pytest --cov=gnss_lib_py/algorithms --cov=gnss_lib_py/parsers --cov=gnss_lib_py/utils --cov-report=xml
poetry run pytest --cov=gnss_lib_py/algorithms --cov=gnss_lib_py/parsers --cov=gnss_lib_py/utils --cov-report=html
poetry run coverage report
See the :ref:`Coverage Report<coverage>` section for more details.
Expand Down
Loading

0 comments on commit aed0a74

Please sign in to comment.