AkôFlow Blog

From a DAG to your first AkôFlow run

Wed, 21 Oct 2026 00:00:00 GMT

With AkôFlow Desktop already installed, your first experiment can start on your own workstation. Describe one activity in YAML, select your local machine, and watch a real execution produce a file. Then turn that first activity into a small analysis pipeline.

This walkthrough uses AkôFlow Desktop throughout. Desktop starts its matching local services and manages the connection to the engine. You do not need to clone the source repository, start a development Compose stack, or copy an API token.

What you will build

Begin with write-report: one activity that writes result.txt and prints its contents in the activity log. This checks the complete path from a definition to a local execution and its recorded output.

After that succeeds, import a second YAML with three activities: prepare three measurements, compute their mean, and write a report. The expected answer is 4.00.

Both examples use a small BusyBox container on your local Docker engine. They perform real execution. They do not simulate work or allocate cloud machines.

1. Begin after Desktop is installed

This walkthrough starts after installing AkôFlow Desktop. If you still need the application, follow Install AkôFlow Desktop, then return here.

Start Docker and open the installed AkôFlow Desktop application.
Let the engine checkup finish and wait for Overview.
Confirm Connected at the bottom-left corner.
Start with Infrastructure → Environments in the sidebar.

The screenshots below were captured from the actual interface. They show the controls using an existing reference instance: its workflow is named hello, its activity is a, and its local environment is Local environment. For your experiment, enter the tutorial names first-local-check, write-report, Local check, and First local scope. Your fresh catalogs may be empty. The reference run's counts and files are identified in each caption rather than presented as your experiment's results.

Each red number has a matching instruction below the image. Click a screenshot to enlarge it with its arrows; on a phone, scroll the enlarged view sideways to read the controls.

Begin on Overview after installation

The capture shows an existing instance. Your fresh installation can have empty catalogs.

Confirm that the bottom-left indicator says Connected.
Open Infrastructure → Environments to create your local target.

Checkpoint: Desktop is connected. If startup fails, open its failure details before retrying.

2. Connect your local machine

Open Infrastructure → Environments. To create the environment from scratch, follow the two screens below. If you already created Local check, open it and continue with its connection check instead.

Open the local environment setup

Use the execution-infrastructure catalog for this real local workflow.

Select Connect environment. Some releases call this New environment.
Keep Execution infrastructure selected.

Select Connect environment (called New environment in some releases), then Local machine.
Name it Local check.
Select Test connection.
When the test succeeds, select Save environment.

Create Local check

This form has only been filled for the capture: Save environment becomes available after a successful connection test.

Choose Local machine.
Enter Local check as the environment name.
Select Test connection and wait for success.
After the test succeeds, select Save environment.

On the environment page, select Check now. Wait until Local machine shows online. This makes the local resource available for planning.

An environment describes where the work can run. Here, the target is the machine reached through your local AkôFlow engine. Desktop requests connection checks from the daemon.

Check that the local machine is online

Open the environment you created. This reference environment is already online; your tutorial environment is named Local check.

Select Check now to request a fresh connection check.
Continue when the local connection reads online.

Checkpoint: the local resource is online. Remember its environment name for step 5.

3. Save your first workflow YAML

Create a plain-text file named first-local-check.yaml, or download the complete YAML. Copy the whole document, preserving indentation, and save it with the .yaml extension.

name: first-local-check
spec:
  namespace: learning
  activities:
    - name: write-report
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            printf 'Akoflow local check\n' > result.txt
            cat result.txt
      expectedOutputs: [result.txt]

Read the document from the outside in:

name identifies the workflow. namespace groups it under learning.
activities contains one unit of work: write-report.
command.executable names the BusyBox image. targetFormat: oci selects the container format used by local Docker.
entrypoint: sh and the -c argument run the following shell script.
printf creates the file in the activity workspace. cat prints it into the activity log.
expectedOutputs asserts that result.txt exists after execution.
CPU and memory limits describe the activity's small resource demand.

The image comes from Docker Hub, so its first use may take longer while it downloads. For a research reproducibility bundle, also retain the resolved image digest alongside the version tag.

4. Import the YAML in Desktop

Import the workflow you saved

The catalog can already contain other workflows. Import your first-local-check.yaml file.

Select Import YAML, then choose first-local-check.yaml.
Find this catalog under Workflows → Definitions.

