ScopeSim Targets#

Simplified, unified target description model for the ScopeSim observation simulation engine.

Getting started#

Installation#

Recommended way to install the package is to simply use pip:

pip install scopesim-targets

Basic usage#

In the most basic example, we will set up a simple point source and observe it with ScopeSim using METIS imaging mode:

from scopesim import Simulation
from scopesim_targets.point_source import Star

target = Star(
    position=(0, 0),
    spectrum="G2V",
    brightness=("K", 18)
)

simulation = Simulation("MICADO")
simulation(target.to_source())

Show code cell output

Hide code cell output

py.warnings - WARNING: /home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

astar.scopesim.commands.user_commands - WARNING: Package could not be found: /home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/tests/mocks/MORFEO

astar.bug_report - ERROR: Unhandled exception occured, see log file for details.
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/utils.py", line 900, in wrapper
    output = func(*args, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 178, in __init__
    self.update(**kwargs)
    ~~~~~~~~~~~^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 266, in update
    self.update(packages=[kwargs["use_instrument"]],
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                yamls=["default.yaml"])
                ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 275, in update
    self._load_yamls(kwargs.get("yamls", []))
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 243, in _load_yamls
    self._load_yaml_dict(yaml_dict)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 226, in _load_yaml_dict
    check_version(yaml_dict)
    ~~~~~~~~~~~~~^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 678, in check_version
    raise NotImplementedError(
    ...<3 lines>...
    )
NotImplementedError: The selected instrument package requires ScopeSim version 0.11.3, but version 0.11.2 is installed. Please update your ScopeSim installation by running 'pip install -U scopesim'.

astar.bug_report - ERROR: Python:
3.13.9 (main, Apr 27 2026, 16:56:59) [GCC 13.2.0]

Installed Python packages:
           anisocado: 0.5.0
         astar-utils: 0.5.3
             astropy: 7.2.0
      beautifulsoup4: 4.13.4
            docutils: 0.21.2
               httpx: 0.28.1
                lxml: 6.1.0
          matplotlib: 3.10.8
      more-itertools: 10.7.0
               numpy: 2.3.5
           packaging: 25.0
               pooch: 1.9.0
              pyyaml: 6.0.3
               scipy: 1.17.1
            scopesim: 0.11.2
       scopesim_data: 0.0.1a0
  scopesim_templates: could not be loaded.
         skycalc-ipy: 0.7.0
             synphot: 1.7.0
                tqdm: 4.67.1

Installed IRDB packages:
     MICADO: version number not available.
  Armazones: version number not available.
        ELT: version number not available.

Operating System info:
   System: Linux
  Release: 7.0.0-1004-aws
  Version: #4-Ubuntu SMP PREEMPT Mon Apr 13 13:14:24 UTC 2026
  Machine: x86_64

astar.bug_report - ERROR: Unhandled exception occured, see log file for details.
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/utils.py", line 900, in wrapper
    output = func(*args, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/scopesimple.py", line 120, in __init__
    cmds = UserCommands(use_instrument=instrument,
                        set_modes=mode, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/utils.py", line 900, in wrapper
    output = func(*args, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 178, in __init__
    self.update(**kwargs)
    ~~~~~~~~~~~^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 266, in update
    self.update(packages=[kwargs["use_instrument"]],
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                yamls=["default.yaml"])
                ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 275, in update
    self._load_yamls(kwargs.get("yamls", []))
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 243, in _load_yamls
    self._load_yaml_dict(yaml_dict)
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 226, in _load_yaml_dict
    check_version(yaml_dict)
    ~~~~~~~~~~~~~^^^^^^^^^^^
  File "/home/docs/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py", line 678, in check_version
    raise NotImplementedError(
    ...<3 lines>...
    )
NotImplementedError: The selected instrument package requires ScopeSim version 0.11.3, but version 0.11.2 is installed. Please update your ScopeSim installation by running 'pip install -U scopesim'.

astar.bug_report - ERROR: Python:
3.13.9 (main, Apr 27 2026, 16:56:59) [GCC 13.2.0]

Installed Python packages:
           anisocado: 0.5.0
         astar-utils: 0.5.3
             astropy: 7.2.0
      beautifulsoup4: 4.13.4
            docutils: 0.21.2
               httpx: 0.28.1
                lxml: 6.1.0
          matplotlib: 3.10.8
      more-itertools: 10.7.0
               numpy: 2.3.5
           packaging: 25.0
               pooch: 1.9.0
              pyyaml: 6.0.3
               scipy: 1.17.1
            scopesim: 0.11.2
       scopesim_data: 0.0.1a0
  scopesim_templates: could not be loaded.
         skycalc-ipy: 0.7.0
             synphot: 1.7.0
                tqdm: 4.67.1

Installed IRDB packages:
     MICADO: version number not available.
  Armazones: version number not available.
        ELT: version number not available.

Operating System info:
   System: Linux
  Release: 7.0.0-1004-aws
  Version: #4-Ubuntu SMP PREEMPT Mon Apr 13 13:14:24 UTC 2026
  Machine: x86_64

---------------------------------------------------------------------------
NotImplementedError                       Traceback (most recent call last)
Cell In[1], line 10
from scopesim_targets.point_source import Star
target = Star(
   position=(0, 0),
   spectrum="G2V",
   brightness=("K", 18)
)
---> 10 simulation = Simulation("MICADO")
simulation(target.to_source())

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/utils.py:900, in top_level_catch.<locals>.wrapper(*args, **kwargs)
@functools.wraps(func)
def wrapper(*args, **kwargs):
   try:
--> 900         output = func(*args, **kwargs)
   except Exception as err:
       # FIXME: This try-except should not be necessary, but
       # logger.exception has an issue in some versions.
       try:

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/scopesimple.py:120, in Simulation.__init__(self, instrument, mode, download_missing, **kwargs)
mode = always_iterable(mode)
# Don't save cmds as an attribute, because OpticalTrain (currently)
# creates a copy of that, so the actual "settings" are stored there
# anyway. If that ever changes, consider adapting this here...
--> 120 cmds = UserCommands(use_instrument=instrument,
                   set_modes=mode, **kwargs)
self.optical_train = OpticalTrain(cmds)

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/utils.py:900, in top_level_catch.<locals>.wrapper(*args, **kwargs)
@functools.wraps(func)
def wrapper(*args, **kwargs):
   try:
--> 900         output = func(*args, **kwargs)
   except Exception as err:
       # FIXME: This try-except should not be necessary, but
       # logger.exception has an issue in some versions.
       try:

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py:178, in UserCommands.__init__(self, *maps, **kwargs)
self.default_yamls = []
self.modes_dict = {}
--> 178 self.update(**kwargs)

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py:266, in UserCommands.update(self, other, **kwargs)
if "use_instrument" in kwargs:
   self.package_name = kwargs["use_instrument"]
--> 266     self.update(packages=[kwargs["use_instrument"]],
               yamls=["default.yaml"])
   # check_for_updates(self.package_name)
if "packages" in kwargs:

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py:275, in UserCommands.update(self, other, **kwargs)
if "packages" in kwargs:
   add_packages_to_rc_search(self["!SIM.file.local_packages_path"],
                             kwargs["packages"])
--> 275 self._load_yamls(kwargs.get("yamls", []))
if mode_yamls := kwargs.get("mode_yamls"):
   # Convert the yaml list of modes to a dict object
   # TODO: Why isn't this a dict with name as key to begin with???
   (...)    284     #       set_modes call, this gets called again, and now thows an
   #       error because the name key is no longer there.....
   self.modes_dict = {mode["name"]: mode for mode in mode_yamls}

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py:243, in UserCommands._load_yamls(self, yamls)
# recursive
for yaml_dict in yaml_dicts:
--> 243     self._load_yaml_dict(yaml_dict)
if yaml_input == "default.yaml":
   logger.debug("    setting default yaml")

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py:226, in UserCommands._load_yaml_dict(self, yaml_dict)
   if self.package_status == "experimental":
       # or rather warning?
       logger.info(
           "The selected instrument package is still in experimental "
           "stage, results may not be representative of physical "
           "instrument, use with care."
       )
--> 226     check_version(yaml_dict)
logger.debug("      dict yaml done")

File ~/checkouts/readthedocs.org/user_builds/scopesim-targets/envs/latest/lib/python3.13/site-packages/scopesim/commands/user_commands.py:678, in check_version(yaml_dict, mode)
if __version__ < needs_scopesim:
   msg = f"Mode {mode}" if mode else "The selected instrument package"
--> 678     raise NotImplementedError(
       f"{msg} requires ScopeSim version {needs_scopesim}, but version "
       f"{__version__} is installed. Please update your ScopeSim "
       "installation by running 'pip install -U scopesim'."
   )

NotImplementedError: The selected instrument package requires ScopeSim version 0.11.3, but version 0.11.2 is installed. Please update your ScopeSim installation by running 'pip install -U scopesim'.

img_slice = slice(462, 562)  # only show center of image
simulation.plot(img_slice=(img_slice, img_slice))

Contents#

API reference#

`scopesim_targets.target`	Contains main `Target` class.
`scopesim_targets.point_source`	Currently only `Star` and baseclass.
`scopesim_targets.extended_source`	Parametrized and discrete 2+1D and 3D target models.
`scopesim_targets.cluster`	Star cluster targets.
`scopesim_targets.spectral_classes`	Stellar parameters lookup table and related functionality.
`scopesim_targets.yaml_constructors`	Custom YAML class constructors (loading) and representations (dumping).
`scopesim_targets.data_utils`	Auxilliary functions for downloading and caching static data.
`scopesim_targets.plot_utils`	Plotting convenience functinality.
`scopesim_targets.typing_utils`	Custom composite types used in this package.
`scopesim_targets.stellar`	Point source stuff, e.g. populations and cluster.