Skip to content

A library of tools for scientific software development, with emphasis on also being able to build web interfaces using Emscripten.

License

Notifications You must be signed in to change notification settings

devosoft/Empirical

Repository files navigation

Empirical Logo

Empirical is a library of tools for developing useful, efficient, reliable, and available scientific software. The provided code is header-only and encapsulated into the emp namespace, so it is simple to incorporate into existing projects.

status CI Documentation Status DOI codecov DockerHub Documentation Coverage GitHub contributors

See our Built With Empirical Gallery for examples of web tools built with Empirical.

See our Quick Start Guides to start using the library.

Starting out on a new project that will use Empirical? Take a look at the cookiecutter Empirical project template for automatically setting up a directory structure with all the files you need to get started -- step-by-step instructions included!

Tools in Empirical include:

  • Web-enabled elements to facilitate compiling to JavaScript and with a full web interfaces, using Mozilla's Emscripten compiler (from C++ to high-efficiency JavaScript).
  • Debug tools to facilitate audited memory management; these tools are turned off outside of debug mode allowing the full speed of raw pointers and normal standard library components.
  • A wide range of Helper tools to streamline common scientific computing tasks such as configuration, data management, mathematical manipulations, etc. All of these are designed to be easy-to-use and efficient.
  • A powerful set of evolution tools for building Artificial Life or Evolutionary Computation software.
  • A signal-action system that allows for efficient customization of tools, and flexible software that can easily facilitate plug-in functionality.

See https://empirical.readthedocs.io/en/latest for more detailed documentation on the available source files.

Citing

If Empirical contributes to a scientific publication, please cite it as

Vostinar, A., Lalejini, A., Ofria, C., Dolson, E., & Moreno, M.A. (2024). Empirical: A scientific software library for research, education, and public engagement. Journal of Open Source Software, 9(98), 6617, https://doi.org/10.21105/joss.06617

@article{devosoft2024empirical,
  year = {2024},
  publisher = {The Open Journal},
  author = {Vostinar, Anya and Lalejini, Alexander and Ofria, Charles and Dolson, Emily and Moreno, Matthew Andres},
  title = {Empirical: A scientific software library for research, education, and public engagement},
  journal = {Journal of Open Source Software},
  volume = {9},
  number = {98},
  pages = {6617},
  doi = {10.21105/joss.06617},
  url = {https://doi.org/10.21105/joss.06617},
}

Please cite phylogeny tracking tools separately as shown here. And don't forget to leave a star on GitHub!

Directory Structure

Folder Description
demos/ examples of mini projects using Empirical
doc/ Documentation files (including for auto generation of docs)
examples/ Example code for many of the above tools (sub-directory structure parallels source/)
include/ Header files that make up the Empirical library (see below for details)
Planning/ Scattered notes about future development (most notes found in GitHub issue tracker)
tests/ Unit tests
third-party/ Non-empirical dependencies

Sub-folders in include/emp directory

Sub-Folder Description
base/ Debug tools used throughout Empirical for fast and efficient memory management
bits/ Tools for conveniently and efficiently working with bit representations
config/ Tools to build a simple configuration system (including compile-time optimizations)
control/ Signaling tools allowing for fast and dynamic interaction across components
compiler/ Components for compiling code
data/ Tools for easy data management and output
datastructs/ A variety of useful data structures and tools for using data structures
debug/ Tools to facilitate debugging (particularly of emscripten-generated web code)
functional/ Tools for handling functions, sets of functions, and memoization
games/ Implementations of simple games
geometry/ Geometry and physics-based tools for implementing simple virtual worlds
hardware/ Implementation of basic virtual hardware that is easy to configure
io/ Tools for handling input/output
matching/ Tools for tag-based matching
math/ Generally useful tools for math and randomness
meta/ Helpful tools for template meta-programming
prefab/ Prefabricated web elements to drop onto web pages
scholar/ Tools for tracking authors, citations, and bibliographies
tools/ Basic tools that are generally useful for scientific software
web/ Tools for building web interfaces (more low-level than in prefab)
Evolve/ Specialized tools for building Artificial Life or Evolutionary Computation projects
in_progress/ Tools that are being worked on, but not at all ready for public consumption

Development Status

Empirical is under heavy development. As such, many source files have at least one of the following statuses:

Status Meaning
DESIGN Notes are in place, but no (or minimal) working code
EXPLORATORY Some functionality may work, but needs re-engineering to get right
ALPHA Some basic functionality works, but more features still need to be added and tested
BETA Basic functionality is all in place, but needs more thorough testing.
RELEASE Well-tested functionality and used in multiple projects, at least by authors
STABLE Used by many non-authors in assorted projects without fixes for extended period
ABANDONED May have worked, or may not; no longer being developed
BROKEN Once worked (at least BETA level), but now needs to be repaired (not abandoned!)
CLEANUP At least BETA, but needs code cleanup, fixing of warnings, etc
DEPRECATED Functionality has been replaced and should shift to replacement.
EXTERNAL Part of another project (cited above); not developed as part of Empirical

Levelization

The structure of Empirical is levelized to facilitate development and testing. This means that all directories are on a level where dependencies are either internal to that directory or on lower levels. Likewise, within a directory, files have a level and depend only on other files at lower levels.

Level Folders
0 base/
1 meta/
2 tools/
3 config/ control/ data/ games/ geometry/ hardware/ scholar/
4 Evolve/ (data, control) web/ (config, control)