Open Workflows → Definitions.
Select Import YAML and choose first-local-check.yaml.
Open the new first-local-check definition.
Confirm that the DAG contains one activity named write-report.

A DAG is a directed acyclic graph: nodes are activities and arrows are dependencies. This first graph has one node and no arrows, enough to learn the execution lifecycle before adding data handoffs.

If the name already exists, open the existing definition or change name before importing another copy. The importer normalizes names into identifiers, so each new definition needs a distinct name.

Checkpoint: the definition exists and its graph matches the YAML. Importing saves a definition; it does not start a run.

5. Create a local execution scope

Create a new execution scope

A fresh instance can show an empty catalog; the creation action is in the page header.

Select Create scope (New execution scope in some releases).
Open Infrastructure → Execution scopes.

Open Infrastructure → Execution scopes.
Select Create scope (called New execution scope in some releases).
Name it First local scope and select your local environment.
Leave Create the initial network topology enabled.
Select Create execution scope.

Name the scope and keep its topology

Enter First local scope. The initial topology is sufficient for a one-machine experiment.

Enter First local scope in Name.
Leave Create the initial network topology enabled.

Select only the local environment for this experiment

The reference instance calls its existing environment Local environment. In your tutorial, choose Local check.

Keep the initial topology enabled.
Select the checkbox for your local environment; use Local check from step 2.

After selecting Local check, scroll to the bottom of the form to save it:

Save the execution scope

Scroll below the list of participating environments to reach this action.

Select Create execution scope after naming the scope and selecting Local check.

A scope selects the environment resources offered to planning. Its topology describes the connections between them. A one-machine experiment needs no network links.

Desktop creates these records and their identifiers. The YAML here describes the workflow; you do not need to author environment, scope, or plan API envelopes.

6. Make a plan and start the run

Return to first-local-check and select Generate plan:

Start planning from the workflow

This reference definition is named hello. Open first-local-check in your own catalog.

Select Generate plan on the workflow detail page.

Choose manual planning

The reference definition has two activities. Your first-local-check definition has only write-report.

Select Create manually.
Use Real execution.
Under Execution scope, choose First local scope; scroll the list if needed.

Choose Create manually.
Select First local scope.
Select write-report in the activity graph.
Choose your local machine runtime and local machine resource.
Set Expected execution time to 1 second.
Select Generate plan.

Assign a runtime, duration, and target

This reference activity is named a. In your workflow, select write-report; configure the same controls.

Select the activity node in the DAG.
Choose the local machine runtime.
Set Expected execution time to 1 and keep the s unit.
Choose your local machine target. Then scroll to the plan review and Generate plan.

The duration is an estimate, not a timeout or a measurement. Image download and startup can make the first run take longer.

On the saved plan page, select Execute plan:

Open the execution request from the saved plan

The example capture shows an existing saved plan. Use the manual plan generated for first-local-check.

Select Execute plan.

Review the selected plan, Real execution, and the local runtime. Keep the suggested unique run ID or enter your own:

Review the execution before starting

This reference plan is bound to its execution request. Your scope and plan names should refer to your new tutorial records.

Keep the suggested run ID or enter a fresh unique ID.
Confirm that the selected plan is the one you just generated.
Confirm Real execution and an available local runtime.

Scroll to the bottom, then select Start execution once:

Start the local run

Scroll to the bottom of the execution request after reviewing the selected plan.

Select Start execution once. Submission is asynchronous; wait on the resulting run page.

Wait until the run says completed and 1/1 activities settled:

Check completion and open Activities

This real reference run has two activities. Your first-local-check run must show 1/1 settled.

Wait for completed.
Check 1/1 settled for your one-activity workflow.
Open Activities to locate write-report.

A plan describes where work should run. A run records what happened. Submission is asynchronous: pending or running can appear before completed.

7. Inspect your first result

On the completed run, select Activities, then write-report. Open its Details link or Open activity page from its information panel (some releases label this Open activity details).

Locate the activity to inspect its output

This reference run lists a and b. Your activity list contains write-report.

Select write-report in your activity list. Use Details or Open activity page in its information panel.

Where to look	Expected result
Execution details	Exit code 0
Activity output/log	`Akoflow local check`
Generated files	`result.txt`, with a SHA-256 checksum

Scroll down the activity page to Activity output and Generated files:

Find the output and its checksum

