numericaltypes-header

A collection of simple type aliases restricting to numerical vectors or matrices for multiple dispatch.

Please read the documentation for detailed usage and tutorials.

Stable Docs Dev Docs Testing Status Coverage
Stable Dev Build Status Codecov
Release JuliaHub Status Dependents Zenodo DOI
version pkgeval deps DOI

Overview

The purpose of this package is to define a set of commonly used aliases in numerical algorithms when it is known that an input vector or matrix should have an element type of floating-point or integer.

This package was inspired by the blurb in StatsBase.jl that defined a set of type aliases to serve this very purpose.

Installation

This project is distributed as a Julia package, available on JuliaHub. Its usage follows the usual Julia package installation procedure, interactively:

] add NumericalTypeAliases

or programmatically:

using Pkg
Pkg.add("NumericalTypeAliases")

You may also add the package directly from GitHub to get the latest changes between releases:

] add https://github.com/AP6YC/NumericalTypeAliases.jl

Quickstart

After installation, load the module with

using NumericalTypeAliases

Then, you can define your functions with these type aliases. For example, say that you have a function that accepts only real-valued vectors because integer don't make sense in your specific situation:

function my_real_func(input::RealVector)
    # Do some math on a 1D vector with floats.
end

Or say that you know that you need a function to operate on an array with a list of indices. You know that floats don't make sense for indexing, so you would write with IntegerVector:

function my_indexer(data::RealMatrix, indices::IntegerVector)
    for ix in eachindex(indices)
        println(data[ix, :])
    end
end

Furthermore, if you know that you need a real-valued number but want your package to still support 32-bit systems, you wouldn't hardcode Float64 everywhere like usual. Instead, you could write with the abstract type RealFP (which is just an alias for AbstractFloat):

function my_float_func(datum::RealFP)
    # Do math with a real-valued floating point variable
end

As a bonus, say that you want to specify a hardcoded type within a struct as a float, but you don't want to write Float64 or Float32. In the same way that the Julia Base defines an Int as the largest integer on your system, you can define a variable to be of the larget native floating point variable on your system depending on the system word size with Float:

# Make a struct that will compile with the largest available float size
struct MyStruct
    cool_variable::Float
end

# Make a cool struct
MyStruct(3.14)

NOTE RealFP is the abstract type, and Float is the concrete type. This is just like in base Julia where Integer is the abstract type, and Int is the concrete type. This Float type is provided for semantic convenience, though beware that it has been the subject of great debate.

Aliases

The aliases exported in this package are:

  • Real-valued arrays:
  • Integer-valued arrays:
  • Single values:
    • RealFP: an abstract floating point type, same as AbstractFloat.
    • Float: a concrete floating point type, likely Float64 depending on the system.

Furthermore, the package exports some convenience variables:

  • NTA_VERSION: the version of NumericalTypeAliases.jl that is installed on the system.
  • NTA_ABSTRACT_TYPES: a list of the abstract types in the package.
  • NTA_CONCRETE_TYPES: a list of the concrete types in the package.
  • NTA_TYPES: a combined list of all abstract and concrete types in the package.

Contributing

If you have a question or concern, please raise an issue. For more details on how to work with the project, propose changes, or even contribute code, please see the Developer Notes in the project's documentation.

In summary:

  1. Questions and requested changes should all be made in the issues page. These are preferred because they are publicly viewable and could assist or educate others with similar issues or questions.
  2. For changes, this project accepts pull requests (PRs) from feature/<my-feature> branches onto the develop branch using the GitFlow methodology. If unit tests pass and the changes are beneficial, these PRs are merged into develop and eventually folded into versioned releases.
  3. The project follows the Semantic Versioning convention of major.minor.patch incremental versioning numbers. Patch versions are for bug fixes, minor versions are for backward-compatible changes, and major versions are for new and incompatible usage changes.

FAQs

You may have some questions....

Why does this package exist?

I have been duplicating this code across several different Julia projects, so I decided to finally modularize it like a big kid.

Why not use ScientificTypes.jl?

This package may very well evolve to convert its type aliases into an extended ScientificTypes convention. But today is not that day.

Why is the testing coverage at 0%?

The Julia unit testing coverage methods don't seem to concern themselves with constant aliases of types, which is the only thing that this package contains. Despite the fact that these types are tested with various assertions, these sadly don't register as covered lines. Full coverage reporting is planned for this package in the future, but today is not that day.

Why the over-the-top retro logo?

This package is so small, simple, and downright boring that it had might as well have a flashy logo to be any kind of memorable whatsoever. Also, retro is always in style (contradiction intended).

Acknowledgements

Authors

This package is developed and maintained by Sasha Petrenko with sponsorship by the Applied Computational Intelligence Laboratory (ACIL). This project is supported by grants from the Night Vision Electronic Sensors Directorate, the DARPA Lifelong Learning Machines (L2M) program, Teledyne Technologies, and the National Science Foundation. The material, findings, and conclusions here do not necessarily reflect the views of these entities.

History

  • 9/29/2022 - Begin project.
  • 9/30/2022 - Submit v0.1.0 to JuliaHub.
  • 10/10/2022 - v0.2.0 release.

License

This software is openly maintained by the ACIL of the Missouri University of Science and Technology under the MIT License.

Citation

This project has a citation file file that generates citation information for the package, which can be accessed at the "Cite this repository button" under the "About" section of the GitHub page.

You may also cite this repository with the following BibTeX entry:

@misc{NumericalTypeAliases,
  doi = {10.5281/zenodo.7183296},
  url = {https://doi.org/10.5281/zenodo.7183296},
  author = {Sasha Petrenko},
  title = {NumericalTypeAliases.jl: A Julia Package for Function Dispatch on Numerical Types},
}