IntervalOfValidity Class Reference

Public Member Functions
	__init__ (self, *iov)
	first (self)
	first_exp (self)
	first_run (self)
	final (self)
	final_exp (self)
	final_run (self)
	__repr__ (self)
	__eq__ (self, other)
	__lt__ (self, other)
	__and__ (self, other)
	__or__ (self, other)
	__sub__ (self, other)
	__hash__ (self)
	subtract (self, other)
	intersect (self, other)
	union (self, other, allow_startone=False)
	contains (self, exp, run)
	is_open (self)
	tuple (self)

Static Public Member Functions
	always ()

Public Attributes
tuple	final = 0
	Doxygen complains without this string.
	first

Private Attributes
	__first = tuple(iov[:2])
	tuple with the first valid exp, run
	__final = tuple(math.inf if x == -1 else x for x in iov[2:])
	tuple with the final valid exp, run

Detailed Description

Interval of validity class to support set operations like union and
intersection.

An interval of validity is a set of runs for which something is valid. An
IntervalOfValidity consists of a `first` valid run and a `final` valid run.

Warning:
    The `final` run is inclusive so the the validity is including the final run.

Each run is identified by a experiment number and a run number. Accessing
`first` or `final` will return a tuple ``(experiment, run)`` but the
elements can also be accessed separately with `first_exp`, `first_exp`,
`final_exp` and `final_run`.

For `final` there's a special case where either the run or both, the run and
the experiment number are infinite. This means the validity extends to all
values. If only the run number is infinite then it's valid for all further
runs in this experiment. If both are infinite the validity extends to everything.

For simplicity ``-1`` can be passed in instead of infinity when creating objects.

Definition at line 24 of file iov.py.

Constructor & Destructor Documentation

__init__()

__init__	(		self,
		*	iov )

Create a new object.

It can be either instantiated by providing four values or one tuple/list
with four values for first_exp, first_run, final_exp, final_run

Definition at line 48 of file iov.py.

    def __init__(self, *iov):
        """Create a new object.
 
        It can be either instantiated by providing four values or one tuple/list
        with four values for first_exp, first_run, final_exp, final_run
        """
        if len(iov) == 1 and isinstance(iov[0], (list, tuple)):
            iov = iov[0]
        if len(iov) != 4:
            raise ValueError("A iov should have four values")
        
        self.__first = tuple(iov[:2])
        
        self.__final = tuple(math.inf if x == -1 else x for x in iov[2:])
        if math.isinf(self.__final[0]) and not math.isinf(self.__final[1]):
            raise ValueError(f"Unlimited final experiment but not unlimited run: {self}")
        if self.__first[0] > self.__final[0]:
            raise ValueError(f"First exp larger than final exp: {self}")
        if self.__first[0] == self.__final[0] and self.__first[1] > self.__final[1]:
            raise ValueError(f"First run larger than final run: {self}")
        if self.__first[0] < 0 or self.__first[1] < 0:
            raise ValueError(f"Negative first exp or run: {self}")
 

Member Function Documentation

__and__()

__and__	(		self,
			other )

Intersection between iovs. Will return None if the payloads don't overlap

Definition at line 126 of file iov.py.

    def __and__(self, other):
        """Intersection between iovs. Will return None if the payloads don't overlap"""
        if not isinstance(other, IntervalOfValidity):
            return NotImplemented
        return self.intersect(other)
 

__eq__()

__eq__	(		self,
			other )

Check for equality

Definition at line 114 of file iov.py.

    def __eq__(self, other):
        """Check for equality"""
        if not isinstance(other, IntervalOfValidity):
            return NotImplemented
        return (self.__first, self.__final) == (other.__first, other.__final)
 

__hash__()

__hash__

(

self

)

Make object hashable

Definition at line 145 of file iov.py.

    def __hash__(self):
        """Make object hashable"""
        return hash((self.__first, self.__final))
 

__lt__()

__lt__	(		self,
			other )

Sort by run values

Definition at line 120 of file iov.py.

    def __lt__(self, other):
        """Sort by run values"""
        if not isinstance(other, IntervalOfValidity):
            return NotImplemented
        return (self.__first, self.__final) < (other.__first, other.__final)
 

__or__()

__or__	(		self,
			other )

Union between iovs. Will return None if the iovs don't overlap or
connect to each other

Definition at line 132 of file iov.py.

    def __or__(self, other):
        """Union between iovs. Will return None if the iovs don't overlap or
        connect to each other"""
        if not isinstance(other, IntervalOfValidity):
            return NotImplemented
        return self.union(other, False)
 

__repr__()

__repr__

(

self

)

Return a printable representation

Definition at line 110 of file iov.py.

    def __repr__(self):
        """Return a printable representation"""
        return str(self.__first + self.__final)
 

__sub__()

__sub__	(		self,
			other )

Difference between iovs. Will return None if nothing is left over