The reference run produced a.txt. Your YAML produces result.txt and prints Akoflow local check.

Inspect Activity output for the captured runtime log.
In Generated files, look for result.txt in your run.
Confirm that the file has a SHA-256 checksum.

The generated file belongs to the activity workspace managed by the engine. Listing a file records that it was observed; it does not automatically download it into your computer's Downloads folder.

You have now submitted and inspected a real local experiment. Save the YAML with your experiment material so the definition can be reused.

8. Extend it into a small analysis

Save the next document as first-local-analysis.yaml, or download the complete analysis YAML. This is a new, complete workflow, with a different name from the first definition.

First local analysis. Nodes in the same column can run in parallel once their dependencies complete.

Activity	Reads	Produces
`prepare`	Values declared in its command: 2, 4, 6	`measurements.txt`
`analyze`	`measurements.txt`	`mean.txt`, containing `4.00`
`write-report`	`mean.txt`	`report.txt`, containing `Mean: 4.00`

name: first-local-analysis
spec:
  namespace: learning
  activities:
    - name: prepare
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            printf '2\n4\n6\n' > measurements.txt
            cat measurements.txt
      expectedOutputs: [measurements.txt]

    - name: analyze
      dependsOn: [prepare]
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            awk '{sum += $1; n++} END {printf "%.2f\n", sum/n}' measurements.txt > mean.txt
            cat mean.txt
      expectedOutputs: [mean.txt]

    - name: write-report
      dependsOn: [analyze]
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            printf 'Mean: %s\n' "$(cat mean.txt)" > report.txt
            cat report.txt
      expectedOutputs: [report.txt]

The new field is dependsOn. analyze waits for prepare, and write-report waits for analyze. AkôFlow stages the predecessor's workspace before a dependent activity starts. Each stage writes a different output path, avoiding conflicting contents at the same path. expectedOutputs verifies that the required file exists.

Repeat the Desktop sequence:

Import first-local-analysis.yaml in Workflows → Definitions.
Confirm the three-node DAG above.
Create a manual plan using the existing First local scope.
Assign all three activities to the local runtime and resource, with an expected duration of 1 second each.
Generate the plan, choose Execute plan → Real execution, and start it.
Wait for completed and 3/3 activities settled.
Open the final write-report activity. Its log should print Mean: 4.00. Its generated files should include report.txt with a checksum.

This graph is sequential because each stage consumes the previous stage's output. A future independent branch should declare only the dependencies it needs. Dependencies determine readiness; resource capacity determines whether ready activities can run together.

If something stops you

Symptom	Next action
Desktop does not reach Connected	Check Docker and inspect first-start failure details.
Local environment is offline or missing from planning	Test its connection, save it, and select Check now.
YAML import fails	Check indentation, retain the complete `name`/`spec` wrapper, and use a distinct workflow name.
No compatible runtime appears	Recheck the environment's runtime binding and select a real local scope.
The first activity cannot obtain its image	Inspect the activity error and verify access to Docker Hub and the local Docker engine.
Analysis cannot find its input	Check `dependsOn`, the predecessor's completion, and workspace-staging evidence.
A run fails or stays pending	Open activity details and run events, then see Troubleshooting.

The idea behind AkôFlow

The original AkôFlow paper introduces middleware for parallel scientific workflows in containerized environments, with provenance capture and an astronomy evaluation. It gives the research context for the project:

Ferreira, W.; Kunstmann, L.; Paes, A.; Bedo, M.; de Oliveira, D. AkôFlow: um Middleware para execução de Workflows científicos em múltiplos ambientes conteinerizados. SBBD, 2024, pp. 27–39. Read the paper.

This post follows the current Desktop interface and portable workflow format, which have evolved since the publication. The paper explains the research motivation; the documentation and downloadable YAML files describe the steps used here.

Here, the YAML is the workflow definition, the environment is your local machine, the scope selects eligible resources, the plan assigns activities, and the run holds observed results. Generated files and checksums provide a first piece of execution evidence.

For your next experiment, change the measurements in a new copy of the analysis YAML and check that the mean changes accordingly. Continue with planning alternatives, workflow authoring, or the Montage 050 scientific workflow.

API automation is a separate next step once you know these objects; see API access. The Desktop path manages its internal credentials for you.

Montage 050: a sky made of workflows

