Merge pull request #13 from ssc-ai/r0.19.0

v0.19.0

Author: mixxen

HISTORY.md

@@ -1,6 +1,12 @@
 History
 =======
 
+0.19.0
+---------------------
+
+* Add lambertian sphere brightness model for objects. Set object key `model` `mode` to `lambertian_sphere` and set `albedo` and `size` (meters) parameters. For 2D simulations, `distance` (km) and `phase_angle` (degrees) parameters must also be specified.
+
+
 0.18.0
 ---------------------
 

Makefile

@@ -111,12 +111,12 @@ install: clean ## install the package to the active python3's site-packages
 	@echo  IMPORTANT: You may need to close and restart your shell after running "make install".
 
 docker: docs dist
-	docker build -t satsim:0.18.0 -t satsim:latest -f docker/ubuntu20.04_cuda11.2_py3.8.dockerfile .
+	docker build -t satsim:0.19.0 -t satsim:latest -f docker/ubuntu20.04_cuda11.2_py3.8.dockerfile .
 
 dind:
 	docker run --rm -it -v .:/workspace/ -w /workspace python:3.8-bullseye ./build.sh
-	docker build -t satsim:0.18.0-cuda11.2 -f docker/ubuntu20.04_cuda11.2_py3.8.dockerfile .
-	docker build -t satsim:0.18.0-cuda11.8 -t satsim:0.18.0 -t satsim:latest -f docker/ubuntu22.04_cuda11.8_py3.10.dockerfile .
+	docker build -t satsim:0.19.0-cuda11.2 -f docker/ubuntu20.04_cuda11.2_py3.8.dockerfile .
+	docker build -t satsim:0.19.0-cuda11.8 -t satsim:0.19.0 -t satsim:latest -f docker/ubuntu22.04_cuda11.8_py3.10.dockerfile .
 
 uninstall: clean
 	cat .install.log | xargs rm -rf

docker/ubuntu20.04_cuda11.2_py3.8.dockerfile

@@ -27,12 +27,12 @@ RUN pip3 --no-cache-dir install --upgrade pip setuptools
 RUN pip3 --no-cache-dir install tensorflow~=2.11.0
 
 # copy wheel file
-ENV SATSIM_VERSION='0.18.0'
-COPY dist/satsim-0.18.0-py2.py3-none-any.whl /tmp
+ENV SATSIM_VERSION='0.19.0'
+COPY dist/satsim-0.19.0-py2.py3-none-any.whl /tmp
 
 # install satsim wheel file together with jupyterlab so dependency compatibility are resolved
 RUN pip3 --no-cache-dir install \
-        tmp/satsim-0.18.0-py2.py3-none-any.whl \
+        tmp/satsim-0.19.0-py2.py3-none-any.whl \
         jupyterlab \
         scikit-learn \
         virtualenv

docker/ubuntu22.04_cuda11.8_py3.10.dockerfile

@@ -28,12 +28,12 @@ RUN pip3 --no-cache-dir install --upgrade pip setuptools
 RUN pip3 --no-cache-dir install tensorflow~=2.13.0
 
 # copy wheel file
-ENV SATSIM_VERSION='0.18.0'
-COPY dist/satsim-0.18.0-py2.py3-none-any.whl /tmp
+ENV SATSIM_VERSION='0.19.0'
+COPY dist/satsim-0.19.0-py2.py3-none-any.whl /tmp
 
 # install satsim wheel file together with jupyterlab so dependency compatibility are resolved
 RUN pip3 --no-cache-dir install \
-        tmp/satsim-0.18.0-py2.py3-none-any.whl \
+        tmp/satsim-0.19.0-py2.py3-none-any.whl \
         jupyterlab \
         scikit-learn \
         virtualenv

docs/api/satsim.geometry.rst

@@ -49,6 +49,14 @@ satsim.geometry.observation module
    :undoc-members:
    :show-inheritance:
 
+satsim.geometry.photometric module
+----------------------------------
+
+.. automodule:: satsim.geometry.photometric
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 satsim.geometry.random module
 -----------------------------
 

docs/api/satsim.util.rst

@@ -9,6 +9,14 @@ satsim.util package
 Submodules
 ----------
 
+satsim.util.python module
+-------------------------
+
+.. automodule:: satsim.util.python
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 satsim.util.system module
 -------------------------
 

docs/conf.py

@@ -58,16 +58,16 @@
 # the built documents.
 #
 # The short X.Y version.
-version = '0.18.0'
+version = '0.19.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.18.0'
+release = '0.19.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -98,7 +98,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['static']
+# html_static_path = ['static']
 
 
 # -- Options for HTMLHelp output ---------------------------------------

satsim/__init__.py

@@ -4,7 +4,7 @@
 
 __author__ = """Alex Cabello"""
 __email__ = 'alexander.cabello@algoritics.com'
