diff --git a/.gitignore b/.gitignore index 944df7b..b6f5f17 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,11 @@ node_modules # Sphinx documentation docs/_build/ +# Pycache Untracked Files +__pycache__/ +*.pyc + + # Jupyter Notebook .ipynb_checkpoints diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..f5871e7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,19 @@ +import os +import sys +sys.path.insert(0, os.path.abspath('../src')) + +project = 'SCARR' +author = 'decryptofy' +release = '0.1' + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx.ext.napoleon', +] + +templates_path = ['_templates'] +exclude_patterns = [] + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..13bb3aa --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +.. SCARR documentation master file + +Welcome to SCARR's documentation! +================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + modules + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..28c25e4 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +SCARR Modules +============= + +.. automodule:: scarr.filters.normalize + :members: + :undoc-members: + :show-inheritance: diff --git a/pyproject.toml b/pyproject.toml index e2c9d5e..3897f24 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,6 +35,9 @@ classifiers = [ "Homepage" = "https://github.com/decryptofy/scarr" "Bug Tracker" = "https://github.com/decryptofy/scarr/issues" +[project.optional-dependencies] +dev = ["sphinx"] + [tool.autopep8] ignore = "E501,W6" # or ["E501", "W6"] in-place = true diff --git a/src/scarr/filters/normalize.py b/src/scarr/filters/normalize.py index 158cc8f..156af65 100644 --- a/src/scarr/filters/normalize.py +++ b/src/scarr/filters/normalize.py @@ -10,16 +10,53 @@ from ..engines.stats import Stats class Normalize(Filter): - def __init__(self, stats:Stats) -> None: + """ + A normalization filter that standardizes trace data using precomputed tile statistics. + + This filter uses the mean and variance for a specific tile, obtained from the Stats object, + to normalize side-channel trace data to zero mean and unit variance. + """ + + def __init__(self, stats: Stats) -> None: + """ + Initialize the Normalize filter with global tile statistics. + + Parameters + ---------- + stats : Stats + A Stats object that provides tile-level means, variances, and coordinate mappings. + """ self.tile_means = stats.get_means() self.tile_variances = stats.get_variances() self.tiles = stats.get_tiles() def configure(self, tile_x, tile_y): + """ + Select and configure the tile statistics for a specific (x, y) tile. + + Parameters + ---------- + tile_x : int + X-coordinate of the tile. + tile_y : int + Y-coordinate of the tile. + """ tile_index = self.tiles.index((tile_x, tile_y)) - self.mean = self.tile_means[tile_index,:] - self.variance = self.tile_variances[tile_index,:] + self.mean = self.tile_means[tile_index, :] + self.variance = self.tile_variances[tile_index, :] + + def filter(self, traces: np.ndarray): + """ + Apply normalization to a batch of traces using the configured tile statistics. - def filter(self, traces:np.ndarray): + Parameters + ---------- + traces : np.ndarray + A NumPy array of raw side-channel traces to normalize. - return (traces - self.mean) / self.variance \ No newline at end of file + Returns + ------- + np.ndarray + Normalized traces with zero mean and unit variance. + """ + return (traces - self.mean) / self.variance