Skip to main content

ExSpec Package

Overview

The ExSpec package provides tools to parse, manipulate, and analyze experiment specifications (exspecs) defined by a custom grammar. It includes functionality for:

  • Parsing exspecs from text which defines a formula on dictionaries.
  • Performing operations like MERGE and ALTERNATE on exspecs.
  • Resolving composed exspecs into a set of constituent atomic exspecs.
  • Pretty-printing atomic exspecs.
  • Flattening exspecs into flat dictionaries suitable for metadata storage (e.g., in InfluxDB).
  • De-flattening flattened exspecs with no information loss. *
  • Comparing exspecs to determine if one specializes another.
  • Comparing exspecs to determine if one is a subset of another.
  • Handling ranges, units, and physical quantities in exspecs.

Table of Contents

Installation

To install the exspec package, use pip:

pip install exspec

ExSpec Language

ExSpecs are organized as packages represented by files with the '.exspec' extension. It is assumed that all these files/packages are available in the same directory in order to resolve references to exspecs in-between packages.

Basic Syntax

An exspec is a set of dictionaries. Each dictionary in the ExSpec represents an alternate experiment specification within the composed experiment specification. A dictionary defines the parameters and configurations for experiments in a structured, hierarchical format. The syntax resembles a combination of JSON and custom constructs.

Example:

my_exspec = {
  prop1 = 'value1' ;
  prop2 = 42 ;
  nested = {
    prop3 = 3.14 ;
  };
}

ExSpecs can be specified as a formulation of different dictionaries:

Example:

my_exspec = {
  prop1 = 'value1' ;
  prop2 = 42 ;  
} MERGE {
  nested = {
    prop3 = 3.14 ;
  };
}

Propositions

A proposition is a key-value pair within an exspec's dictionaries. Propositions can be nested to create hierarchical structures.

Syntax:

property_name = property_value ;

Example:

simulation = {
    duration = 100 ;
    solver = 'DASSL' ;
    settings = {
        tolerance = 1e-6 ;
    } ;
}

Types

You can optionally specify the types of the value/s in a proposition. Properties can have explicit types specified, including basic types (str, int, float), composed types (e.g., list[int], list[list[ ... ]]).

Syntax:

property_name : type = value ;

Example:

simulation.solver : str = 'DASSL' ;

Physical Dimensions:

You can also specify dimensions of physical quantities as a dimensional formula.

Dimensions are specified using SI base units:

  • M (mass)
  • L (length)
  • T (time)
  • I (current)
  • K (temperature)
  • N (substance amount)
  • J (luminous intensity)

Example:

force : MLT-2 = 9.8 ;

Units

You can optionally specify units of the value/s in a proposition. Units can be any string representing a unit (e.g., m, s, g, N) There is no inbuilt library for conversion of units for comparison, so be careful to use only one standard system of units.

You can also optionally specify the prefix of the unit.

Prefixes:

  • n- (nano)
  • u- (micro)
  • m- (milli)
  • k- (kilo)
  • M- (mega)
  • G- (giga)
  • T- (tera)

Syntax:

property_name = value prefix-unit ;

Example:

length = 10 n-m ;
time = 5 k-s ;

The prefix is taken into account when comparing propositions. So 1e9 n-m == 1 m will evaluate to True.

Multi-Values

You can use the multivalued propositions to compactly describe a composed experiment specification, where the multivalued properties are chosen combinatorially.

There are 2 types of constructs to specify multiple values for a property. You can even specify the types and units of multivalued properties with no problems.

Range Syntax:

property_name = RANGE(start, stop, step) ;

Example:

temperature = RANGE(300, 350, 10) K ;

Set Syntax:

property_name = { value1; value2; value3 } ;

Example:

modes : str = { 'mode1'; 'mode2'; 'mode3' } ;

Composed Values

There may arise the need to specify a property that is a composition of multiple basic values. In such a case, you can use a List. The items of a list are not interpreted as leading to a composition of experiments.

Set Syntax:

property_name = [ value1, value2, value3 ] ;

Example:

modes : str = [ 'mode1', 'mode2', 'mode3' ] ;

Operations

ExSpecs can be defined as formulas (over dictionaries) by composing two operations:

  • MERGE : Combines two exspecs into one, ensuring no conflicting propositions.

  • ALTERNATE : Creates an exspec representing all combinations of the input exspecs.

Syntax:

exspec1 MERGE exspec2
exspec1 ALTERNATE exspec2

External References

ExSpecs can reference exspecs from other packages in formulas:

Syntax:

exspec1 OPERATION package_name::exspec_name

Getting Started

This project is licensed under the MIT License. See the LICENSE file for details.

Step 1: Install the package using pip.

pip install exspec

Step 2: Import the necessary modules in your Python script.

from exspec.parser import parse_exspec
from exspec import flatten_exspec
from exspec import ExSpec
from exspec import merge, alternate

Step 3: Define your exspecs as strings and parse them. You can also use exspecs defined in files instead.

input_text = """
simulation = {
    duration = 100 s
    solver = 'DASSL'
}
"""

exspecs = parse_exspec(input_text)
simulation_exspec = exspecs[0]

Step 4: Use the exspec as needed.

  • Flattening:
if simulation_exspec.is_atomic():
    flat_dicts = flatten_exspec(simulation_exspec)
    flat_dict = flat_dicts[0]
    # Use flat_dict as metadata
  • Operations:
merged_exspec = ExSpec('merged', merge(exspec1.dictionaries, exspec2.dictionaries))
alternated_exspec = ExSpec('alternated', alternate(exspec1.dictionaries, exspec2.dictionaries))
  • Comparison:
if exspec1.is_subset_of(exspec2):
    print(f"{exspec1.name} is a subset of {exspec2.name}")
elif exspec1.is_subset_of(exspec2) is None:
    print("Exspecs cannot be compared")
else:
    print(f"{exspec1.name} is not a subset of {exspec2.name}")

Example Script

An example script demonstrating how to use the package is included in exspec/example.py.

Running the Example:

python -m exspec.example

How to Invoke the Tests

Prerequisites:

  • Ensure you have the exspec package code and the tests/ directory in your project.

Steps:

  1. Navigate to the root directory of your project (where setup.py is located).

  2. Run the following command:

python -m unittest discover -s tests

Notes:

  • The tests use Python's built-in unittest framework.

  • The discover command automatically finds and runs all test modules in the tests/ directory.

Documentation

You can build and view the documentation by:

python -m exspec.docgen

Happy experimenting!

Metadata

Release files for exspec 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for exspec 0.1.1
File Size Uploaded Provenance Actions
exspec-0.1.1.tar.gz 23.3 kB Without provenance Details for exspec-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for exspec 0.1.1
File Interpreter ABI Platform Actions
exspec-0.1.1-py3-none-any.whl Python 3 none any Details for exspec-0.1.1-py3-none-any.whl

Total release size: 49.1 kB

Release files / exspec-0.1.1.tar.gz

Download URL exspec-0.1.1.tar.gz
Size 23.3 kB
Tags Source
SHA-256 checksum
How to use checksums
ed9b7fe363b61ca2e8cca3663c58409e643918c57c04a3d75aea8bc7c534af0f
BLAKE2b-256 checksum
How to use checksums
05773f1bbbf4717001da279ba7f2421686372eeff903e4310a402c92b786f710
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.1.1 CPython/3.11.2

Release files / exspec-0.1.1-py3-none-any.whl

Download URL exspec-0.1.1-py3-none-any.whl
Size 25.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
371c5f5ed5f0e2d567c8387e188acc2dbe45e05ec90a4dc65beceb0e33f5f0fc
BLAKE2b-256 checksum
How to use checksums
723eae5ef3a24515e49094b80dc4adc93fa10c3c315e96473d83ca123efbaf25
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.1.1 CPython/3.11.2

Security for exspec 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page