Usage Examples

The examples below demonstrate typical workflows for the Python API and command line interface.

Quick Start

>>> from microlens_submit import load, Submission
>>>
>>> # Load an existing project
>>> submission = load("./my_project")
>>>
>>> # Or create a new submission
>>> submission = Submission()
>>> submission.team_name = "Team Alpha"
>>> submission.tier = "experienced"
>>> submission.save("./my_project")
>>>
>>> # Add a solution to an event
>>> event = submission.get_event("EVENT001")
>>> solution = event.add_solution(
...     model_type="1S1L",
...     parameters={"t0": 2459123.5, "u0": 0.1, "tE": 20.0},
... )
>>> solution.log_likelihood = -1234.56
>>> solution.cpu_hours = 2.5
>>> submission.save()

Command Line Usage

# Initialize a new project
microlens-submit init --team-name "Team Alpha" --tier "experienced" ./project

# Add a solution
microlens-submit add-solution EVENT001 1S1L ./project \
    --param t0=2459123.5 --param u0=0.1 --param tE=20.0 \
    --log-likelihood -1234.56 --cpu-hours 2.5

# Validate and generate dossier
microlens-submit validate-submission ./project
microlens-submit generate-dossier ./project

# Export for submission
microlens-submit export submission.zip ./project

Supported Model Types

• 1S1L: Point Source, Single Point Lens (standard microlensing)

• 1S2L: Point Source, Binary Point Lens

• 2S1L: Binary Source, Single Point Lens

• 2S2L: Binary Source, Binary Point Lens

• 1S3L: Point Source, Triple Point Lens

• 2S3L: Binary Source, Triple Point Lens

Higher-Order Effects

• parallax: Microlens parallax effect

• finite-source: Finite source size effect

• lens-orbital-motion: Orbital motion of lens components

• xallarap: Source orbital motion

• gaussian-process: Gaussian process noise modeling

• stellar-rotation: Stellar rotation effects

• fitted-limb-darkening: Fitted limb darkening coefficients

Extended Example

>>> from microlens_submit import load, Submission
>>> from pathlib import Path
>>>
>>> # Create a new submission project
>>> submission = Submission()
>>> submission.team_name = "Team Alpha"
>>> submission.tier = "experienced"
>>> submission.repo_url = "https://github.com/team-alpha/microlens-analysis"
>>>
>>> # Add hardware information
>>> submission.hardware_info = {
...     "cpu_details": "Intel Xeon E5-2680 v4",
...     "memory_gb": 64,
...     "nexus_image": "roman-science-platform:latest"
... }
>>>
>>> # Create an event and add solutions
>>> event = submission.get_event("EVENT001")
>>>
>>> # Simple 1S1L solution
>>> solution1 = event.add_solution(
...     model_type="1S1L",
...     parameters={
...         "t0": 2459123.5,
...         "u0": 0.1,
...         "tE": 20.0,
...         "F0_S": 1000.0,
...         "F0_B": 500.0
...     }
... )
>>> solution1.log_likelihood = -1234.56
>>> solution1.n_data_points = 1250
>>> solution1.cpu_hours = 2.5
>>> solution1.relative_probability = 0.8
>>> solution1.notes = "# Simple Point Lens Fit\n\nThis is a basic 1S1L solution."
>>>
>>> # Binary lens solution with parallax
>>> solution2 = event.add_solution(
...     model_type="1S2L",
...     parameters={
...         "t0": 2459123.5,
...         "u0": 0.08,
...         "tE": 22.1,
...         "s": 1.15,
...         "q": 0.001,
...         "alpha": 45.2,
...         "piEN": 0.1,
...         "piEE": 0.05,
...         "F0_S": 1000.0,
...         "F0_B": 500.0
...     }
... )
>>> solution2.higher_order_effects = ["parallax"]
>>> solution2.t_ref = 2459123.0
>>> solution2.log_likelihood = -1189.34
>>> solution2.cpu_hours = 15.2
>>> solution2.relative_probability = 0.2
>>>
>>> # Add uncertainties with metadata
>>> solution2.parameter_uncertainties = {
...     "t0": 0.01,
...     "u0": [0.005, 0.008],  # asymmetric uncertainties
...     "tE": 0.5,
...     "piEN": 0.02,
...     "piEE": 0.01
... }
>>> solution2.uncertainty_method = "mcmc_posterior"
>>> solution2.confidence_level = 0.68  # 1-sigma confidence level
>>>
>>> # Add physical parameters with uncertainties
>>> solution2.physical_parameters = {
...     "Mtot": 0.45,
...     "D_L": 5.2,
...     "D_S": 8.1,
...     "thetaE": 0.52
... }
>>> solution2.physical_parameter_uncertainties = {
...     "Mtot": 0.08,
...     "D_L": 0.3,
...     "D_S": 0.5,
...     "thetaE": 0.02
... }
>>>
>>> # Add physical parameters (e.g. from pyLIMA / pyLIMASS)
>>> solution2.physical_parameters = {
...     "Mtot": 0.5,  # Solar masses
...     "D_L": 4.0,   # kpc
...     "thetaE": 0.5, # mas
...     "piE": 0.15    # magnitude
... }
>>> solution2.physical_parameter_uncertainties.update({
...     "Mtot": [0.45, 0.55],
...     "D_L": 0.5
... })
>>>
>>> # Save the submission
>>> submission.save("./my_submission")
>>>
>>> # Validate the submission
>>> warnings = submission.validate()
>>> if warnings:
...     print("Validation warnings:", warnings)
>>> else:
...     print("Submission is valid!")
>>>
>>> # Generate dossier
>>> from microlens_submit.dossier import generate_dashboard_html
>>> generate_dashboard_html(submission, Path("./my_submission/dossier"))

