simulit 0.1.0__py3-none-any.whl

simulit/__init__.py

@@ -0,0 +1,35 @@
+from .simulit import (
+    __version__,
+    Detector,
+    Drift,
+    Observation,
+    GaussianSource,
+    ExponentialGalaxy,
+    UniformDisk,
+    generate_sources,
+    generate_galaxies,
+    simulate_events,
+    create_truth_catalogue,
+    save_truth_catalogue,
+    save_events_to_fits,
+    make_image_from_events,
+    add_simulated_events_to_existing_list,
+)
+
+__all__ = [
+    "__version__",
+    "Detector",
+    "Drift",
+    "Observation",
+    "GaussianSource",
+    "ExponentialGalaxy",
+    "UniformDisk",
+    "generate_sources",
+    "generate_galaxies",
+    "simulate_events",
+    "create_truth_catalogue",
+    "save_truth_catalogue",
+    "save_events_to_fits",
+    "make_image_from_events",
+    "add_simulated_events_to_existing_list",
+]

simulit/simulit.py

@@ -0,0 +1,702 @@
+#!/usr/bin/env python3
+
+
+import numpy as np
+
+from astropy.io import fits
+from dataclasses import dataclass, field
+from typing import ClassVar, TypeAlias
+
+
+__version__ = "0.1.0"
+FWHM_TO_SIGMA = 1.0 / (2.0 * np.sqrt(2.0 * np.log(2.0)))
+UVIT_FINAL_IMAGE_SIZE = 4800
+UVIT_FRAME_RATE = 28.719265
+
+
+@dataclass(frozen=True)
+class Detector:
+    """
+    Detector configuration used for event simulations.
+
+    Parameters
+    ----------
+    detector_size : int, optional
+        Size of the detector in pixels.
+        The default corresponds to the UVIT final image size.
+
+    frame_rate : float, optional
+        Detector frame rate in frames per second.
+        The default corresponds to the UVIT detector (full window mode).
+    """
+
+    detector_size: int = UVIT_FINAL_IMAGE_SIZE
+    frame_rate: float = UVIT_FRAME_RATE
+
+
+@dataclass(frozen=True)
+class Drift:
+    """
+    Pointing drift model.
+
+    A drift model specifies the detector X and Y offsets to be applied
+    to each detector frame during the simulation.
+
+    Parameters
+    ----------
+    x_offset, y_offset : ndarray
+        One-dimensional arrays containing the detector X and Y offsets,
+        in detector pixels, for each frame.
+    """
+
+    x_offset: np.ndarray
+    y_offset: np.ndarray
+
+    def __post_init__(self):
+        if len(self.x_offset) != len(self.y_offset):
+            raise ValueError("x_offset and y_offset must have the same length.")
+        if self.x_offset.ndim != 1 or self.y_offset.ndim != 1:
+            raise ValueError("Drift offsets must be one-dimensional arrays.")
+
+
+@dataclass
+class Observation:
+    """
+    Observation configuration.
+
+    An Observation combines the exposure time, detector configuration,
+    and an optional pointing drift model. Event lists can be simulated
+    from one or more source models using :meth:`simulate_events`.
+
+    Parameters
+    ----------
+    exposure : float
+        Exposure time in seconds.
+
+    detector : Detector, optional
+        Detector configuration. If not specified, the default UVIT
+        configuration is used.
+
+    drift : Drift, optional
+        Pointing drift model applied during the simulation.
+    """
+
+    exposure: float
+    detector: Detector = field(default_factory=Detector)
+    drift: Drift | None = None
+
+    def simulate_events(self, sources, rng=None):
+        return simulate_events(
+            exposure=self.exposure,
+            sources=sources,
+            detector=self.detector,
+            rng=rng,
+            drift=self.drift,
+        )
+
+
+@dataclass(frozen=True)
+class GaussianSource:
+    """
+    Gaussian point source.
+
+    Photons are sampled from a circular Gaussian distribution centred
+    at the specified detector position.
+
+    Parameters
+    ----------
+    rate : float
+        Source count rate in counts per second.
+
+    x, y : float
+        Detector coordinates of the source centre in detector pixels.
+
+    fwhm : float
+        Full width at half maximum of the Gaussian profile in detector
+        pixels.
+    """
+
+    profile: ClassVar[str] = "gaussian"
+
+    rate: float
+    x: float
+    y: float
+    fwhm: float
+
+    def sample_positions(self, rng, n):
+        return _sample_gaussian(
+            rng,
+            self.x,
+            self.y,
+            n,
+            self.fwhm,
+        )
+
+
+@dataclass(frozen=True)
+class ExponentialGalaxy:
+    """
+    Elliptical exponential galaxy.
+
+    Photons are sampled from a two-dimensional exponential surface
+    brightness profile with elliptical isophotes.
+
+    Parameters
+    ----------
+    rate : float
+        Source count rate in counts per second.
+
+    x, y : float
+        Detector coordinates of the galaxy centre in detector pixels.
+
+    r0 : float
+        Exponential scale length in detector pixels.
+
+    q : float
+        Axis ratio (minor axis / major axis).
+
+    pa : float
+        Position angle in radians, measured counter-clockwise.
+    """
+
+    profile: ClassVar[str] = "elliptical_exp_disk"
+
+    rate: float
+    x: float
+    y: float
+    r0: float
+    q: float
+    pa: float
+
+    def sample_positions(self, rng, n):
+        return _sample_elliptical_exp_disk(
+            rng,
+            n,
+            self.x,
+            self.y,
+            self.r0,
+            self.q,
+            self.pa,
+        )
+
+
+@dataclass(frozen=True)
+class UniformDisk:
+    """
+    Uniform circular source.
+
+    Photons are sampled uniformly within a circular disk.
+
+    Parameters
+    ----------
+    rate : float
+        Source count rate in counts per second.
+
+    x, y : float
+        Detector coordinates of the disk centre in detector pixels.
+
+    radius : float
+        Disk radius in detector pixels.
+    """
+
+    profile: ClassVar[str] = "uniform_disk"
+
+    rate: float
+    x: float
+    y: float
+    radius: float
+
+    def sample_positions(self, rng, n):
+        return _sample_uniform_disk(
+            rng,
+            n,
+            self.x,
+            self.y,
+            self.radius,
+        )
+
+
+Source: TypeAlias = GaussianSource | ExponentialGalaxy | UniformDisk
+
+
+def generate_sources(n_sources, rate, fwhm, x0, y0, radius, rng):
+    """
+    Generate a random distribution of Gaussian point sources.
+
+    Source positions are sampled uniformly within a circular region.
+
+    Parameters
+    ----------
+    n_sources : int
+        Number of sources to generate.
+
+    rate : float
+        Count rate assigned to every source.
+
+    fwhm : float
+        Gaussian FWHM in detector pixels.
+
+    x0, y0 : float
+        Centre of the generation region.
+
+    radius : float
+        Radius of the generation region in detector pixels.
+
+    rng : numpy.random.Generator
+        Random number generator.
+
+    Returns
+    -------
+    list of GaussianSource
+        Generated Gaussian source models.
+    """
+    sources = []
+
+    x_positions, y_positions = _sample_uniform_disk(rng, n_sources, x0, y0, radius)
+
+    for x, y in zip(x_positions, y_positions):
+        sources.append(
+            GaussianSource(
+                rate=rate,
+                x=x,
+                y=y,
+                fwhm=fwhm,
+            )
+        )
+
+    return sources
+
+
+def generate_galaxies(
+    n_sources,
+    rate,
+    r0,
+    x0,
+    y0,
+    radius,
+    rng,
+    axis_ratio_low=0.4,
+    axis_ratio_high=1.0,
+    orientation_low=0 * np.pi,
+    orientation_high=2 * np.pi,
+):
+    """
+    Generate a random distribution of elliptical exponential galaxies.
+
+    Galaxy centres are sampled uniformly within a circular region. Each
+    galaxy is assigned a random axis ratio and position angle drawn from
+    the specified ranges.
+
+    Parameters
+    ----------
+    n_sources : int
+        Number of galaxies to generate.
+
+    rate : float
+        Count rate assigned to every galaxy.
+
+    r0 : float
+        Exponential scale length in detector pixels.
+
+    x0, y0 : float
+        Centre of the generation region.
+
+    radius : float
+        Radius of the generation region in detector pixels.
+
+    rng : numpy.random.Generator
+        Random number generator.
+
+    axis_ratio_low, axis_ratio_high : float, optional
+        Lower and upper limits for the galaxy axis ratio.
+
+    orientation_low, orientation_high : float, optional
+        Lower and upper limits for the position angle in radians.
+
+    Returns
+    -------
+    list of ExponentialGalaxy
+        Generated galaxy models.
+    """
+
+    galaxies = []
+
+    x_positions, y_positions = _sample_uniform_disk(rng, n_sources, x0, y0, radius)
+
+    for x, y in zip(x_positions, y_positions):
+
+        q = rng.uniform(axis_ratio_low, axis_ratio_high)  # axis ratio
+        pa = rng.uniform(orientation_low, orientation_high)  # random orientation
+
+        galaxies.append(
+            ExponentialGalaxy(
+                rate=rate,
+                x=x,
+                y=y,
+                r0=r0,
+                q=q,
+                pa=pa,
+            )
+        )
+
+    return galaxies
+
+
+def simulate_events(
+    exposure: float,
+    sources: list[Source],
+    detector: Detector,
+    rng=None,
+    drift: Drift | None = None,
+):
+    """
+    Simulate a UVIT-like photon event list from a set of astrophysical
+    sources.
+
+    This function generates a list of photon events (time, detector X,
+    detector Y) for a given exposure. Each source contributes photons
+    according to a Poisson process with mean rate ``rate × exposure``.
+    Photon arrival times are assigned to detector frames and converted
+    to seconds using the detector frame rate.
+
+    Source spatial distributions are determined by the specified source
+    models. The resulting events are clipped to the detector boundaries
+    and sorted by time.
+
+    Parameters
+    ----------
+    exposure : float
+        Exposure time in seconds.
+
+    sources : list of Source
+        Source models to simulate.
+
+    detector : Detector, optional
+        Detector configuration. If not specified, the default UVIT
+        detector configuration is used.
+
+    rng : numpy.random.Generator, optional
+        Random number generator. If not provided, a new generator is
+        created.
+
+    drift : Drift, optional
+        Pointing drift model applied during the simulation.
+
+    Returns
+    -------
+    times, x, y : ndarray
+        Arrays containing the photon arrival times and detector
+        coordinates.
+
+    Raises
+    ------
+    ValueError
+        If no photon events are generated.
+    """
+
+    if rng is None:
+        rng = np.random.default_rng()
+
+    if detector is None:
+        detector = Detector()
+
+    detector_size = detector.detector_size
+    frame_rate = detector.frame_rate
+
+    all_times = []
+    all_x = []
+    all_y = []
+
+    n_frames = int(exposure * frame_rate)
+
+    for src in sources:
+
+        n = rng.poisson(src.rate * exposure)
+        if n == 0:
+            continue
+
+        frame_indices = rng.integers(0, n_frames, size=n)
+        times = frame_indices / frame_rate
+
+        x, y = src.sample_positions(rng, n)
+
+        all_times.append(times)
+        all_x.append(x)
+        all_y.append(y)
+
+    if not all_times:
+        raise ValueError("No events generated.")
+
+    times = np.concatenate(all_times)
+    x = np.concatenate(all_x)
+    y = np.concatenate(all_y)
+
+    if drift is not None:
+
+        frame_index = np.clip(
+            (times * frame_rate).astype(int),
+            0,
+            len(drift.x_offset) - 1,
+        )
+
+        x += drift.x_offset[frame_index]
+        y += drift.y_offset[frame_index]
+
+    # Keep only detector-valid events
+    mask = (x >= 0) & (x < detector_size) & (y >= 0) & (y < detector_size)
+
+    times = times[mask]
+    x = x[mask]
+    y = y[mask]
+
+    # Sort by time
+    order = np.argsort(times)
+    times = times[order]
+    x = x[order]
+    y = y[order]
+
+    return times, x, y
+
+
+def create_truth_catalogue(sources: list[Source]):
+    """
+    Create a truth catalogue from a list of simulated sources.
+
+    The returned structured array contains the intrinsic properties of
+    every simulated source and can be written to a FITS table using
+    :func:`save_truth_catalogue`.
+
+    Parameters
+    ----------
+    sources : list of Source
+        Source models.
+
+    Returns
+    -------
+    numpy.ndarray
+        Structured NumPy array containing the source catalogue.
+    """
+    rows = []
+
+    for i, src in enumerate(sources):
+
+        rows.append(
+            (
+                i,
+                src.profile,
+                src.rate,
+                src.x,
+                src.y,
+                getattr(src, "fwhm", np.nan),
+                getattr(src, "r0", np.nan),
+                getattr(src, "q", np.nan),
+                getattr(src, "pa", np.nan),
+                getattr(src, "radius", np.nan),
+            )
+        )
+
+    dtype = [
+        ("ID", "i4"),
+        ("PROFILE", "U20"),
+        ("RATE", "f8"),
+        ("X", "f8"),
+        ("Y", "f8"),
+        ("FWHM", "f8"),
+        ("R0", "f8"),
+        ("Q", "f8"),
+        ("PA", "f8"),
+        ("RADIUS", "f8"),
+    ]
+
+    return np.array(rows, dtype=dtype)
+
+
+def save_truth_catalogue(truth, filename="truth_catalogue.fits"):
+    """
+    Save a truth catalogue to a FITS binary table.
+
+    Parameters
+    ----------
+    truth : numpy.ndarray
+        Structured array returned by :func:`create_truth_catalogue`.
+
+    filename : str, optional
+        Name of the output FITS file.
+    """
+    cols = []
+    for name in truth.dtype.names:
+        cols.append(
+            fits.Column(
+                name=name,
+                format=(
+                    "D"
+                    if truth.dtype[name].kind == "f"
+                    else "20A" if truth.dtype[name].kind == "U" else "J"
+                ),
+                array=truth[name],
+            )
+        )
+
+    hdu = fits.BinTableHDU.from_columns(cols, name="TRUTH")
+    hdu.writeto(filename, overwrite=True)
+
+
+def save_events_to_fits(times, x, y, filename="simulated_events.fits"):
+    """
+    Save a simulated event list to a FITS binary table.
+
+    The output table contains the photon arrival time and detector
+    coordinates for every simulated event.
+
+    Parameters
+    ----------
+    times, x, y : ndarray
+        Photon arrival times and detector coordinates.
+
+    filename : str, optional
+        Name of the output FITS file.
+    """
+    cols = [
+        fits.Column(name="TIME", format="D", array=times),
+        fits.Column(name="X_DET", format="D", array=x),
+        fits.Column(name="Y_DET", format="D", array=y),
+    ]
+
+    hdu = fits.BinTableHDU.from_columns(cols)
+    hdu.writeto(filename, overwrite=True)
+
+
+def make_image_from_events(
+    x, y, exposure, detector_size, filename="simulated_image.fits"
+):
+    """
+    Create a detector image from simulated events.
+
+    Events are binned into detector pixels and converted to a count-rate
+    image.
+
+    Parameters
+    ----------
+    x, y : ndarray
+        Detector coordinates of the simulated events.
+
+    exposure : float
+        Exposure time in seconds.
+
+    detector_size : int
+        Size of the detector image in pixels.
+
+    filename : str, optional
+        Name of the output FITS image.
+    """
+    ndarray, _, _ = np.histogram2d(
+        x, y, bins=detector_size, range=[[0, detector_size], [0, detector_size]]
+    )
+    count_rate_image = ndarray.T / exposure
+    fits.writeto(filename, count_rate_image, overwrite=True)
+
+
+def add_simulated_events_to_existing_list(
+    sim_time, sim_fx, sim_fy, frame_rate, existing_list, output_file
+):
+    """
+    Append simulated events to an existing UVIT Level-2 events list.
+
+    The simulated events are converted to the UVIT Level-2 events table
+    format, merged with the existing events, sorted by time, and written
+    to a new FITS file. This is useful for testing source detection,
+    photometry, and variability analysis software on realistic UVIT
+    datasets.
+
+    Parameters
+    ----------
+    sim_time : ndarray
+        Simulated photon arrival times in seconds.
+
+    sim_fx, sim_fy : ndarray
+        Detector coordinates of the simulated photons.
+
+    frame_rate : float
+        Detector frame rate in frames per second.
+
+    existing_list : str
+        Path to the input UVIT Level-2 events list.
+
+    output_file : str
+        Path to the output FITS file.
+    """
+    with fits.open(existing_list) as hdul:
+        events = hdul["EVENTS"].data
+
+        n_sim = len(sim_time)
+        new = np.zeros(n_sim, dtype=events.dtype)
+        t0 = events["Time"].min()
+
+        new["Time"] = t0 + sim_time
+        new["Fx"] = sim_fx
+        new["Fy"] = sim_fy
+        new["PacketSequence"] = 0
+        new["FrameCount"] = events["FrameCount"].min() + (sim_time * frame_rate).astype(
+            int
+        )
+        new["Max-Min"] = 0
+        new["Min"] = 0
+        new["BAD FLAG"] = 1
+        new["MULT PHOTON"] = 1
+        new["EFFECTIVE_NUM_PHOTONS"] = frame_rate
+        new["UVIT_MASTER_TIME"] = t0 + sim_time
+        new["Sky_RA"] = np.nan
+        new["Sky_DEC"] = np.nan
+        new["MJD_L2"] = (
+            events["MJD_L2"].min() + sim_time
+        )  # MJD_L2 is in seconds, legacy design choice.
+        new["Fx_astronomical"] = sim_fx
+        new["Fy_astronomical"] = sim_fy
+        new["Fx_original"] = np.nan
+        new["Fy_original"] = np.nan
+
+        combined = np.concatenate([events, new])
+        order = np.argsort(combined["Time"])
+        combined = combined[order]
+        hdul["EVENTS"].data = combined
+        hdul.writeto(output_file, overwrite=True)
+
+
+def _sample_gaussian(rng, x0, y0, n, fwhm):
+    sigma = fwhm * FWHM_TO_SIGMA
+    x = rng.normal(x0, sigma, n)
+    y = rng.normal(y0, sigma, n)
+    return x, y
+
+
+def _sample_elliptical_exp_disk(rng, n, x0, y0, r0, q, pa):
+    # Radial distribution: Gamma(k=2, theta=r0)
+    r = rng.gamma(shape=2.0, scale=r0, size=n)
+
+    theta = rng.uniform(0, 2 * np.pi, n)
+
+    # Elliptical coordinates before rotation
+    x_ell = r * np.cos(theta)
+    y_ell = r * np.sin(theta) * q
+
+    # Rotate by PA
+    cos_pa = np.cos(pa)
+    sin_pa = np.sin(pa)
+
+    x_rot = x_ell * cos_pa - y_ell * sin_pa
+    y_rot = x_ell * sin_pa + y_ell * cos_pa
+
+    x = x0 + x_rot
+    y = y0 + y_rot
+
+    return x, y
+
+
+def _sample_uniform_disk(rng, n, x0, y0, radius):
+    r = radius * np.sqrt(rng.uniform(0, 1, n))
+    theta = rng.uniform(0, 2 * np.pi, n)
+
+    x = x0 + r * np.cos(theta)
+    y = y0 + r * np.sin(theta)
+
+    return x, y