Wed, 21 Oct 2026 00:00:00 GMT

The stars in the opening image are the output of a scientific computation. Before the color mosaic existed, individual observations had to be reprojected, their overlaps compared, their backgrounds reconciled, and their pixels combined. AkôFlow coordinates those steps as a workflow and keeps the execution evidence alongside the result.

This field note follows Montage 050, a 58-activity astronomy workflow. We will look at what the activities do, how to reproduce the local example, and what an existing completed experiment tells us about planning and execution.

Start with the image—and its provenance

The cover is the actual 1800 × 1800 color preview from run montage-docker-image-real-20261010-v2. It is a recorded product of a completed hybrid GCP/HPC experiment. Click it to enlarge the image, or open the original PNG.

That experiment and the local reproduction described below use different execution environments. The cover and historical timings establish what the completed hybrid run produced; they are not a claim that the two-slot local example finished in the same time.

The preserved PNG is 4,920,451 bytes. Its SHA-256 is:

63fa4d8447274bdb8a44f6be8cf5a23c0a2f0baa479bd2ae1ec3b541df4e19f2

The image copied into this site matches that checksum. You can download the observed result summary to connect the picture to the run, activity counts, timings, and audit checks.

What Montage does for astronomy

A sky survey records many images rather than a single photograph of an entire region. Those images may use different pixel grids and have different background levels. Simply placing them next to each other would leave misalignment and visible seams.

Montage, developed at IPAC, combines astronomical images while preserving positional and calibration fidelity. Its building blocks operate on FITS files, the scientific image products in this workflow. The color PNG is a visualization of the resulting mosaics; retain the FITS products for scientific analysis.

Three operations explain much of the computation:

Reprojection: map observations onto a common output grid. The mProject documentation describes the input image, header template, reprojected image, and accompanying area image.
Background matching: measure overlap differences and solve for consistent corrections. mBgModel uses the fitted differences to estimate a global set of adjustments.
Coaddition: combine corrected observations into mosaics. The Montage module guide describes the tools for metadata generation, reprojection, background correction, and mosaicking.

Here, twelve input FITS observations feed three image-band branches. Each branch produces a FITS mosaic and a monochrome preview; a final activity combines the three mosaics into the color preview.

Which Montage example and which public data?

This example is Montage 050, preserved in the original image as 050d. The identifier names the workload configuration; it does not mean that the graph contains 50 activities. Section 4.1 and Table 1 of the AkôFlow paper, SBBD 2024, describe the smaller “0.5” configuration with the same inventory used here: 12 projections, 18 overlap fits, and 58 activity executions in total. The paper also evaluates a larger “1.0” configuration with 472 executions. This walkthrough uses the smaller one. The bundled FITS header templates define its actual output footprint and pixel grid.

The inputs are real, publicly accessible astronomical survey images, rather than generated test pictures. Their names identify the POSS2/UKSTU survey products distributed through the Digitized Sky Survey (DSS) archive at IRSA. DSS digitizes photographic survey plates from the Palomar and UK Schmidt telescopes; IRSA provides image access and links to the originating STScI archive. The IRSA dataset summary documents that survey lineage. Public access does not remove the archive's attribution and copyright requirements; retain the DSS/STScI and original survey acknowledgments when reusing the images.

The pinned bundle contains four input tiles in each of three survey bands:

Branch	Source filename family	Source band	FITS mosaic	Display channel in the final PNG
`1`	`poss2ukstu_blue_*.fits`	Blue	`1-mosaic.fits`	Blue
`2`	`poss2ukstu_red_*.fits`	Red	`2-mosaic.fits`	Green
`3`	`poss2ukstu_ir_*.fits`	Near infrared	`3-mosaic.fits`	Red

That is 12 FITS inputs, approximately 87 MiB in the image's input seed. The RGB assignment is a visualization choice: the red survey band is displayed in green, and the infrared band in red. Read the scientific FITS products and their headers when interpreting measurements; PNG colors alone do not identify an observing wavelength.

The exact command and file inventory is available in the pinned workflow.yaml. Keeping that revision and the container digest identifies the packaged input set used for reproduction. Acquiring a fresh cutout from the public archive may select different pixels or preprocessing, so it is a new input set to record explicitly.

Inside the 58-activity graph

The local bundle preserves the original commands, activity names, and 138 named file handoffs. Its activity inventory is:

Native command	Activities	Responsibility
`mProject`	12	Reproject the input observations
`mDiffFit`	18	Compare overlaps and fit their differences
`mConcatFit`	3	Assemble fit results for each band
`mBgModel`	3	Solve each band's background corrections
`mBackground`	12	Apply corrections to the projected observations
`mImgtbl`	3	Build metadata tables for corrected images
`mAdd`	3	Coadd the three FITS mosaics
`mViewer`	4	Produce three monochrome previews and one color preview
Total	58

The diagram below comes from the local example's activity and dependency contract. Enlarge it to follow individual edges.

Montage 050 locally. Nodes in the same column can run in parallel once their dependencies complete.

Independent projections and overlap operations can run concurrently after their own inputs are ready. Background modeling introduces a convergence point within each band. The final color preview waits for its three mosaic inputs. There is no extra global barrier forcing an unrelated band to wait at every stage.

This is why the DAG matters: it encodes scientific dependencies. A scheduler can choose where ready work runs, but cannot skip an input merely to make the graph appear more parallel. The Montage parallelization guide explains the relationship between independent image operations and background-model convergence.

What each activity does, and what its parameters mean

The scientific design follows Jacob et al., Montage: a grid portal and software toolkit for science-grade astronomical image mosaicking, especially its toolkit components and workflow discussion. Reprojection aligns the pixel grids; overlap fitting supplies evidence for background adjustments; corrected images are then coadded. The sections below combine that explanation with the module manuals and the actual arguments in this example.

An activity type, such as mProject, can have several executions in the graph. Here, the same processing chain repeats for three bands. The examples below show the first band unless noted otherwise. They run inside an activity workspace after AkôFlow has staged the declared inputs; copying one command into an empty directory is not a complete reproduction.

`mProject`: put one observation on the common sky grid

mProject -X poss2ukstu_blue_001_001.fits pposs2ukstu_blue_001_001.fits region-oversized.hdr

Each of the 12 executions reprojects one observation. It maps input pixels through sky coordinates onto the requested output grid, accounting for pixel overlap rather than merely resizing a picture. Its outputs include the projected FITS image and an accompanying _area.fits coverage image.

Parameter	Meaning in this example
`-X`	Expand the template region as necessary to retain the input image's extent.
`poss2ukstu_blue_001_001.fits`	Input observation.
`pposs2ukstu_blue_001_001.fits`	Projected output; the `p` prefix is this workflow's naming convention.
`region-oversized.hdr`	FITS header template defining the working grid, coordinate projection, reference coordinates, and pixel scale. It is used before the final mosaic footprint is applied.

These tasks have no predecessor activities and can start independently when execution slots are available. See the official mProject manual.

`mDiffFit`: measure how two projected images disagree

mDiffFit -d -s 1-fit.000001.000002.txt pposs2ukstu_blue_001_001.fits pposs2ukstu_blue_001_002.fits 1-diff.000001.000002.fits region-oversized.hdr

The 18 executions compare overlapping pairs: six pairs among the four images in each band. mDiffFit combines image differencing (mDiff) with a plane fit (mFitplane). It measures relative background offsets and gradients that the next stages need.

Parameter	Meaning in this example
`-d`	Enable diagnostic output.
`-s 1-fit.000001.000002.txt`	Write the structured fit/status result for this pair to a named file.
The two `pposs2ukstu_…fits` arguments	Projected images to compare; both projection tasks must finish first.
`1-diff.000001.000002.fits`	Difference-image path used by the combined operation.
`region-oversized.hdr`	Shared working-grid template.

Different pairs can run concurrently after their respective inputs arrive. See the Montage grid-tool description and mDiffFit implementation and command interface.

`mConcatFit`: gather the pairwise measurements

mConcatFit 1-stat.tbl 1-fits.tbl .

There are three executions, one per band. Each gathers the individual overlap-fit records into the table required by background modeling. It combines fit parameters, not image pixels.

Parameter	Meaning in this example
`1-stat.tbl`	Input table identifying the fit-result files to collect.
`1-fits.tbl`	Output table of pairwise fit measurements.
`.`	Directory containing those staged fit-result files: the current workspace.

This task waits for the band's six mDiffFit executions. The grid-tool guide explains why independently generated fit records need this merge; the mConcatFit source documents its three positional arguments.

`mBgModel`: solve a consistent background model for the band