Inspecting Solutions and Resolving Duplicate Aliases (Python API)

If you re-run a notebook or script, you might accidentally reuse an alias. Aliases must be unique within each event. The example below shows how to inspect existing aliases, rename one, and optionally deactivate a duplicate.

>>> from microlens_submit import load
>>> submission = load("./my_project")
>>> event = submission.get_event("EVENT123")
>>> # Inspect aliases and IDs
>>> for sol in event.solutions.values():
...     print(sol.solution_id, sol.alias)
>>> # Rename a duplicate alias
>>> sol = event.get_solution("<solution_id>")
>>> sol.alias = "new_alias"
>>> submission.save()
>>> # Deactivate if it's a true duplicate
>>> sol.deactivate()
>>> submission.save()

Solution-Level Hardware Overrides (Python API)

If a solution is produced on a different server, you can attach hardware metadata directly to the solution without changing submission-wide info.

>>> from microlens_submit import load
>>> submission = load("./my_project")
>>> event = submission.get_event("EVENT123")
>>> sol = next(iter(event.solutions.values()))
>>> # Autofill from current environment
>>> sol.autofill_hardware_info()
>>> submission.save()
>>> # Manual override
>>> sol.hardware_info = {
...     "cpu_details": "Xeon",
...     "memory_gb": 128,
...     "nexus_image": "roman-science-platform:latest",
... }
>>> submission.save()

Dossier Generation Examples

The dossier generation system creates comprehensive HTML reports for reviewing your submission. Here are examples of the different types of pages you can generate:

Complete Dossier Generation:

>>> from microlens_submit import load
>>> from microlens_submit.dossier import generate_dashboard_html
>>> from pathlib import Path
>>>
>>> # Load your submission
>>> submission = load("./my_project")
>>>
>>> # Generate the complete dossier (dashboard + all event pages + all solution pages)
>>> generate_dashboard_html(submission, Path("./dossier_output"))
>>>
>>> # This creates:
>>> # - dossier_output/index.html (main dashboard)
>>> # - dossier_output/EVENT001.html (event page)
>>> # - dossier_output/solution_uuid.html (solution pages)
>>> # - dossier_output/full_dossier_report.html (printable version)
>>> # - dossier_output/assets/ (logos and icons)

Individual Event Page Generation:

>>> from microlens_submit.dossier import generate_event_page
>>>
>>> # Generate a single event page
>>> event = submission.get_event("EVENT001")
>>> generate_event_page(event, submission, Path("./dossier_output"))
>>>
>>> # Creates: dossier_output/EVENT001.html
>>> # This page shows:
>>> # - Event overview and metadata
>>> # - Solutions table with model types, status, and statistics
>>> # - Navigation links to individual solution pages
>>> # - Evaluator-only visualization placeholders

Individual Solution Page Generation:

>>> from microlens_submit.dossier import generate_solution_page
>>>
>>> # Generate a single solution page
>>> solution = event.get_solution("solution_uuid_here")
>>> generate_solution_page(solution, event, submission, Path("./dossier_output"))
>>>
>>> # Creates: dossier_output/solution_uuid_here.html
>>> # This page shows:
>>> # - Solution header with model type and metadata
>>> # - Parameter tables with uncertainties
>>> # - Markdown-rendered notes with syntax highlighting
>>> # - Plot placeholders and compute statistics
>>> # - Evaluator-only comparison sections

Custom Dossier Content Generation:

>>> from microlens_submit.dossier import (
...     _generate_dashboard_content,
...     _generate_event_page_content,
...     _generate_solution_page_content
... )
>>>
>>> # Generate HTML content without saving files
>>> dashboard_html = _generate_dashboard_content(submission)
>>> event_html = _generate_event_page_content(event, submission)
>>> solution_html = _generate_solution_page_content(solution, event, submission)
>>>
>>> # Custom processing or integration
>>> with open("custom_dashboard.html", "w") as f:
...     f.write(dashboard_html)

Full Dossier Report Generation:

>>> from microlens_submit.dossier import _generate_full_dossier_report_html
>>>
>>> # Generate a comprehensive single-file report
>>> _generate_full_dossier_report_html(submission, Path("./dossier_output"))
>>>
>>> # Creates: dossier_output/full_dossier_report.html
>>> # This single file contains:
>>> # - Complete dashboard content
>>> # - All event pages
>>> # - All active solution pages
>>> # - Section dividers and navigation
>>> # - Print-friendly formatting

Dossier Features:

The generated dossier includes:

• Dashboard: Overview with submission statistics, progress tracking, and event summaries

• Event Pages: Detailed views of each event with solution tables and metadata

• Solution Pages: Individual solution details with parameters, notes, and visualizations

• Navigation: Links between pages and back to dashboard

• Styling: Professional Tailwind CSS design with RGES-PIT branding

• Notes Rendering: Markdown support with syntax highlighting for code blocks

• GitHub Integration: Commit links when repository information is available

• Responsive Design: Works on desktop and mobile devices

• Print Support: Optimized for printing and PDF generation

CLI Dossier Generation:

# Generate complete dossier
microlens-submit generate-dossier ./my_project

# Generate dossier for specific event only
microlens-submit generate-dossier ./my_project --event-id EVENT001

# Generate dossier for specific solution only
microlens-submit generate-dossier ./my_project --solution-id solution_uuid_here

# Generate with priority flags (for advanced users)
microlens-submit generate-dossier ./my_project --priority-flags

Note

This package stores data in JSON and performs extensive validation to ensure correctness. Dossier generation produces printable HTML reports with Tailwind CSS styling and syntax highlighted notes.