simulit-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: simulit
+Version: 0.1.0
+Summary: Simulate UVIT-like photon event lists from astrophysical source models
+Project-URL: Homepage, https://github.com/prajwel/simulit
+Project-URL: Issues, https://github.com/prajwel/simulit/issues
+Author-email: Prajwel Joseph <prajwel.pj@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: AstroSat,UVIT,astronomy,detector,event list,photon,simulation
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.9
+Requires-Dist: astropy
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# Simulit
+
+Simulit is a Python package for simulating UVIT-like photon event lists from astrophysical source models.
+
+It is designed for developing, testing, and validating software for source detection, photometry, variability analysis, PSF improvement, and other UVIT data analysis applications.
+
+Current source models include:
+
+- Gaussian point sources
+- Elliptical exponential galaxies
+- Uniform circular sources
+
+Simulit can also:
+
+- Generate detector images from simulated event lists
+- Create truth catalogues for validation and benchmarking
+- Inject simulated events into existing UVIT Level-2 event lists
+
+## Installation
+
+```bash
+pip install simulit
+```
+
+## Quick start
+
+```python
+import numpy as np
+import simulit as sm
+
+rng = np.random.default_rng(42)
+
+observation = sm.Observation(
+    exposure=2000,
+)
+
+centre = observation.detector.detector_size / 2
+
+sources = sm.generate_sources(
+    n_sources=100,
+    rate=0.1,
+    fwhm=1.2,
+    x0=centre,
+    y0=centre,
+    radius=2048,
+    rng=rng,
+)
+
+times, x, y = observation.simulate_events(
+    sources,
+    rng=rng,
+)
+
+truth = sm.create_truth_catalogue(sources)
+
+sm.save_events_to_fits(times, x, y)
+sm.save_truth_catalogue(truth)
+
+sm.make_image_from_events(
+    x,
+    y,
+    exposure=observation.exposure,
+    detector_size=observation.detector.detector_size,
+)
+```
+
+## Source models
+
+### GaussianSource
+
+A Gaussian point source.
+
+```python
+sm.GaussianSource(
+    rate=1.0,
+    x=2400,
+    y=2400,
+    fwhm=1.2,
+)
+```
+
+### ExponentialGalaxy
+
+An elliptical exponential galaxy with an exponential surface brightness profile.
+
+```python
+sm.ExponentialGalaxy(
+    rate=0.5,
+    x=2400,
+    y=2400,
+    r0=3.0,
+    q=0.7,
+    pa=np.pi / 4,
+)
+```
+
+### UniformDisk
+
+A uniformly illuminated circular source.
+
+```python
+sm.UniformDisk(
+    rate=5.0,
+    x=2400,
+    y=2400,
+    radius=200,
+)
+```
+
+## Observation
+
+An `Observation` combines
+
+- exposure time
+- detector configuration
+- optional pointing drift
+
+```python
+observation = sm.Observation(
+    exposure=2000,
+)
+```
+
+A pointing drift model can also be supplied.
+
+```python
+drift = sm.Drift(
+    x_offset=x_shift,
+    y_offset=y_shift,
+)
+
+observation = sm.Observation(
+    exposure=2000,
+    drift=drift,
+)
+```
+
+## Output products
+
+Simulit can generate
+
+- simulated photon event lists
+- detector images
+- truth catalogues
+
+It can also append simulated events to an existing UVIT Level-2 event list, enabling realistic testing of UVIT analysis software.
+
+## Examples
+
+The `examples/` directory contains complete working examples.
+
+- `mixed_sources.py` — mixed populations of point sources, galaxies, and diffuse background
+- `synthetic_drift.py` — simulate observations with synthetic UVIT-inspired pointing drift
+
+## Planned features
+
+Future development is expected to include:
+
+- additional source models
+- realistic background models
+- cosmic ray simulations
+- detector artefacts
+- UVIT slitless spectroscopy
+- filter-dependent simulations
+- additional validation datasets

simulit-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+simulit/__init__.py,sha256=lcHIc4CkaRHtj_atip4RrtBo3rNPCUWBKMoyFzkbeZI,740
+simulit/simulit.py,sha256=Wwg94flZO9vO1wVBlM28O_2pLAGYh7udBZa1Akbw79o,17231
+simulit-0.1.0.dist-info/METADATA,sha256=xZJ7w46Nj79-G7OUrVjrXLovnm0D_dbKJVJq_1jeYPU,3739
+simulit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+simulit-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+simulit-0.1.0.dist-info/RECORD,,

simulit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

simulit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.