Aspro2 Documentation

JMMC logo

ASPRO 2 Logo

ASPRO 2 User Manual

Date: Sep 17th 2024

Authors:

[!NOTE] Documentation updates in progress

Release history:

Show previous revisions: - ASPRO 2 version 24.03 (March 2024): Implemented advanced OIFITS simulator (GRAVITY_FT / GPAO NGS VIS support) - ASPRO 2 version 23.09 (September 2023): Implemented wavelength interpolation and extrapolation of user-defined models (FITS cube) - ASPRO 2 version 23.03 (March 2023): Added the new VLTI Extended configuration providing baselines up to 200m - ASPRO 2 version 22.12 (December 2022): Updated export OB section / removed old P2PP actions, add placeholder for the Targets's Table - ASPRO 2 version 22.03 (March 2022): Improved CHARA PoPs handling + added SAMP interoperability ('image.load.fits' import) - ASPRO 2 version 21.09 (September 2021): minor bug fixes - ASPRO 2 version 21.03 (March 2021): Updated noise modelling parameters for MATISSE + improved OIFITS generation (noisy observables) - ASPRO 2 version 20.03 (March 2020): Updated noise modelling parameters for MATISSE (GRA4MAT, high resolution) + ObsPortal integration to query raw VLTI observations - ASPRO 2 version 19.09 (September 2019): Fixed noise modelling parameters for MATISSE LM & N (matching the MATISSE ETC) + image apodization + many smaller improvements... - ASPRO 2 version 0.9.9.6 (March 2019): Improved AO setup (added VLTI CIAO + NAOMI) ... - ASPRO 2 version 0.9.9.5 (September 2018): Improved noise modelling for MATISSE, user models (scaling / rotation) and enhanced Target Editor (FT/AO/GUIDE groups) - ASPRO 2 version 0.9.9.4 (March 2018): Improved noise modelling for MATISSE (thermal background) - ASPRO 2 version 0.9.9.3 (September 2017): Added A2P2 (xml) integration and OIFits processor (CLI) - ASPRO 2 version 0.9.9.2 (March 2017): minor changes to OIFits viewer (consistent colors) and bug fixes - ASPRO 2 version 0.9.9.1 (September 2016): updated VLTI configuration for GRAVITY and MATISSE and improvements on the OIFits simulator - ASPRO 2 version 0.9.9 (March 2016): updated VLTI configuration (ESO telescope shadowing profiles, GRAVITY) and several improvements (mean atmosphere transmission, noise modelling and upgraded OIFits viewer) - ASPRO 2 version 0.9.8 (September 2015): updated VLTI configuration and several improvements (OB export, noise modelling) - ASPRO 2 version 0.9.7 (March 2015): updated VLTI & CHARA configuration and several minor changes - ASPRO 2 version 0.9.5 (September 2013): updated the embedded OIFits explorer (customizable plots), updated VLTI, CHARA VEGA configuration and bug fixes - ASPRO 2 version 0.9.4 (March 2013): added polychromatic user-defined model support (FITS cube) and many GUI changes - ASPRO 2 version 0.9.3 (October 2012): updated CHARA VEGA configuration and bug fixes - ASPRO 2 version 0.9.2 (September 2012): added moon avoidance, wind restriction, enhanced OIFits viewer - ASPRO 2 version 0.9.1 (June 2012): bug fixes and many minor changes (Simbad mirrors, Samp interoperability, configuration ...) - ASPRO 2 version 0.9.0 (March 2012): added user-defined model support (FITS image) - ASPRO 2 version 0.8.1 (September 2011): updated configuration (VLTI P89, CHARA VEGA and MIRC), added VIS2 plot - ASPRO 2 version 0.8 (March 2011): added multi configuration support to have an overview of UV coverages of one source observed with different configurations - ASPRO 2 version 0.7 (February 2011): added Target editor / calibrator support / interoperability with LITpro and SearchCal - ASPRO 2 version 0.6 (September 2010): added OIFits support - ASPRO 2 version 0.5 (June 2010): initial ASPRO2 public release

Here are the Release notes.

Table of contents

Description

This document will give general information on the new version of ASPRO named "ASPRO 2" to constitute the "ASPRO 2 User Manual".

ASPRO 2 is a Java standalone program that helps you to prepare observations on various optical interferometers.

Supported interferometers and instruments

Xml configuration files are provided as the ASPRO 2 Configuration package and evolve with releases.

Public ASPRO 2 configuration description is available:

Please give us your feedback if you want another interferometer or instrument to be supported or if you find mistakes in the configuration. We are trying to maintain the configuration as exact as possible, but it is really difficult to have the correct & up-to-date information about instruments ...

[!NOTE]

Main functionalities

Requirements

[!NOTE]

OpenJDK binary packages are available through several providers:

JavaWebStart (IcedTeaWeb) binary packages are available through several providers:

How to get and run ASPRO 2 ?

The easiest way consists in using the JMMC AppLauncher application which is able to run JMMC applications (Aspro 2, SearchCal, LITpro) and other VO tools when needed (relying on Java Web Start to start applications).

An internet connection is required to use Java Web Start and get the latest release: ASPRO 2.

Of course, both Java Web Start and ASPRO 2 support offline mode i.e. ASPRO 2 can work without any internet connection.

Once downloaded, you should have a shortcut icon "Aspro 2" on your desktop: ASPRO 2 Icon