-__version__ = '0.18.0'
+__version__ = '0.19.0'
 
 from .satsim import gen_images, gen_multi, image_generator
 from .config import load_json, load_yaml

satsim/generator/obs/breakup.py

@@ -20,21 +20,25 @@ def _rotation_from_vectors(v, local=np.array([[1,0,0], [0,1,0], [0,0,1]])):
     return M
 
 
-def _generate_random_mv(mv, scale, n, sigma=1.0):
-    ZP = 1.0
+def _generate_random_mv_or_size(mv_or_size, scale, n, sigma=1.0, brightness_model='mv'):
     # samples = np.abs(np.random.normal(0, sigma, n))
     samples = np.abs(np.random.lognormal(0, sigma, n))
-    samples = samples / np.sum(samples)
-    pe_target = mv_to_pe(ZP, mv)
-    pe_part = samples * pe_target
-    return pe_to_mv(ZP, pe_target * scale[0]), pe_to_mv(ZP, pe_part * scale[1])
+    samples = samples / np.sum(samples)  # normalize
+
+    if brightness_model == 'mv':
+        ZP = 1.0
+        pe_target = mv_to_pe(ZP, mv_or_size)
+        pe_part = samples * pe_target
+        return pe_to_mv(ZP, pe_target * scale[0]), pe_to_mv(ZP, pe_part * scale[1])
+    else:
+        return mv_or_size * scale[0], samples * mv_or_size * scale[1]
 
 
 def collision_from_tle(tle, collision_time, radius=37.5, K=0.5,
                        attack_angle='random', attack_velocity=None, attack_velocity_scale=1.0,
                        n=[100,100], target_mv_scale=[0.5, 2.0], rpo_mv_scale=[0.5, 2.0],
                        target_mv=12.0, rpo_mv=12.0, offset=[0.0, 0.0], collision_time_offset=0.0, variable_brightness=True,
-                       fragment_angle='random', scale_fragment_velocity=False):
+                       fragment_angle='random', scale_fragment_velocity=False, brightness_model='mv'):
     """Generates a two object collision configuration from the input `tle`.
 
     Args:
@@ -55,6 +59,7 @@ def collision_from_tle(tle, collision_time, radius=37.5, K=0.5,
         variable_brightness: `boolean`, if True randomly assign sine variable brightness between 0 to 1 hz. default=True
         fragment_angle: `string`, specified the fragment angle sampling. `random` or `linspace`. default=`random`
         scale_fragment_velocity: `boolean`, if True scale the fragment velocity by cosine of the exit velocity. default=`false`
+        brightness_model: `string`, the model to use for brightness calculations. valid options `mv`, `lambertian_sphere` default=`mv`
 
     Example usage in SatSim configuration::
 
@@ -109,10 +114,10 @@ def collision_from_tle(tle, collision_time, radius=37.5, K=0.5,
     collision_time = time.to_utc_list(t)
 
     # brightness calculations
-    target_mv_after, target_particles_mv = _generate_random_mv(target_mv, target_mv_scale, n[0], np.random.uniform(0.0,1.0))
+    target_mv_after, target_particles_mv = _generate_random_mv_or_size(target_mv, target_mv_scale, n[0], np.random.uniform(0.0,1.0), brightness_model=brightness_model)
 
     if rpo_mv is not None:
-        rpo_mv_after, rpo_particles_mv = _generate_random_mv(rpo_mv, rpo_mv_scale, n[1], np.random.uniform(0.0,1.0))
+        rpo_mv_after, rpo_particles_mv = _generate_random_mv_or_size(rpo_mv, rpo_mv_scale, n[1], np.random.uniform(0.0,1.0), brightness_model=brightness_model)
     else:
         rpo_mv_after, rpo_particles_mv = (None, [])
 
@@ -184,93 +189,133 @@ def collision_from_tle(tle, collision_time, radius=37.5, K=0.5,
     vv[ndiv2:,2] = np.abs(vv[ndiv2:,2])
     vv[ndiv2:,:] = M1.dot(vv[ndiv2:,:].T).T + velocity1
 
-    if variable_brightness is True:
-        def mv_func(mv_in):
-            return {
-                "$pipeline": [
-                    {
-                        "module": "satsim.pipeline",
-                        "function": "constant",
-                        "kwargs": {
-                            "value": mv_in
-                        }
-                    },
-                    {
-                        "module": "satsim.pipeline",
-                        "function": "sin_add",
-                        "kwargs": {
-                            "freq": np.random.normal(0, 1.0),
-                            "mag_scale": np.random.uniform(0, 7.0)
-                        }
-                    }
-                ]
-            }
-    else:
-        def mv_func(mv_in):
-            return mv_in
-
     obs = {
         "mode": "list",
         "list": [{
             "mode": "twobody",
             "position": list(position),
             "velocity": list(v),
             "epoch": collision_time,
-            "mv": mv_func(m),
             "offset": offset,
             "events": {
                 "create": collision_time
             }
         } for v, m in zip(vv, np.concatenate([target_particles_mv, rpo_particles_mv]))]
     }
 
+    target_obs = None
     if target_mv is not None:
-        obs['list'].append({
+        target_obs = {
             "mode": "twobody",
             "position": list(position),
             "velocity": list(velocity0),
             "epoch": collision_time,
-            "mv": target_mv,
             "offset": offset,
             "events": {
                 "update": [
                     {
                         "time": collision_time,
                         "values": {
-                            "mv": mv_func(target_mv_after)
                         }
                     }
                 ]
             }
-        })
+        }
+        obs['list'].append(target_obs)
 
+    rpo_obs = None
     if rpo_mv is not None:
-        obs['list'].append({
+        rpo_obs = {
             "mode": "twobody",
             "position": list(position),
             "velocity": list(velocity1),
             "epoch": collision_time,
-            "mv": rpo_mv,
             "offset": offset,
             "events": {
                 "update": [
                     {
                         "time": collision_time,
                         "values": {
-                            "mv": mv_func(rpo_mv_after)
                         }
                     }
                 ]
             }
-        })
+        }
+        obs['list'].append(rpo_obs)
+
+    if variable_brightness is True:
+        def mv_func(mv_in):
+            return {
+                "$pipeline": [
+                    {
+                        "module": "satsim.pipeline",
+                        "function": "constant",
+                        "kwargs": {
+                            "value": mv_in
+                        }
+                    },
+                    {
+                        "module": "satsim.pipeline",
+                        "function": "sin_add",
+                        "kwargs": {
+                            "freq": np.random.normal(0, 1.0),
+                            "mag_scale": np.random.uniform(0, 7.0)
+                        }
+                    }
+                ]
+            }
+    else:
+        def mv_func(mv_in):
+            return mv_in
+
+    if brightness_model == 'mv':
+
+        for i, m in enumerate(np.concatenate([target_particles_mv, rpo_particles_mv])):
+            obs['list'][i]['mv'] = mv_func(m)
+
+        if target_obs is not None:
+            target_obs['mv'] = mv_func(target_mv_after)
+            target_obs['events']['update'][-1]['values']['mv'] = mv_func(target_mv_after)
+        if rpo_obs is not None:
+            rpo_obs['mv'] = mv_func(rpo_mv_after)
+            rpo_obs['events']['update'][-1]['values']['mv'] = mv_func(rpo_mv_after)
+
+    else:
+        albedo = 0.3  # TODO: make this a parameter
+        for i, m in enumerate(np.concatenate([target_particles_mv, rpo_particles_mv])):
+            obs['list'][i]['model'] = {
+                'mode': brightness_model,
+                'albedo': albedo,
+                'size': m
+            }
+
+        if target_obs is not None:
+            target_obs['model'] = {
+                'mode': brightness_model,
+                'albedo': albedo,
+                'size': target_mv
+            }
+            target_obs['events']['update'][-1]['values']['model'] = {
+                'size': target_mv_after
+            }
+
+        if rpo_obs is not None:
+            rpo_obs['model'] = {
+                'mode': brightness_model,
+                'albedo': albedo,
+                'size': rpo_mv
+            }
+            rpo_obs['events']['update'][-1]['values']['model'] = {
+                'size': rpo_mv_after
+            }
 
     return obs
 
 
 def breakup_from_tle(tle, breakup_time, radius=37.5, breakup_velocity=108,
                      n=100, target_mv_scale=[0.5, 2.0], target_mv=12.0,
                      offset=[0.0, 0.0], breakup_time_offset=0.0,
-                     variable_brightness=True):
+                     variable_brightness=True, brightness_model='mv'):
     """Generates a breakup configuration from the input `tle`.
 
     Args:
@@ -283,6 +328,7 @@ def breakup_from_tle(tle, breakup_time, radius=37.5, breakup_velocity=108,
         offset: `array`, row column offset of target position on fpa in normalized coordinates. default=12
         breakup_time_offset: `float`, number of seconds to offset breakup time from `breakup`. default=[0,0]
         variable_brightness: `boolean`, if True randomly assign sine variable brightness between 0 to 1 hz. default=True
+        brightness_model: `string`, the model to use for brightness calculations. valid options `mv`, `lambertian_sphere` default=`mv`
 
     Example usage in SatSim configuration::
 
@@ -319,6 +365,6 @@ def breakup_from_tle(tle, breakup_time, radius=37.5, breakup_velocity=108,
                              attack_angle='random', attack_velocity=breakup_velocity, attack_velocity_scale=1.0,
                              n=n, target_mv_scale=target_mv_scale, rpo_mv_scale=None, target_mv=target_mv, rpo_mv=None,
                              offset=offset, collision_time_offset=breakup_time_offset, variable_brightness=variable_brightness,
-                             scale_fragment_velocity=False)
+                             scale_fragment_velocity=False, brightness_model=brightness_model)
 
     return obs