mBgModel -i 100000 1-images.tbl 1-fits.tbl 1-corrections.tbl

The three executions use the overlap measurements together to find per-image background corrections. A global solution within each band avoids treating each seam as an unrelated adjustment. The result is a correction table; the image pixels are changed by the following activity.

Parameter	Meaning in this example
`-i 100000`	Iteration count requested by this versioned workload's modeling command; it is not a timeout or CPU allocation. Preserve it when reproducing the pinned example.
`1-images.tbl`	Input image metadata and identifiers.
`1-fits.tbl`	Aggregated measurements from `mConcatFit`.
`1-corrections.tbl`	Output coefficients for correcting each image's background.

This is a convergence point for each band. Other bands can progress independently. The official mBgModel manual explains the solver and its arguments; documented iteration limits can differ from the packaged command, so the pinned image remains the reference for this reproduction.

`mBackground`: apply the correction to one projected image

mBackground -t pposs2ukstu_blue_001_001.fits cposs2ukstu_blue_001_001.fits 1-projected.tbl 1-corrections.tbl

Each of the 12 executions subtracts the fitted background plane from one projected image. In the module's model, the plane has the form A*x + B*y + C. This matches relative backgrounds while retaining the image for coaddition; it is not a command to remove every astronomical source or all diffuse emission.

Parameter	Meaning in this example
`-t`	Table mode: obtain the image's correction coefficients from the supplied tables rather than three explicit coefficient arguments.
`pposs2ukstu_blue_001_001.fits`	Projected input image.
`cposs2ukstu_blue_001_001.fits`	Background-corrected output; `c` is the workflow's naming convention.
`1-projected.tbl`	Metadata table used to identify the projected image.
`1-corrections.tbl`	Per-image corrections produced by `mBgModel`.

Corrections for different images can run concurrently once their band model and projected inputs are ready. See the official mBackground manual.

`mImgtbl`: describe the corrected files for the coaddition step

mImgtbl . -t 1-corrected.tbl 1-updated-corrected.tbl

The three executions read FITS headers and create metadata tables. Those tables describe image geometry and file identity so that coaddition can place the corrected inputs correctly. This stage produces metadata, not another mosaic.

Parameter	Meaning in this example
`.`	Directory in which to read the corrected FITS files.
`-t 1-corrected.tbl`	Restrict processing to the images named in this input list, rather than every FITS file in the workspace.
`1-updated-corrected.tbl`	Output table with the corrected files' header metadata.

Each task waits for its band's four corrected images. The official mImgtbl manual documents the table fields and selection option.

`mAdd`: coadd the corrected observations into one FITS mosaic

mAdd -e 1-updated-corrected.tbl region.hdr 1-mosaic.fits

The three executions create one scientific mosaic per band from the corrected, aligned images. Coaddition combines contributions where pixels overlap; it is not concatenation of files or an RGB operation. Montage also produces an area/coverage mosaic.

Parameter	Meaning in this example
`-e`	Use the exact dimensions in the final header template instead of shrinking the mosaic to the data's bounding region.
`1-updated-corrected.tbl`	Metadata table selecting the images to coadd.
`region.hdr`	Final mosaic template, as distinct from the oversized working template used earlier. The recorded output is 1800 × 1800 pixels.
`1-mosaic.fits`	Output scientific mosaic for this band.

No averaging-mode override (-a) is supplied in this command. The official mAdd manual describes the coaddition modes and area-image behavior.

`mViewer`: turn scientific mosaics into viewable PNGs

The first three executions render one preview per band:

mViewer -ct 1 -gray 1-mosaic.fits -1s max gaussian -png 1-mosaic.png

Parameter	Meaning in this example
`-ct 1`	Select color-table index 1 for the single-band display.
`-gray 1-mosaic.fits`	Read one FITS image for single-band rendering.
`-1s max`	Set the display range using a sigma-based lower bound and the maximum as the upper bound.
`gaussian`	Use Gaussian histogram-based stretching for display.
`-png 1-mosaic.png`	Write the rendered PNG.

The fourth execution builds the color preview after all three mAdd tasks finish:

mViewer -red 3-mosaic.fits -0.5s max gaussian-log -green 2-mosaic.fits -0.5s max gaussian-log -blue 1-mosaic.fits -0.5s max gaussian-log -png mosaic-color.png