Alternatively you can start it again later using the Java Web Start Viewer and click on "Aspro 2":

    javaws -viewer

If Java Web Start is not working properly on your environment or if ASPRO 2 needs more memory (1024m by default), you can download the ASPRO 2 (JAR file) and run ASPRO 2 using the following command:

    java -Xms1024m -Xmx4096m -jar Aspro2-Version.jar

where:

[!NOTE] Look at the memory monitor in the status bar to know how much memory is available (depending on the loaded user models) and potentially clean up memory (garbage collection) by clicking on the memory's progress bar.

Look at the JMMC Tools page and the Release page to see the complete list of JMMC tools with related links to news, release notes and FAQs...

[!NOTE] You can run multiple instances of ASPRO 2 at the same time, but it may be confusing when you want to use interoperability with other applications: take care of SAMP's client id reported in the title bar to properly identify the appropriate application instance.

Acknowledgement

If this software was helpful in your research, please add this sentence in the acknowledgement section of your articles, as it will support further development of new tools for interferometry:

    This research has made use of the Jean-Marie Mariotti Center
    \texttt{Aspro2} service \footnote{Available at http://www.jmmc.fr/aspro}.

ASPRO 2 depends on many open source libraries including these important astronomical / VO libraries:

The exhaustive list of open source libraries is available: view credits

Guided tour

How to run a simple preparation scenario ?

  1. Launch ASPRO 2
  2. Set the main observation settings (interferometer, instrument, configuration ...) and constraints (date ...)
  3. Enter your observation targets using the the Simbad star resolver
  4. Navigate among tab panels to see outputs and other options

To complete your observation preparation, you can:

Of course you can save your complete observation settings using the File menu / Save action to open it later using the File menu / Open observation action. Besides the File / Open Recent menu lists up to 10 recent observation settings to quickly open any of them.

[!NOTE]

Main observation settings

The main panel is always present at the top of the application window to let you define main observation settings: Main Panel

This panel is divided in four parts:

[!NOTE] Any change made to these fields will be taken into account immediately on plots

Target definition

To add a new target in the target list, the simplest way consist in typing its identifier (name) in the Simbad star resolver and press the Enter key to get its coordinates and other information using the CDS Simbad service.

An error can occur if the target identifier is not present in Simbad or if ASPRO 2 can not access to internet (proxy or firewall problems).

If Simbad returns multiple matches for a given identifier, the following error message is displayed:

Multiple objects found (please refine your query):
'uy': [ NAME UY Aur A, NAME UY Aur B ]

To add multiple targets at once, enter their identifiers separated by ';' (semicolon character) in the star resolver or copy / paste your target list (one identifier per line). Of course, the Simbad query takes more time to proceed then a summary of the query results is displayed.

[!NOTE]

If you are off line, you can enter manually a new target by giving its RA / DEC coordinates and an optional name using the following format:

    HH:MM:SS.ms [+/-]DD:MM:SS.ms [target name]
    04:00:00 -20:00:00 TEST

To avoid possible target duplicates (different identifiers used), a new target cannot be added to the target list if it contains a target within 5 arcseconds (angular separation). In such case, the following message is displayed:

Target [A](ra, dec) too close to Target [B ](ra, dec): ... arcsec.

[!NOTE] As a convention, we will use the terms "science target" [science target] and "calibrator target" [calibrator target] in this document. ASPRO 2 uses icons to represent this distinction in the graphical user interface and calibrator targets are displayed with the suffix "(cal)".

The target list contains both science targets and calibrator targets. It uses the following rules to order targets:

To flag a target as a calibrator target, click on the Editor button to open the Target Editor window and use the Targets tabbed pane or use SearchCal to find calibrators automatically.

To remove target(s) from the target list, select first the target(s) in the list, use the small "X" button and confirm the operation. If the selected target is a:

[!NOTE]

ASPRO 2 supports an object model per target in contrary to ASPRO. It defines either a simple analytical model to describe the geometry of the target composed of elementary models (punct, disk, ring ...) or an user-defined model based on one given FITS image.

To edit any object model of your targets, click on the Editor button to open the Target Editor window and use the Models tabbed pane.

Finally click on the sky button to open the JSkyCalc tool and synchronize your observation:

[!NOTE] you can use the Edit menu / Find action (Previous / Next) to find and select a target in the target list by matching patterns on its name

Main settings

This panel let you define your main settings:

Main Panel CHARA

Configuration(s)

This panel let you choose one or more base line configurations in the configuration list which contains only available baselines for the selected instrument (and period for VLTI or CHARA).

To select several configurations, use the Control key or Command key (mac) before clicking on one configuration.

[!NOTE] As a convention, we will use the terms "single configuration" when only one configuration is selected and "multi configuration" when more configurations are selected.

See the Multi configuration support topic for more information.

Constraints

The Night restriction check box is useful to use or not night limits in the observability computation for a particular observation date. If disabled, it gives the largest observability intervals to see when the target is observable during the year.

An observation Date must be defined to determine the coming astronomical night and twilight zones used by the observability computation. The date syntax uses the English format i.e. "YYYY/MM/DD".

For a given date, ASPRO2 determines the coming night range(s) in the [DD; DD+1] range; for example the given date '2014/4/4' corresponds to the night between April 4th and 5th.

The Minimum elevation must be given in degrees (45 degrees by default) to respect observation constraints on telescopes (at least 30 degrees).

Finally the Wind check box can be used during VLTI observations (on site) to define the wind direction used to determine the correct observability due to VLTI pointing restrictions.

[!NOTE]

Status indicator

The status (OK, Information or Warning) gives you the feedback on underlying computations: observability, UV coverage, OIFits data simulation and noise modelling. Pointing the Information or Warning indicator with your mouse displays a tooltip containing status messages:

[!NOTE] clicking on the status opens the ASPRO 2 Log Console which displays the complete history of status messages

Targets tab

This tab brings all target's informations through a table view. Targets can be sorted by any column (use shift to add a second column ordering).

Click in the bottom right corner to choose your colums of interest.

Future release will improve the way to select, filter and group targets.

Interferometer sketch (Map tab)

This zoomable plot shows the selected interferometer with all stations and selected baselines. Selected baselines are indicated with their lengths in the legend area.

Interferometer sketch

Observability tab

This zoomable plot shows the observability intervals per target expressed in LST, UTC or Local time for the chosen observation date.

A diamond mark indicates the transit of the target and graduation marks indicate the azimuth (on top: 0 means North, 90 means East...) and elevation (on bottom) of the target in degrees along the observability range.

If the night restriction is enabled, night and twilight zones for the chosen observation date are displayed in the background, used by the observability computation and the maximum FLI (Fractional Lunar Illumination) for this night is indicated in the chart title.

If your observation date corresponds to the current night, a red time line indicating the time is displayed and refreshed every minute.

Several plot options are available in this case:

[!NOTE] The default time reference (LST, UTC or Local), Center plot around night, Night only options and the Twilight used as night limit (astronomical, nautical or civil) can be defined in the Preferences Window.

Target observability takes into account:

[!NOTE] the impact of optional constraints (HA, moon avoidance and wind restriction) on the target observability is displayed using a translucent area and dotted outline.

Colors are automatically associated to targets and their meaning is described in the legend area: (Science / Calibrator or configuration).

The selected target in the main target list is represented highlighted using a gradient (white to 'color') and the observability plot is automatically updated when the selected target changes.

Observability plot

[!NOTE]

Show more details on the PoPs configuration and best PoPs algorithms:

ASPRO 2 finds the best PoPs combination for the complete target list when the PoPs text field is empty. The current PoPs combination is indicated in the Current label, in the plot title and in status indicator messages using the following format "Station(PoP number)...", as in the following image: Automatic PoPs"

You can use the PoPs combo box to list best PoP combinations followed by up to good PoP combinations (descending order) and select one to see its impact on the observability of your complete target list.

You can tell ASPRO 2 to use another PoPs combination by entering a valid PoPs code in the PoPs text widget ( "34" means PoP3 on S1 and PoP4 on S2), as in the following image: User PoPs

To compare observability between 6T and 5T configurations, please use the Fixed PoPs combo boxes (and the set / clear actions) to associate PoPs with stations in a stable manner:

The best PoPs algorithm has two different behaviour depending on your target list:

The best PoPs algorithm takes only into account (for performance reasons):

Finally, the best PoPs algorithm has several variants:

Both Transit and HALimits variants use a normal law estimator (mean, standard deviation).

Several options can be defined in the Preferences Window:

Show more details on the observability computation:

Observability detailed plot

The detailed observability plot shows each target multiple times (look at the legend area) to illustrate different aspects:

Show base line limits for the selected configuration:

BaseLine Limits plot

This plot is useful to see telescope shadowing restrictions for the selected baselines on the VLTI and also the zenithal restriction.

Show more details on the moon avoidance:

ASPRO 2 determine the moon separation with every target during the rise / set interval only.

Here are the rules for each interferometer:

On the following screen shot, the target ETA TAU is not observable because it is too close to the moon (~ 2.1 deg) at this particular date (2015/10/28).

Observability plot with moon avoidance

Show more details on entering the VLTI wind direction:

When the Wind check box is enabled (night restriction should be enabled first), the compass widget is also enabled to let you enter the wind direction represented by the red arrow.

Observability plot with wind pointing restrictions

On this screen shot, the wind direction is set to North - East (60 deg) and the target HD 1234 is impacted (telescopes can not be pointed to South - West).

Here is the detailed observability plot in this case when the Details check box is then enabled: Observability detailed plot with wind pointing restrictions

The observability interval related to Wind pointing restriction is represented in cyan color and is the limiting effect on the target HD 1234.

UV coverage tab

This zoomable plot shows the UV coverage for the target selected in the target list of the main panel.

An optional image of the target object model is displayed on the background which represents the amplitude, square amplitude, phase of the Fourier transform of the target model and its color scale (linear or logarithmic) is displayed on the left side. You can use the Add error noise to image in the Preferences Window to perform noise modelling (VIS or VIS2) and add error noise to the model image.

It can show UV tracks per base line given by the Rise / Set intervals only to see the largest elliptical paths supporting UV measurements.

UV measurements are represented by UV segments as the spectral resolution is simulated for the selected Instrument mode (wavelength range).

If your observation date corresponds to the current night, red segments indicating current UV measurements and the LST (or UTC) time are displayed and refreshed every minute.

These UV measurements are using the observability range of the target expressed in hour angle displayed near the HA min and HA max sliders and the Sampling Periodicity in minutes (default value depending on the chosen instrument). Besides, these hour angle fields are useful to adjust the starting and ending hour angles of the simulated observation.

Important actions:

On the following screen shot, the object model is an elliptical uniform disk which visibility amplitude is converted using a linear scale: 0.0 is indicated in black and the maximum (1.0 because fluxes are normalized) in white.

UV Coverage plot

[!NOTE]

On the left side, many options are proposed:

[!NOTE]

OIFits Viewer tab

The OIFits viewer uses an embedded OIFitsExplorer which provides several predefined but customizable plots showing the OIFits simulated data (VIS, VIS2, T3, FLUX) only if the target has an object model and the OIFits data computation is enabled on the UV coverage panel.

The Show combo box lists many predefined plots:

The Color by selector allows to color data points by effective wavelength, baseline or configuration (multi-configuration).

The Skip flag data checkbox is important to filter out simulated data having signal to noise ratio SNR < 3 (high uncertainty), that may occur at instrument wavelength boundaries. Ths threshold value (3 by default) can be set in the Preferences Window.

The Draw line checkbox allows to plot lines along the wavelength axis instead of data points to observe the spectral dispersion; if the x axis corresponds to EFF_WAVE (wavelength), then step lines are used to display histograms (spectra like).

To customize the plot axes, please use the [...] button to select the plotted axes / quantities (among OIFITS data columns) and define their ranges (auto / fixed) and many other options (log, include zero).

The plot includes error bars representing the error computed by the noise modelling.

There are 2 types of "noise" in Aspro2:

Data and errors are coming from the simulated OIFits file generated "on the fly" which can be exported using the File menu / Export to OIFits file action.

Vis2 / T3 plots with error bars

[!NOTE] If errors can not be computed by the noise modelling (missing target magnitudes...), data points are then represented using a triangle shape and of course, error bars are not displayed:

Vis2 / T3 plots without error bars

[!NOTE] To enable / disable the OIFits computation or error noise, look at the UV coverage panel. When an user-defined model is used (FITS image), OIFits data are computed using direct Fourier transform (not FFT) which can be slow (high resolution) but more precise at each UV point; however, if it is too slow, consider using the Fast mode (optimize the input image) in the Preferences Window or disable OIFits data computation when not absolutely needed in the UV coverage panel.

OIFits output

ASPRO 2 generates OIFITS (version 1) compliant files for the select target using the current observation setup with OI_VIS, OI_VIS2, OI_T3 and OI_FLUX tables. The OI_FLUX table (OIFITS version 2) gives the theoretical target's flux in photons (no atmosphere nor transmission loss, strehl).

To illustrate the bandwidth smearing effect of the instrumental spectral configuration, ASPRO 2 uses super sampling (3 samples by default) on the target model to compute complex visibilities for instrument modes having less than 100 spectral channels (large bandwith).

The noise modelling can estimate errors on OI_VIS, OI_VIS2, OI_T3 and OI_FLUX data based on object magnitudes and the current instrument configuration and observation setup (fringe tracker, adaptive optics...).

If a magnitude or flux is missing, errors can not be computed:

[!NOTE]

About VISAMP and VISPHI quantities in OI_VIS tables:

Instrument VISAMP type VISPHI type
AMBER differential differential
GRAVITY differential differential
MATISSE absolute differential

Noise modelling is based on the JMMC-MEM-2800-0001 - Noise model for interferometric combiners document.

In 2016, the noise modelling and the OIFITS data simulator has been improved for new VLTI instruments (GRAVITY & MATISSE) and this work has been described in the SPIE proceedings: L. Bourgès and G. Duvert, “ASPRO2: get ready for VLTI’s instruments GRAVITY and MATISSE”, Proc. SPIE 9907, Optical and Infrared Interferometry and Imaging V, 990711

Since ASPRO2 2024.03 noise modeling has been improved:

Noise modeling plots:

The relevant parameters for each instrument are described in: Latest Aspro Configuration

Get Information about past observations

Since ASPRO2 release 20.03, ASPRO2 can retrieve past observations logs from the JMMC ObsPortal service. It provides observations logs from the ESO archive (all VLTI instruments) with lots of details: observation setup (configuration, instrument mode), date & time, UV points & atmospheric conditions.

To get observation logs for a single target, first select the target and use the Edit menu / Get Observations (Selected) action. To get observations logs for all targets, use the Edit menu / Get Observations (All targets) action. Depending on the number of targets and the amount of downloaded data, this action can take a while.

If any past observation corresponds to the selected target, a data table will be displayed on the bottom of the main window showing the corresponding data.

To filter these data, the table panel provides (several) filters:

[!NOTE]

Observability plot

This plot shows the observability plot of the target 'DoAr 44'.

Past observation ranges of the GRAVITY instrument are displayed as an overlay in orange color: Aspro2-rawobs-obs.png

'V2062 Oph' and 'DoAr 44' are the same object in Simbad, even if the distance between the ASPRO2 target coordinates and the observation coordinates in the ESO archive is 8 as in this specific case.

[!NOTE] Tooltips are showing details about the pointed observation log.

UV Coverage plot

This plot shows the UV coverage of the target 'DoAr 44'. Past observation UV points of the GRAVITY instrument are displayed (in the background) in orange color: Aspro2-rawobs-uv.png

[!NOTE] Tooltips are showing details about the pointed observation log.

Multi configuration support

When several configurations are selected in the Configuration(s) list, ASPRO 2 evaluates all configurations and updates plots accordingly.

This behaviour corresponds in the real world to perform multiple observations of one target using the same observation settings but using different configurations; these observations are done during several nights: switching from one configuration to another is not allowed during the night.

If night restrictions are used in multi configuration mode, the following warning appears: "Multiple configurations cannot be done in one night (night restrictions are only valid for YYYY/MM/DD)". Night and twilight zones are still helpful to know roughly when these observations can be planned.

To illustrate this feature, following configurations are selected to produce the plots below:

[!NOTE]

Interferometer sketch

This plot shows selected configurations and their related baselines: Aspro2-multiConf-map.png

Observability plot

This plot represents the observability intervals per target and configuration: Aspro2-multiConf-obs.png

[!NOTE]

UV Coverage plot

This plot shows the combined UV coverage of your target using selected configurations: Aspro2-multiConf-uv.png

OIFits viewer

This plot shows the combined OIFits data of your target using selected configurations: Aspro2-multiConf-oifitsViewer.png

Target Editor

This window provides 3 tabbed panes respectively to edit target information, target object models and target groups & associations.

[!NOTE]

Targets Tabbed Pane

The Targets panel allows you to edit target information and associate calibrator target(s) to your science target(s).

On the first screen shot, only science targets are present; on the second screen shot, science and calibrator targets are present:

Target editor with science targets only Target editor with science and calibrator targets

In the tree view on the left, targets are shown using the following rule to order targets: science targets followed by their calibrator targets.

In the calibrator list on the bottom left, all calibrator targets are present only once. On the right, the target information of the selected target is displayed and can be edited.

[!NOTE]

To sort both your science and calibrator targets by their right ascension (R.A.), click on the Sort by R.A. button.

To sort manually your science or calibrator targets, use up or down buttons to move:

To add a new target, use the Simbad star resolver to resolve target(s) by their identifier (see Targets).

To remove the current target, use the small "X" button and confirm the operation. If the selected target is a:

To flag a science target as a calibrator target, select first a science target in the tree view and then click on the Flag calibrator button to enable it: this target is then moved from the tree view to the calibrator list and can be later associated to other science targets using "Drag and Drop". Of course, it is not possible to flag a science target that already has any calibrator target.

Objects can have other flags to be used as Adaptive Optics, Fringe Tracker or Guide stars, see Groups.

To remove the calibrator flag from a calibrator target, select first a calibrator target either in the tree view or in the calibrator list and then click on the Flag calibrator button to disable it: this target is then moved from the calibrator list to the tree view. Of course, if this calibrator target is already associated to science targets, a confirmation message is displayed "Do you really want to remove associations with this calibrator ?". If you confirm, it is also removed automatically from every calibrator list of your science targets.

To remove a calibrator target from the calibrator list of one science target, select first this calibrator target in the tree view and then click on the Remove Calibrator button.

The Target form let you see target information and edit some fields:

The Target notes field let you edit user comments about the selected target.

Models Tabbed Pane

The Models panel allows you to edit the object model of your targets using either an analytical model or an user-defined model (FITS image).

For the selected target, choose the correct Mode to enable its Analytical or User model.

In the tree view at the top left, targets with their models are shown using the following rules to order targets:

[!NOTE]

Analytical model

Each target can have its own object model composed of several elementary analytical model among:

[!NOTE] The supported model list is subject to change and will evolve in the future.

On the first screen shot, only science targets and their models are present; on the second screen shot, science, calibrator targets and their models are present.

Model editor with science targets only Model editor with science and calibrator targets

To add a new elementary model, choose first its model type and then click on the Add button.

To remove an elementary model, select first a model in the tree view and then click on the Remove button.

Of course, you can convert any elementary model to another type: select first a model in the tree view, choose the new model type and click on the Update button. Please check then parameter values and correct them as wanted.

The Telescope FOV indicates the overall field of view (telescope + spatial filter in the recombiner) that may impact the analytical model if any distance (separation, width ...) is larger than 20% of the FOV, then a warning is displayed indicating the problem.

The Model description area gives you a description of the current elementary model and its parameters. The Model Parameters table let you edit each parameter of analytical models.

When several models are defined for a target, the first model is always centered (x = y = 0 and fixed). Positions of other models can be edited using carthesian coordinates (x / y) or polar coordinates rho and theta (respectively separation and position angle following the astronomical convention from north through east) according to edit positions choice.

The Normalize fluxes button corrects values of the flux_weight parameter to have a total flux equal to 1.0.

[!NOTE] The type of coordinates (carthesian or polar) can be defined in the Preferences Window.

User-defined model

Each target can have an user-defined model using one FITS image (monochromatic model) or cube (polychromatic model) representing the object flux over the sky (i.e. X and Y axes corresponds respectively to RA and DEC coordinates) optionally per spectral channel for Fits cubes.

Target editor with an user-defined model

To add or change an user model, click on the Open button and choose your FITS image or cube file (fits or fits.gz files are both supported).

The image extent is displayed (too large extent will generate a warning and the image will not be displayed). One can adjust the image extent using the Pixel size field and rotate the image using the Rotation field. This permits to "fit" any image, whatever its FITS header values, in the interferometer FOV. Of course you have to know what you do!

The Telescope FOV indicates the overall field of view (telescope + spatial filter in the recombiner) that impacts model images if their extent is larger than 20% of the FOV (see the apodization step below).

Click on the AMHRA button to open the AMHRA service that provides several polychromatic science models as FITS image cubes that can be sent back to ASPRO2 using the SAMP interoperability ('image.load.fits' message).

[!NOTE] Use the image browser widget to see all polychromatic images (Fits cube only): Image browser widget

When your FITS image (or cube) is loaded (only the first image / cube present in the FITS file), several image processing tasks are performed to obtain a linear-flux image prepared for Fourier transform computations:

  1. compute its dynamic range
  2. ignore negative values (set to 0.0)
  3. perform image apodization (if necessary) given the telescope diameter and instrumental minimum or model image wavelength by multiplying the image with a gaussian profile whose $FWHM \approx (lambda / diameter)$. Typically the telescope's PSF is 60 mas for a VLTI/UT. So if the object is very extended, ASPRO2 will only retain data within the telescope's PSF (smaller extent).
  4. compute the total flux $Fi$ = sum(image) to normalize the image by 1.0 / Fi i.e. sum(normalized image) = 1.0
  5. ignore flux values lower than an adaptive threshold [*] (i.e. set such values to 0.0) to ensure the error on visibility amplitude is lower than 1 thousandth
  6. extract the region of interest (centered region where flux is > 0.0 to ignore blank data pixels
  7. make the image square i.e. width = height = even number

[!NOTE]

The 5th task is only performed when the Fast mode (optimize the input image) is enabled in the Preferences Window: it consists in discarding useless data to have accurate but faster response time when computing optimized Fast (UV plane) or direct Fourier transform (simulated OIFits data).

If your image was successfully loaded and coordinate increments are valid, the prepared image is displayed on the zoomable image preview using given LUT table and Color scale:

[!NOTE] As useless data pixels are discarded, the image preview displays the prepared image having useful flux data that ASPRO 2 will use in Fourier transforms. To reduce computation time, use small image sizes; moreover, zero padding in the FITS image is useless or counter productive as ASPRO 2 always performs its image processing.

Use the State field to enable or disable an user-defined model.

Actually the user-defined model may be automatically disabled if ASPRO 2 can not load its file (moved or deleted) or if coordinate increments are invalid for the selected configuration (UV Max and instrument minimal wavelength); so it is better to keep FITS image files in a folder dedicated to ASPRO 2 observations on your file system (archive).

Moreover, ASPRO 2 does not embed FITS files in its own Aspro Observation file format for the moment, but certainly in future releases. This means that such observation files can still be exchanged between colleagues but user-defined models will then be disabled. To enable them again, you must send FITS image files to your colleague and he must use either the Open button action to open the FITS image files (placed to another location on his file system) or use the State field to enable them (same file location).

[!NOTE] ASPRO 2 computes FITS checksum to ensure file integrity and detect if an used user-defined model has changed. In such case, this model will be disabled and ASPRO 2 encourages you to check your FITS image by opening the Target editor.

Following FITS image keywords are interpreted by ASPRO 2:

SIMPLE  =                    T / Fits standard
BITPIX  =                  -32 / Bits per pixel                                Float (REAL*4) but any data type is supported
NAXIS   =                    3 / Number of axes                                2 or 3 respectively for FITS image/cube
NAXIS1  =                  512 / Axis length                                   RA  / column
NAXIS2  =                  512 / Axis length                                   DE / row
[NAXIS3 =                    7 / Axis length                                   Optional Wavelength axis]
EXTEND  =                    T / File may contain extensions
[...]
CRPIX1  =                 256. / Reference pixel
CRVAL1  =                   0. / Coordinate at reference pixel
CDELT1  =             -1.2E-10 / Coord. incr. per pixel (original value)       rad / pixel (RA / column)
[CUNIT1 =              'RAD'   / Units along axis                              Optional axis units (rad, deg, arcmin, arcsec)]
CRPIX2  =                 256. / Reference pixel
CRVAL2  =                   0. / Coordinate at reference pixel
CDELT2  =              1.2E-10 / Coord. incr. per pixel (original value)       rad / pixel (DE / row)
[CUNIT2 =              'RAD'   / Units along axis                              Optional axis units (rad, deg, arcmin, arcsec)]
[CRPIX3 =                   1. / Reference pixel
CDELT3 =              4.75E-02 / Coord. incr. per pixel (original value)       (Wavelength increment / image)
CRVAL3 =              1.528550 / Coordinate at reference pixel                 Wavelength reference
CUNIT3 =              'MICRON' / Units along axis                              Optional axis units (meter, micron, nanometer, hertz)]
[...]

[!NOTE]

For example, the following screen shot shows the UV coverage plot of the previous spiral user-defined model:

UV Coverage plot for HD 1234 (user model

Polychromatic User-defined model

How to use polychromatic image models to estimate flux and visibility values at each detector channel defined by EFF_WAVE (central wavelength) and EFF_BAND (channel width) arrays in the OIFITS standard.

The model gives a list of images with attributes:

Given an instrument and a specific instrumental mode, for each channel ($\lambda_i$, $d\lambda_i$):

If the model is mono-chromatic or a single model image A corresponds to the detector channel at lambda_i (channel and image bandwidth overlap or the closest image if no interpolation or extrapolation), then it simplifies to:

If Interpolation is enabled and 2 model images A and B exist where $\lambda_A <= \lambda_i <= \lambda_B$, then a linear interpolation on the image flux can be performed:

With Interpolation, the visibility is a linear combination of Fourier transforms of the A and B normalized images.

For Fits cubes, OI_FLUX's FLUXDATA / FLUXERR columns give the object flux and error (from the object magnitude) scaled by $\frac{Fi}{Fm}$ where $Fm$ is the integrated flux $Fi$ over the band / band width: $$Fm = \frac{ \int_{\lambda_{Bmin}}^{\lambda_{Bmax}} Fi.\delta\lambda }{\lambda_{Bmax} - \lambda_{Bmin}}$$

[!NOTE]

Groups Tabbed Pane

The Groups panel allows you to Drag & Drop targets to define groups and associations, in particular to associate ancillary stars to your SCIENCE or CALIBRATOR objects using the predefined groups:

In the following screenshot, 'Sirius B' uses the 'Sirius A' star for the AO sub-system: Group AO

On the left side, all SCIENCE / CALIBRATOR targets are shown with their associated stars. On the middle tree panel, target Groups are shown with their corresponding stars; stars can belong to multiple groups. On the right side, target groups are displayed for the selected target (see checked boxes) and the group information is displayed for the selected group.

To mark a target as AO / FT / Guide stars, select it on the left side and either click on the corresponding Group(s) (AO star, FT star, Guide star) or use Drag & Drop to the appropriate Group in the tree on the middle (Target groups with their associated targets).

To associate an AO / FT / Guide star to your SCIENCE / CALIBRATOR target(s), use Drag & Drop from the selected ancillary star in the appropriate AO / FT / Guide Star Group to the corresponding SCIENCE / CALIBRATOR target. To discard such association between targets, select the ancillary star and use the Remove association button.

To create user-defined groups, use the Add group button and edit its name, description and color. Only empty user-defined groups can be removed using the Delete group button.

[!NOTE] Target groups (AO / FT) are used by the noise modelling and A2P2 interoperability.

Preferences

This window let you define several settings that are stored on your machine and will be loaded at application start up.

Preferences

Preferences are grouped by feature:

Use the Restore Default settings button to reset your preferences to default values and Save Modifications to make you changes persistent; otherwise, your settings will be used until you close ASPRO 2.

JSkyCalc tool

The JSkyCalc tool made by J. R. Thorstensen, Dartmouth College has one main window with all lot of buttons which shows / hides a pop up window per feature:

[!NOTE]

JSkyCalc main window JSkyCalc sky display

Click on the Help button to open the JSkyCalc documentation page.

Interoperability

JMMC applications are able to communicate with other VO tools (VO stands for virtual observatory) using SAMP (Simple Applications Messaging Protocol) messaging protocol (see IVOA SAMP for more information).

Here are JMMC applications supporting the SAMP messaging protocol:

The following page gives you the official list of VO applications supporting SAMP messaging protocol: IVOA SAMP Software

General description: The communication architecture is the following: all tools communicate with a central "Hub" process, so a hub must be running in order for the messaging to operate. If a hub is running when a JMMC application starts, or if one starts up while any JMMC application is in operation, it will connect to it automatically. A hub can be started from within any JMMC application if needed. Other tools will have their own policies for connecting to the hub, but in general it is a good idea to start a hub first before starting up the tools which you want to talk to it.

This communication has two aspects to it: on the one hand an application can send messages to other applications which causes them to do things, and on the other hand an application can receive and act on such messages sent by other applications.

SAMP in JMMC applications

When a JMMC application starts, it will try to connect to an existing hub or start a new internal hub.

The running hub is indicated by the science target system tray icon that provides following actions:

Here is a screen shot of the hub status window: Hub status window

Anyway when the JMMC application is started, it will be ready to communicate with other JMMC (and VO) applications.

JMMC applications have an Interop menu containing common actions followed by specific actions to send messages to other applications: Interop menu

Common actions are:

[!NOTE]

ASPRO 2 / SearchCal

How to find calibrators easily using SearchCal from ASPRO 2 ?

SearchCal is a tool developed by the JMMC Working Group "catalogue of calibration sources" to assist the astronomers in this calibrator selection process for long baseline interferometric observations.

[!NOTE]

Here is a step by step tutorial:

  1. Start the SearchCal application (or it is already running) to be able to communicate with it: SearchCal Aspro2-calibrators-SearchCal-start.png
  2. In ASPRO 2, select your science target in the target list and use the Search calibrators action in the Interop menu to let ASPRO 2 send a message to SearchCal with your target information (coordinates, magnitudes), the instrument band and other parameters (maximum baseline length): Aspro2-calibrators-StartSearchQuery.png
  3. SearchCal interprets the ASPRO 2 message, updates its graphical user interface and sends the query immediately (please wait). When calibrators are found, they are filtered and displayed: Aspro2-calibrators-SearchCal-results.png
  4. Select the calibrators you want or all displayed calibrators (i.e. filtered) will be sent to ASPRO 2.
  5. Use the Send calibrators to action in the Interop Menu to let SearchCal send these calibrators to ASPRO 2: Aspro2-calibrators-SearchCal-SendCalibrators.png
  6. ASPRO 2 processes the SearchCal message and displays an operation summary: Aspro2-calibrators-Summary.png
  7. That's all: ASPRO 2 has updated the target list with SearchCal calibrators, created an uniform disk model for every calibrator target using the SearchCal diameter corresponding to the instrument band (UD_ fields) and the graphical user interface is updated:

[!NOTE]

ASPRO 2 / LITpro

How to prepare easily your model fitting using LITpro from ASPRO 2 ?

LITpro is a model fitting software, developed and maintained by one JMMC working group ( CRAL, LAOG and FIZEAU ).

[!NOTE]

Here is a step by step tutorial:

  1. Start the LITpro application (or it is already running) to be able to communicate with it: LITpro Aspro2-LITpro-start.png
  2. In ASPRO 2, select your target in the target list and use the Perform model fitting action in the Interop menu to let ASPRO 2 send a message to LITpro with your simulated OIFits file and target information (with object model) as shown on the UV Coverage plot: Aspro2-LITpro-send.png
  3. LITpro interprets the ASPRO 2 message, loads the OIFits file and displays the OIFits validation summary: Aspro2-LITpro-summary.png
  4. That's all: LITpro has now updated the graphical interface with the new created settings including the OIFits file and the target with its object model: Aspro2-LITpro-settings.png

ASPRO 2 / OIFits Explorer

Using the Send OIFits data action in the Interop menu, you can send your simulated OIFits file to the OIFitsExplorer / OImaging or any other VO tools supporting FITS files.

It can be very helpful in several use cases:

ASPRO 2 / A2P2

Using the Send Obs. block(s) to A2p2 action in the Interop menu, you can send an Observing Block of the selected target to A2P2, the ASPRO2 bridge to ESO P2 or CHARA backends.

See the A2P2 project on github: ASPRO2 / A2P2 Tutorial

ASPRO 2 - Export targets to VO Tools

Using the Export targets to VOTable action in the Interop menu, you can send your target list to any other VO tools supporting VOTable files (another ASPRO2 instance, Topcat or Aladin for finding charts).

ASPRO 2 - Import targets from VO Tools

ASPRO 2 supports the standard 'table.load.votable' SAMP message to import a target list from any VO Tool (Topcat, Vizier ...) using the VOTable format (version 1.1 and 1.2) conforming to the following rules:

Supported data columns are listed in the following table:

Name Description Data type UCD 1.0 UCD 1.1 Supported Units
NAME Target name (identifier) char META.MAIN meta.id;meta.main
RA Right ascension - J2000 char POS_EQ_RA_MAIN pos.eq.ra;meta.main 'h:m:s' or 'hms' or 'deg'
DEC Declination - J2000 char POS_EQ_DEC_MAIN pos.eq.ra;meta.main 'd:m:s' or 'dms' or 'deg'
RV Radial velocity double VELOC_HC spect.dopplerVeloc.opt 'km.s-1' or 'km/s'
PMRA Proper motion in RA double POS_EQ_PMRA pos.pm;pos.eq.ra 'mas.yr-1' or mas/yr
PMDEC Proper motion in DEC double POS_EQ_PMDEC pos.pm;pos.eq.dec 'mas.yr-1' or mas/yr
PLX Parallax double POS_PARLX_TRIG pos.parallax.trig mas
e_PLX Parallax error double POS_PARLX_TRIG_ERROR stat.error;pos.parallax.trig mas
HD HD identifier (H. Draper: III/135A) char META.ID meta.id
HIP HIP identifier (Hipparcos catalogue: I/239) char META.ID meta.id
2MASS 2MASS identifier (2Micron All-Sky Survey: II/246) char META.ID meta.id
OTYPES Object type(s) char src.class
SP_TYPES MK spectral type(s) char SPECT_TYPE_MK src.spType
FLUX_V Magnitude V double PHOT_JHN_V phot.mag;em.opt.V mag
FLUX_I Magnitude I double PHOT_JHN_I phot.mag;em.opt.I mag
FLUX_J Magnitude J double PHOT_JHN_J phot.mag;em.IR.J mag
FLUX_H Magnitude H double PHOT_JHN_H phot.mag;em.IR.H mag
FLUX_K Magnitude K double PHOT_JHN_K phot.mag;em.IR.K mag
FLUX_N Magnitude N double PHOT_JHN_N phot.mag;em.IR.8-15um mag

[!NOTE] Only Name and coordinates (RA/DEC) are mandatory. Supported identifiers must use correct column names (HD, HIP, 2MASS).

Here is a sample VOTable file describing all possible parameters and columns: Aspro2_samp_load_votable.xml: Aspro2 Sample Target list (VOTable)

ASPRO 2 - Import FITS image from VO Tools

ASPRO 2 supports the standard 'image.load.fits' SAMP message to import one FITS image or cube from any VO Tool (AMHRA, OImaging, LITpro, DS9 ...).

As described in the User Model section, the FITS image or cube must provide mandatory keywords (increments, units...) to be compatible in terms of spatial and spectral resolution with the observation setup (instrument, baselines).

Support and change requests

Please do not hesitate to use the JMMC Feedback Report integrated using Help menu / Report Feedback to JMMC... action: Aspro2-FeebackReport.png

Of course, you can still contact the user support team for any bug report or change request.

[!NOTE] If an unexpected exception occurs in a JMMC application, an error message will be displayed and the JMMC Feedback Report will be opened to encourage users to submit their problems and let the JMMC technical team fix it as soon as possible

Sample files

Here are the "Guided Tour" Observation files that can be loaded in ASPRO 2 / SearchCal / LITpro for demonstration purposes:

The following folder gives sample output files (PDF, OIFITS files): outputs