specula 0.0.0__tar.gz

specula-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FabioRossiArcetri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

specula-0.0.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: specula
+Version: 0.0.0
+Summary: PYramid Simulator Software for Adaptive OpTics Arcetri
+Author: Alfio Puglisi, Guido Agapito, INAF Arcetri Adaptive Optics group
+Author-email: Fabio Rossi <fabio.rossi@inaf.it>
+License-Expression: MIT
+Keywords: Adaptive Optics,Astrophysics,INAF,Arcetri
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: astropy
+Requires-Dist: matplotlib
+Requires-Dist: symao>=1.0.1
+Requires-Dist: astro-seeing>=1.1
+Requires-Dist: flask-socketio
+Requires-Dist: python-socketio
+Requires-Dist: requests
+Requires-Dist: pytest
+Requires-Dist: scikit-image
+Provides-Extra: control
+Requires-Dist: iircontrol; extra == "control"
+Dynamic: license-file
+
+# SPECULA
+Python AO end-to-end simulator
+
+SPECULA is a Python-based, object-oriented software derived from [PASSATA](https://arxiv.org/abs/1607.07624) and developed
+by the Adaptive Optics group at the Arcetri Observatory for end-to-end Monte-Carlo simulations of adaptive optics systems.
+It can be accelerated using GPU-CUDA via CuPy.
+
+See the documentation here: [specula.readthedocs.io](https://specula.readthedocs.io/en/latest/)
+
+## Directories
+
+- **docs**: contains the documentation.
+- **main**: contains functions and parameter files to calibrate and run a closed loop of an adaptive optics system (single-conjugated, multi-conjugated, natural, laser, ...).
+- **specula**: the main library, structured as follows:
+  - **data_objects**: classes that wrap the data and provide methods to access them.
+  - **display**: classes for data visualization.
+  - **lib**: utility functions used by multiple objects.
+  - **processing_objects**: classes that model the simulation elements as a function of inputs and time.
+  - **scripts**: various scripts.
+- **test**: contains functions to test SPECULA using the `unittest` framework.
+
+## Requirements
+
+- Python 3.8+
+- numpy
+- scipy
+- matplotlib
+- flask
+- flask-socketio
+- socketio
+- scikit-image (for physical propagation)
+- cupy (for GPU acceleration, optional)
+
+### Optional libraries
+
+Some features require additional libraries:
+- **pycairo**: needed for block diagram generation with orthogram
+- **orthogram**: for automatic block diagram creation (see [orthogram](https://pypi.org/project/orthogram/))
+- **control**: for conversion of transfer function system in SPECULA format and vice-versa and analysis of transfer function
+
+Install optional dependencies (pycairo will be installed as dependency of orthogram) with:
+```bash
+pip install orthogram
+pip install control
+```
+
+## Contributing to SPECULA
+To contribute to SPECULA, follow these steps:
+
+1. Fork this repository.
+2. Create a branch: `git checkout -b <branch_name>`
+3. Make your changes and **add tests for the new functionality.**
+4. Commit your changes: `git commit -m '<commit_message>'`
+5. Push to the branch: `git push`
+6. Create the pull request.
+
+We require tests for all new features to ensure the stability of the project.

specula-0.0.0/README.md

@@ -0,0 +1,57 @@
+# SPECULA
+Python AO end-to-end simulator
+
+SPECULA is a Python-based, object-oriented software derived from [PASSATA](https://arxiv.org/abs/1607.07624) and developed
+by the Adaptive Optics group at the Arcetri Observatory for end-to-end Monte-Carlo simulations of adaptive optics systems.
+It can be accelerated using GPU-CUDA via CuPy.
+
+See the documentation here: [specula.readthedocs.io](https://specula.readthedocs.io/en/latest/)
+
+## Directories
+
+- **docs**: contains the documentation.
+- **main**: contains functions and parameter files to calibrate and run a closed loop of an adaptive optics system (single-conjugated, multi-conjugated, natural, laser, ...).
+- **specula**: the main library, structured as follows:
+  - **data_objects**: classes that wrap the data and provide methods to access them.
+  - **display**: classes for data visualization.
+  - **lib**: utility functions used by multiple objects.
+  - **processing_objects**: classes that model the simulation elements as a function of inputs and time.
+  - **scripts**: various scripts.
+- **test**: contains functions to test SPECULA using the `unittest` framework.
+
+## Requirements
+
+- Python 3.8+
+- numpy
+- scipy
+- matplotlib
+- flask
+- flask-socketio
+- socketio
+- scikit-image (for physical propagation)
+- cupy (for GPU acceleration, optional)
+
+### Optional libraries
+
+Some features require additional libraries:
+- **pycairo**: needed for block diagram generation with orthogram
+- **orthogram**: for automatic block diagram creation (see [orthogram](https://pypi.org/project/orthogram/))
+- **control**: for conversion of transfer function system in SPECULA format and vice-versa and analysis of transfer function
+
+Install optional dependencies (pycairo will be installed as dependency of orthogram) with:
+```bash
+pip install orthogram
+pip install control
+```
+
+## Contributing to SPECULA
+To contribute to SPECULA, follow these steps:
+
+1. Fork this repository.
+2. Create a branch: `git checkout -b <branch_name>`
+3. Make your changes and **add tests for the new functionality.**
+4. Commit your changes: `git commit -m '<commit_message>'`
+5. Push to the branch: `git push`
+6. Create the pull request.
+
+We require tests for all new features to ensure the stability of the project.

specula-0.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "specula"
+description = "PYramid Simulator Software for Adaptive OpTics Arcetri"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+
+authors = [
+    { name = "Fabio Rossi", email = "fabio.rossi@inaf.it" },
+    { name = "Alfio Puglisi" },
+    { name = "Guido Agapito" },
+    { name = "INAF Arcetri Adaptive Optics group" }
+]
+keywords = ["Adaptive Optics", "Astrophysics", "INAF", "Arcetri"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+]
+
+# IMPORTANT: version must now be declared explicitly or dynamically
+dynamic = ["version", "dependencies"]
+
+[project.scripts]
+specula_frontend_start = "specula.scripts.web_frontend:start"
+specula_frontend_stop = "specula.scripts.web_frontend:stop"
+specula = "specula.scripts.specula_main:main"
+
+[tool.setuptools]
+packages = [
+    "specula",
+    "specula.data_objects",
+    "specula.processing_objects"
+]
+include-package-data = true
+
+[tool.setuptools.dynamic]
+dependencies = { file = "requirements.txt" }
+
+[project.optional-dependencies]
+control = ["iircontrol"]
+
+[tool.setuptools_scm]
+write_to = "specula/_version.py"
+

specula-0.0.0/requirements.txt

@@ -0,0 +1,11 @@
+numpy
+scipy
+astropy
+matplotlib
+symao >= 1.0.1
+astro-seeing>=1.1
+flask-socketio
+python-socketio
+requests
+pytest
+scikit-image

specula-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

specula-0.0.0/specula/__init__.py

@@ -0,0 +1,282 @@
+import numpy as np
+import os
+import functools
+from functools import wraps
+
+cpu_float_dtype_list = [np.float64, np.float32]
+cpu_complex_dtype_list = [np.complex128, np.complex64]
+array_types = []
+
+gpuEnabled = False
+cp = None
+xp = None
+global_precision = None
+float_dtype_list = None
+complex_dtype_list = None
+gpu_float_dtype_list = cpu_float_dtype_list
+gpu_complex_dtype_list = cpu_complex_dtype_list
+float_dtype = None
+complex_dtype = None
+default_target_device_idx = None
+default_target_device = None
+process_comm = None
+process_rank = None
+ASEC2RAD = np.pi / (3600 * 180)
+RAD2ASEC = 1.0 / ASEC2RAD
+MPI_DBG = False
+
+MPI_SEND_DBG = False
+
+# precision = 0 -> double precision
+# precision = 1 -> single precision
+
+# target_device = -1 -> CPU
+# target_device = i>-1 -> GPUi
+
+# you might have a GPU working and cupy installed
+# and still want to use the CPU (idx==-1) as default_target_device
+# in this case you might still want to allocate some objects on
+# a GPU device (idx>=0).
+# This can be checked later looking at the  value of gpuEnabled.
+
+def init(device_idx=-1, precision=0, rank=None, comm=None, mpi_dbg=False):
+    global xp
+    global cp
+    global gpuEnabled
+    global global_precision
+    global float_dtype_list
+    global complex_dtype_list
+    global gpu_float_dtype_list
+    global gpu_complex_dtype_list
+    global array_types
+    global float_dtype
+    global complex_dtype
+    global default_target_device_idx
+    global default_target_device
+    global process_comm
+    global process_rank
+    global MPI_DBG
+    
+    MPI_DBG = mpi_dbg
+    process_comm = comm
+    process_rank = rank
+
+    default_target_device_idx = device_idx
+    systemDisable = os.environ.get('SPECULA_DISABLE_GPU', 'FALSE')
+    if systemDisable=='FALSE':
+        try:
+            import cupy as cp
+            print("Cupy import successfull. Installed version is:", cp.__version__)
+            gpuEnabled = True
+            cp = cp
+        except:
+            print("Cupy import failed. SPECULA will fall back to CPU use.")
+            cp = None
+            xp = np
+            default_target_device_idx=-1
+    else:
+        print("env variable SPECULA_DISABLE_GPU prevents using the GPU.")
+        cp = None
+        xp = np
+        default_target_device_idx=-1
+
+
+    if default_target_device_idx>=0:
+        xp = cp
+        gpu_float_dtype_list = [cp.float64, cp.float32]
+        gpu_complex_dtype_list = [cp.complex128, cp.complex64]
+        default_target_device = cp.cuda.Device(default_target_device_idx)
+        default_target_device.use()
+        print('Default device is GPU number ', default_target_device_idx)
+        # print('Using device: ', cp.cuda.runtime.getDeviceProperties(default_target_device)['name'])
+        # attributes = default_target_device.attributes
+        # properties = cp.cuda.runtime.getDeviceProperties(default_target_device)
+        # print('Number of multiprocessors:', attributes['MultiProcessorCount'])
+        # print('Global memory size (GB):', properties['totalGlobalMem'] / (1024**3))
+    else:
+        print('Default device is CPU')
+        xp = np
+
+    if cp is not None:
+        array_types = [np.ndarray, cp.ndarray]
+    else:
+        array_types = [np.ndarray]
+
+    float_dtype_list = [xp.float64, xp.float32]
+    complex_dtype_list = [xp.complex128, xp.complex64]
+    global_precision = precision
+    float_dtype = float_dtype_list[global_precision]
+    complex_dtype = complex_dtype_list[global_precision]
+    
+    # Patch cupy's missing RandomState.random() method
+    if cp is not None:
+        cp.random.RandomState.random = cp.random.RandomState.random_sample
+
+
+# should be used as less as a possible and preferably outside time critical computations
+def cpuArray(v, dtype=None, force_copy=False):
+    return to_xp(np, v, dtype=dtype, force_copy=force_copy)
+
+
+def to_xp(xp, v, dtype=None, force_copy=False):
+    '''
+    Make sure that v is allocated as an array on this object's device.
+    Works for all combinations of np and cp, whether installed or not.
+
+    Optionally casts to the required dtype (no copy is made if
+    the dtype is already the correct one)
+
+    The main trigger for this function is that np.array() cannot
+    be used on a cupy array.
+    '''
+    if xp is cp:
+        if isinstance(v, cp.ndarray) and not force_copy:
+            retval =  v
+        else:
+            retval =  cp.array(v)
+    else:
+        if cp is not None and isinstance(v, cp.ndarray):
+            retval = v.get()
+        elif isinstance(v, np.ndarray) and not force_copy:
+            # Avoid extra copy (enabled by numpy default)
+            retval = v
+        else:
+            retval = np.array(v)
+    if dtype is None and not force_copy:
+        return retval
+    else:
+        return retval.astype(dtype, copy=force_copy)
+
+
+class DummyDecoratorAndContextManager():
+    def __init__(self):
+        pass
+    def __enter__(self):
+        pass
+    def __exit__(self, *args):
+        pass
+    def __call__(self, f):
+        def caller(*args, **kwargs):
+            return f(*args, **kwargs)
+        return caller
+
+
+def show_in_profiler(message=None, color_id=None, argb_color=None, sync=False):
+    '''
+    Decorator to allow using cupy's TimeRangeDecorator
+    in a safe way even when cupy is not installed
+    Parameters are the same as TimeRangeDecorator
+    '''
+    try:
+        from cupyx.profiler import time_range
+
+        return time_range(message=message,
+                          color_id=color_id,
+                          argb_color=argb_color,
+                          sync=sync)
+
+    except ImportError:
+        return DummyDecoratorAndContextManager()
+
+
+def fuse(kernel_name=None):
+    '''
+    Replacement of cupy.fuse() allowing runtime
+    dispatch to cupy or numpy.
+    
+    Fused function takes an xp argument that will
+    cause it to run as a fused kernel or a standard
+    numpy function. The xp argument can be used
+    inside the function as usual.
+
+    Parameters are the same as cp.fuse()
+    '''
+    def decorator(f):
+        f_cp = functools.partial(f, xp=cp)
+        f_np = functools.partial(f, xp=np)
+        f_cpu = f_np
+        if cp:
+            f_gpu = cp.fuse(kernel_name=kernel_name)(f_cp)
+        else:
+            f_gpu = None
+        @wraps(f)
+        def wrapper(*args, xp, **kwargs):
+            if xp == cp:
+                return f_gpu(*args, **kwargs)
+            else:
+                return f_cpu(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def main_simul(yml_files: list,
+               nsimul = 1,
+               cpu: bool=False,
+               overrides: str=None,
+               target: int=0,
+               profile: bool=False,
+               mpi: bool=False,
+               mpidbg: bool=False,
+               stepping: bool=False,
+               diagram: bool=False,
+               diagram_title: str=None,
+               diagram_filename: str=None,
+               diagram_colors_on: bool=False):
+
+    if mpi:
+        try:
+            from mpi4py import MPI
+            from mpi4py.util import pkl5
+            print("mpi4py import successfull. Installed version is:", MPI.Get_version())
+        except ImportError:
+            print("mpi4py import failed.")
+            raise
+
+        comm = pkl5.Intracomm(MPI.COMM_WORLD)
+        rank = comm.Get_rank()
+        N = 10000000
+        datatype = MPI.FLOAT
+        num_bytes = N * (datatype.Pack_size(count=1, comm=comm) + MPI.BSEND_OVERHEAD)
+
+        print(f'MPI buffer size: {num_bytes/1024**2:.2f} MB')
+        attached_buf = bytearray(num_bytes)
+        MPI.Attach_buffer(attached_buf)
+    else:
+        rank = None
+        comm = None
+        
+    if cpu:
+        target_device_idx = -1
+    else:
+        target_device_idx = target
+
+    init(target_device_idx, precision=1, rank=rank, comm=comm, mpi_dbg=mpidbg)
+    from specula.simul import Simul
+
+    if profile:
+        import cProfile
+        import pstats
+        pr = cProfile.Profile()
+        pr.enable()
+
+    for simul_idx in range(nsimul):
+        print(yml_files)
+        Simul(*yml_files,
+            simul_idx=simul_idx,
+            overrides=overrides,
+            stepping=stepping,
+            diagram=diagram,
+            diagram_filename=diagram_filename,
+            diagram_title=diagram_title,
+            diagram_colors_on=diagram_colors_on
+        ).run()
+
+    if profile:
+        pr.disable
+        stats = pstats.Stats(pr).sort_stats("cumtime")
+        stats.print_stats(r"\((?!\_).*\)$", 200)
+        
+    if mpi:
+        MPI.Detach_buffer()
+
+

specula-0.0.0/specula/base_data_obj.py

@@ -0,0 +1,135 @@
+
+import warnings
+from copy import copy
+from functools import lru_cache
+
+from specula import cp, np, array_types
+from specula.base_time_obj import BaseTimeObj
+
+
+# We use lru_cache() instead of cache() for python 3.8 compatibility
+@lru_cache(maxsize=None)
+def get_properties(cls):
+    result = []
+    classlist = cls.__mro__
+    for cc in classlist:
+        result.extend([attr for attr, value in vars(cc).items() if isinstance(value, property) ]) 
+    return result
+
+
+class BaseDataObj(BaseTimeObj):
+    def __init__(self, target_device_idx=None, precision=None):
+        """
+        Initialize the base data object.
+
+        Parameters:
+        target_device_idx: int, optional
+            device to be targeted for data storage. Set to -1 for CPU,
+            to 0 for the first GPU device, 1 for the second GPU device, etc.
+        precision: int, optional
+            if None will use the global_precision, otherwise set to 0 for double, 1 for single
+        """
+        super().__init__(target_device_idx, precision)
+        self.generation_time = -1
+        self.tag = ''
+
+    def transferDataTo(self, destobj, force_reallocation=False):
+        '''
+        Copy CPU/GPU arrays into an existing data object:
+        iterate over all self attributes and, if a CPU or GPU array
+        is detected, copy data into *destobj* without reallocating.
+
+        Destination (CPU or GPU device) is inferred by *destobj.target_device_idx*,
+        which must be set correctly before calling this method.
+        '''
+        # Get a list of all attributes, but skip properties
+        pp = get_properties(type(self))
+        attr_list = [attr for attr in dir(self) if attr not in pp]       
+
+        for attr in attr_list:
+            self_attr = getattr(self, attr)
+            self_type = type(self_attr)
+            if self_type not in array_types:
+                continue
+
+            dest_attr = getattr(destobj, attr)
+            dest_type = type(dest_attr)
+
+            if dest_type not in array_types:
+                print(f'Warning: destination attribute is not a cupy/numpy array, forcing reallocation ({destobj}.{attr})')
+                force_reallocation = True
+
+            # Destination array had the correct type: perform in-place data copy
+            if not force_reallocation:
+                # Detect whether the array types are correct for all four cases:
+                # Device to CPU, CPU to device, device-to-device, and CPU-CPU. Also check whether
+                # the target_device_idx is set correctly for the destination object.
+                DtD = cp is not None and (self_type == cp.ndarray) and (dest_type == cp.ndarray) and destobj.target_device_idx >= 0
+                DtH = cp is not None and (self_type == cp.ndarray) and (dest_type == np.ndarray) and destobj.target_device_idx == -1
+                HtD = cp is not None and (self_type == np.ndarray) and (dest_type == cp.ndarray) and destobj.target_device_idx >= 0
+                HtH = (self_type == np.ndarray) and (dest_type == np.ndarray) and destobj.target_device_idx == -1
+                if DtD:
+                    # Performance warnings here are expected, because we might
+                    # trigger a peer-to-peer transfer between devices
+                    with warnings.catch_warnings():
+                        if self.PerformanceWarning:
+                            warnings.simplefilter("ignore", category=self.PerformanceWarning)
+                        try:
+                            dest_attr[:] = self_attr
+                        except:
+                            dest_attr = self_attr
+                elif DtH:
+                    # Do not set blocking=True for cupy 12.x compatibility.
+                    # Blocking is True by default in later versions anyway
+                    self_attr.get(out=dest_attr)
+                elif HtD:
+                    dest_attr.set(self_attr)
+                elif HtH:
+                    dest_attr[:] = self_attr
+                else:
+                    print(f'Warning: mismatch between target_device_idx and array allocation, forcing reallocation ({destobj}.{attr})')
+                    force_reallocation = True
+
+            # Otherwise, reallocate
+            if force_reallocation:
+                DtD = cp is not None and (self_type == cp.ndarray) and destobj.target_device_idx >= 0
+                DtH = cp is not None and (self_type == cp.ndarray) and destobj.target_device_idx == -1
+                HtD = (self_type == np.ndarray) and destobj.target_device_idx >= 0
+                HtH = (self_type == np.ndarray) and destobj.target_device_idx == -1
+
+                if DtD:
+                    # Performance warnings here are expected, because we might
+                    # trigger a peer-to-peer transfer between devices
+                    with warnings.catch_warnings():
+                        if self.PerformanceWarning:
+                            warnings.simplefilter("ignore", category=self.PerformanceWarning)
+                        setattr(destobj, attr, cp.asarray(self_attr))
+                if DtH:
+                    # Do not set blocking=True for cupy 12.x compatibility.
+                    # Blocking is True by default in later versions anyway
+                    setattr(destobj, attr, self_attr.get())
+                if HtD:
+                    setattr(destobj, attr, cp.asarray(self_attr))
+                if HtH:
+                    setattr(destobj, attr, np.asarray(self_attr))
+
+        destobj.generation_time = self.generation_time
+
+    def copyTo(self, target_device_idx):
+        '''
+        Duplicate a data object on another device,
+        alllocating all CPU/GPU arrays on the new device.
+        '''
+        if target_device_idx == self.target_device_idx:
+            return self
+        else:
+            cloned = copy(self)
+
+            if target_device_idx >= 0:
+                cloned.xp = cp
+            else:
+                cloned.xp = np
+            cloned.target_device_idx = target_device_idx
+
+            self.transferDataTo(cloned, force_reallocation=True)
+            return cloned