Definition at line 139 of file iov.py.

    def __sub__(self, other):
        """Difference between iovs. Will return None if nothing is left over"""
        if not isinstance(other, IntervalOfValidity):
            return NotImplemented
        return self.subtract(other)
 

always()

always ( )

static

Return an iov that is valid everywhere

>>> IntervalOfValidity.always()
(0, 0, inf, inf)

Definition at line 72 of file iov.py.

    def always():
        """Return an iov that is valid everywhere
 
        >>> IntervalOfValidity.always()
        (0, 0, inf, inf)
        """
        return IntervalOfValidity(0, 0, -1, -1)
 

contains()

contains	(		self,
			exp,
			run )

Check if a run is part of the validity

Definition at line 253 of file iov.py.

    def contains(self, exp, run):
        """Check if a run is part of the validity"""
        return self.first <= (exp, run) <= self.final
 

final()

final

(

self

)

Return the final valid experiment,run

Definition at line 96 of file iov.py.

    def final(self):
        """Return the final valid experiment,run"""
        return self.__final
 

final_exp()

final_exp

(

self

)

Return the final valid experiment

Definition at line 101 of file iov.py.

    def final_exp(self):
        """Return the final valid experiment"""
        return self.__final[0]
 

final_run()

final_run

(

self

)

Return the final valid run

Definition at line 106 of file iov.py.

    def final_run(self):
        """Return the final valid run"""
        return self.__final[1]
 

first()

first

(

self

)

Return the first valid experiment,run

Definition at line 81 of file iov.py.

    def first(self):
        """Return the first valid experiment,run"""
        return self.__first
 

first_exp()

first_exp

(

self

)

Return the first valid experiment

Definition at line 86 of file iov.py.

    def first_exp(self):
        """Return the first valid experiment"""
        return self.__first[0]
 

first_run()

first_run

(

self

)

Return the first valid run

Definition at line 91 of file iov.py.

    def first_run(self):
        """Return the first valid run"""
        return self.__first[1]
 

intersect()

intersect	(		self,
			other )

Intersection with another iov.

Will return None if the payloads don't overlap

    >>> iov1 = IntervalOfValidity(1,0,2,5)
    >>> iov2 = IntervalOfValidity(2,0,2,-1)
    >>> iov3 = IntervalOfValidity(2,10,5,-1)
    >>> iov1.intersect(iov2)
    (2, 0, 2, 5)
    >>> iov2.intersect(iov3)
    (2, 10, 2, inf)
    >>> iov3.intersect(iov1) is None
    True

Definition at line 187 of file iov.py.

    def intersect(self, other):
        """Intersection with another iov.
 
        Will return None if the payloads don't overlap
 
            >>> iov1 = IntervalOfValidity(1,0,2,5)
            >>> iov2 = IntervalOfValidity(2,0,2,-1)
            >>> iov3 = IntervalOfValidity(2,10,5,-1)
            >>> iov1.intersect(iov2)
            (2, 0, 2, 5)
            >>> iov2.intersect(iov3)
            (2, 10, 2, inf)
            >>> iov3.intersect(iov1) is None
            True
 
        """
        if other.first <= self.final and other.final >= self.first:
            return IntervalOfValidity(*(max(self.first, other.first) + min(self.final, other.final)))
        return None
 

is_open()

is_open

(

self

)

Check whether the iov is valid until infinity

Definition at line 258 of file iov.py.

    def is_open(self):
        """Check whether the iov is valid until infinity"""
        
        return self.final == (math.inf, math.inf)
 

subtract()

subtract	(		self,
			other )

Return a new iov with the validity of the other removed.
Will return None if everything is removed.

Warning:
    If the other iov is in the middle of the validity we will return a
    tuple of two new iovs

        >>> iov1 = IntervalOfValidity(0,0,10,-1)
        >>> iov2 = IntervalOfValidity(5,0,5,-1)
        >>> iov1 - iov2
        ((0, 0, 4, inf), (6, 0, 10, inf))

Definition at line 149 of file iov.py.

    def subtract(self, other):
        """Return a new iov with the validity of the other removed.
        Will return None if everything is removed.
 
        Warning:
            If the other iov is in the middle of the validity we will return a
            tuple of two new iovs
 
                >>> iov1 = IntervalOfValidity(0,0,10,-1)
                >>> iov2 = IntervalOfValidity(5,0,5,-1)
                >>> iov1 - iov2
                ((0, 0, 4, inf), (6, 0, 10, inf))
        """
        if other.first <= self.first and other.final >= self.final:
            # full overlap
            return None
        if other.first > self.first and other.final < self.final:
            # the one we want to remove is in the middle, return a pair of iovs
            # by subtracting two extended once
            iov1 = self.subtract(IntervalOfValidity(other.first + (-1, -1)))
            iov2 = self.subtract(IntervalOfValidity((0, 0) + other.final))
            return (iov1, iov2)
        if other.first <= self.final and other.final >= self.first:
            # one sided overlap, figure out which side and calculate the remainder
            if self.first < other.first:
                end_run = other.first_run - 1
                end_exp = other.first_exp if end_run >= 0 else other.first_exp - 1
                return IntervalOfValidity(self.first + (end_exp, end_run))
            else:
                start_run = other.final_run + 1
                start_exp = other.final_exp
                if math.isinf(other.final_run):
                    start_exp += 1
                    start_run = 0
                return IntervalOfValidity((start_exp, start_run) + self.final)
        # no overlap so return unchanged
        return self
 