Here, -red, -green, and -blue assign FITS mosaics to display channels. Each receives its own -0.5s max range and gaussian-log stretch. -png names the final output. These choices control visualization, not the calibrated FITS pixel values.

The official mViewer examples describe these interfaces. Berriman and Good's visualization paper explains the scientific visualization context. The three single-band previews and the color preview are sibling consumers of the FITS mosaics: the color task does not need to wait for the preview PNGs.

Scientific parameters and execution settings are different

The command arguments above determine image processing and file products. The YAML also supplies AkôFlow settings such as cpuLimit: 1000m (one CPU), memoryLimit: 1Gi, the selected runtime, and dependsOn. Those govern execution placement, limits, and readiness; they are not flags passed to Montage. workspaceSeedPath identifies the packaged seed, while historical simulation.durationSeconds values support planning and do not measure a new real execution.

Reproduce the workload locally

If this is your first AkôFlow experiment, begin with the Desktop walkthrough. It teaches definitions, environments, scopes, plans, and runs with a tiny local workload.

The full Montage bundle adds a command-line preparation and execution path. Have Git, Go 1.23 or newer, and Docker with linux/amd64 support available. Keep at least 15 GiB of free disk for the image and intermediate workspaces. Retention and concurrency affect the peak requirement. Apple Silicon runs this amd64 workload through emulation and may take substantially longer.

1. Get the versioned example

git clone https://github.com/UFFeScience/akoflow-examples.git
cd akoflow-examples
git checkout --detach d890c3171e3661890305b763b8fc3ede48bb61b4
cd scientific-workflows/montage-050

Pinning the checkout makes this walkthrough refer to a specific example revision. The bundle README documents its requirements and commands.

The bundle contains workflow.yaml, environment.yaml, scope.yaml, and topology.yaml, plus preparation, execution, and validation scripts. The workflow retains historical simulation durations as model inputs. Use the provided runner or daemon helper for the real workload; importing that source YAML alone is not the complete real-execution setup.

2. Prepare the image and inputs

./prepare.sh

Preparation obtains the pinned image and Go dependencies, and checks the command/input contract. The image includes approximately 87 MiB of source FITS data, region headers, lookup tables, and the native Montage tools. There is no need to locate twelve observations manually.

The upstream image is pinned by digest:

ovvesley/akoflow-wf-montage@sha256:26b060b83b990557ea86ab40503cc8f17ab6016b5973e7e6f9201100a96440c9

Preparation success establishes that the inputs and commands are available. It does not mean all scientific activities have executed.

3. Execute the complete local DAG

./run.sh

The standalone runner uses two CPU slots by default. Each activity becomes eligible once its dependencies finish and a slot is available. It copies the bundled input seed, executes the native commands with network access disabled, and writes activity observations under outputs/.

This path provisions no cloud machines and needs no remote HPC account. It is a substantial scientific workload: allow it to finish rather than interpreting a slow projection as a completed run.

4. Validate and open the products

./validate.sh

Inspect the final files in outputs/:

Product	What it gives you
`1-mosaic.fits`, `2-mosaic.fits`, `3-mosaic.fits`	Three 1800 × 1800 scientific mosaics
`1-mosaic.png`, `2-mosaic.png`, `3-mosaic.png`	Monochrome visual previews
`mosaic-color.png`	Combined color preview
`manifest.json`	Generated artifacts and SHA-256 digests
`dag-validation.json`	Dependency-wave validation
`stage-.json`	Per-activity observations

The validator checks all 58 activity records, FITS dimensions, and PNG headers. A successful manifest is published only after the workflow and final-file checks pass. Merely finding one intermediate image is insufficient to declare the experiment complete.

Inspect a daemon-managed run in Desktop

The bundle also supports a daemon helper that registers the local environment, builds the declared image, and submits the 58 activities to the engine. This advanced path requires a daemon whose API address and token you manage; follow API connection setup. The graphical Desktop installation keeps its internal credentials managed by its proxy—do not assume that it exposes a shell token.

From the example directory, with that daemon connection configured:

go run ../../tools/daemon-local -root ../.. -example scientific-workflows/montage-050 -wait=false

The command prints the submitted run ID and returns while execution continues. Connect Desktop to that same instance and open the run. Inspect its activity DAG, file handoffs, logs, and completion status. The daemon owns execution and transfers; the standalone runner's outputs/ directory belongs to the separate standalone path.