tuple()

tuple

(

self

)

Return the iov as a tuple with experiment/run numbers replaced with -1

This is mostly helpful where infinity is not supported and is how the
intervals are represented in the database.

    >>> a = IntervalOfValidity.always()
    >>> a
    (0, 0, inf, inf)
    >>> a.tuple
    (0, 0, -1, -1)

Definition at line 264 of file iov.py.

    def tuple(self):
        """Return the iov as a tuple with experiment/run numbers replaced with -1
 
        This is mostly helpful where infinity is not supported and is how the
        intervals are represented in the database.
 
            >>> a = IntervalOfValidity.always()
            >>> a
            (0, 0, inf, inf)
            >>> a.tuple
            (0, 0, -1, -1)
        """
        return self.__first + tuple(-1 if math.isinf(x) else x for x in self.__final)
 
 

union()

union	(		self,
			other,
			allow_startone = False )

Return the union with another iov.

    >>> iov1 = IntervalOfValidity(1,0,1,-1)
    >>> iov2 = IntervalOfValidity(2,0,2,-1)
    >>> iov3 = IntervalOfValidity(2,10,5,-1)
    >>> iov1.union(iov2)
    (1, 0, 2, inf)
    >>> iov2.union(iov3)
    (2, 0, 5, inf)
    >>> iov3.union(iov1) is None
    True

Warning:
   This method will return None if the iovs don't overlap or connect to
   each other as no union can be formed.

Parameters:
    other (IntervalOfValidity): IoV to calculate the union with
    allow_startone (bool): If True we will consider run 0 and run 1 the
        first run in an experiment. This means that if one of the iovs has
        un unlimited final run it can be joined with the other iov if the
        experiment number increases and the iov starts at run 0 and 1. If
        this is False just run 0 is considered the next run.

            >>> iov1 = IntervalOfValidity(0,0,0,-1)
            >>> iov2 = IntervalOfValidity(1,1,1,-1)
            >>> iov1.union(iov2, False) is None
            True
            >>> iov1.union(iov2, True)
            (0, 0, 1, inf)

Definition at line 207 of file iov.py.

    def union(self, other, allow_startone=False):
        """
        Return the union with another iov.
 
            >>> iov1 = IntervalOfValidity(1,0,1,-1)
            >>> iov2 = IntervalOfValidity(2,0,2,-1)
            >>> iov3 = IntervalOfValidity(2,10,5,-1)
            >>> iov1.union(iov2)
            (1, 0, 2, inf)
            >>> iov2.union(iov3)
            (2, 0, 5, inf)
            >>> iov3.union(iov1) is None
            True
 
        Warning:
           This method will return None if the iovs don't overlap or connect to
           each other as no union can be formed.
 
        Parameters:
            other (IntervalOfValidity): IoV to calculate the union with
            allow_startone (bool): If True we will consider run 0 and run 1 the
                first run in an experiment. This means that if one of the iovs has
                un unlimited final run it can be joined with the other iov if the
                experiment number increases and the iov starts at run 0 and 1. If
                this is False just run 0 is considered the next run.
 
                    >>> iov1 = IntervalOfValidity(0,0,0,-1)
                    >>> iov2 = IntervalOfValidity(1,1,1,-1)
                    >>> iov1.union(iov2, False) is None
                    True
                    >>> iov1.union(iov2, True)
                    (0, 0, 1, inf)
 
        """
        # check the trivial case of overlapping
        if other.first <= self.final and other.final >= self.first:
            return IntervalOfValidity(min(self.first, other.first) + max(self.final, other.final))
        # ok, let's do the less simple case where they don't overlap but join directly
        for i1, i2 in (self, other), (other, self):
            if (i1.first == (i2.final_exp, i2.final_run + 1) or
                (math.isinf(i2.final_run) and (i1.first_exp == i2.final_exp + 1) and
                 (i1.first_run == 0 or allow_startone and i1.first_run == 1))):
                return IntervalOfValidity(i2.first + i1.final)
        # no union possible: not directly connected and not overlapping
        return None
 

Member Data Documentation

__final

__final = tuple(math.inf if x == -1 else x for x in iov[2:])

private

tuple with the final valid exp, run

Definition at line 61 of file iov.py.

__first

__first = tuple(iov[:2])

private

tuple with the first valid exp, run

Definition at line 59 of file iov.py.

final

final = 0

Doxygen complains without this string.

Definition at line 165 of file iov.py.

first

first

Definition at line 204 of file iov.py.

---

The documentation for this class was generated from the following file:

• framework/scripts/conditions_db/iov.py