What the completed hybrid experiment observed

The following results come from the preserved completion record for montage-docker-image-real-20261010-v2, dated by that run's identity. Its topology comprised ten GCP e2-micro instances, two e2-medium instances, and eight HPC activity assignments. This is a historical experiment, not the local two-slot configuration above.

Evidence	Recorded result
Completed activities	58 / 58
Failed activities	0
Successful runtime handles	58
Missing dependency routes	0
Transfer-barrier violations	0
Unreleased consumer leases	0
Overlapping activities on single-lane micro instances	0
Final PNG dimensions	1800 × 1800

The preserved record also distinguishes three timing scopes:

Timing	Seconds	Approximately
Planned makespan	3,617.94	60.3 min
SimGrid makespan	3,617.50	60.3 min
Real API-reported makespan	6,924.25	115.4 min
Run timestamp wall interval	6,949.00	115.8 min

The real API-reported makespan was about 1.91× the planned estimate. That is an observation from this run, not a general slowdown factor. Close agreement between the plan and simulation did not establish that the real distributed execution would match either prediction.

The accompanying results record identifies whole-workspace traffic and different planned edge volumes as a comparability limit. Summed transfer or compute work can overlap across activities and is not the same as wall-clock makespan. Likewise, a zero reported interference value cannot establish that physical contention was absent.

The recorded cloud compute-and-boot-disk lifecycle estimate was USD 0.3532 at the experiment's list rates. It excludes network egress, public IPv4, reusable image storage, discounts, and tax, and assigns no calibrated monetary tariff to HPC. It is an estimate, not a provider invoice or a current price quote. Other cost fields in the JSON use different task/window scopes and should not be treated as equivalent bills.

Download the result summary and its limitations. The repository preserves the original completion record and detailed results.

What is—and is not—verified for the local bundle

The checked-in local image contract was validated on 2026-10-20: twelve FITS inputs, 58 activities, and 138 named handoffs. That record explicitly states fullExecutionPerformed: false. Its separate daemon snapshot recorded a running workflow with zero completed activities at capture time. These are historical snapshots; neither establishes the current state of another instance.

The completed hybrid run supplies the mosaic and the results in this article. To claim a completed reproduction on your machine, retain your own successful validator output, activity records, and output manifest. The local showcase page links the checked-in contract and daemon evidence.

Keep the experiment with the picture

The mosaic is the visible result, but the research artifact includes more: input identity, native commands, the dependency graph, resource assignments, file transfers, and output digests. Together, they explain how the image was produced and where a later execution differs.

AkôFlow's original paper provides the research context: Ferreira et al., AkôFlow: um Middleware para execução de Workflows científicos em múltiplos ambientes conteinerizados, SBBD 2024, pp. 27–39. Read the publication.

Continue with the complete local example, the Desktop first experiment, or planning alternatives. When comparing placements, preserve the scientific workload and change the execution environment deliberately, so the measurements remain interpretable.

AkôFlow Blog

From a DAG to your first AkôFlow run

What you will build​

1. Begin after Desktop is installed​

2. Connect your local machine​

3. Save your first workflow YAML​

4. Import the YAML in Desktop​

5. Create a local execution scope​

6. Make a plan and start the run​

7. Inspect your first result​

8. Extend it into a small analysis​

If something stops you​

The idea behind AkôFlow​

Montage 050: a sky made of workflows

Start with the image—and its provenance​

What Montage does for astronomy​

Which Montage example and which public data?​

Inside the 58-activity graph​

What each activity does, and what its parameters mean​

mProject: put one observation on the common sky grid​

mDiffFit: measure how two projected images disagree​

mConcatFit: gather the pairwise measurements​

mBgModel: solve a consistent background model for the band​

mBackground: apply the correction to one projected image​

mImgtbl: describe the corrected files for the coaddition step​

mAdd: coadd the corrected observations into one FITS mosaic​

mViewer: turn scientific mosaics into viewable PNGs​

Scientific parameters and execution settings are different​

Reproduce the workload locally​

1. Get the versioned example​

2. Prepare the image and inputs​

3. Execute the complete local DAG​

4. Validate and open the products​

Inspect a daemon-managed run in Desktop​

What the completed hybrid experiment observed​

What is—and is not—verified for the local bundle​

Keep the experiment with the picture​