microlens-submit 0.12.1__tar.gz

microlens_submit-0.12.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Amber Malpas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

microlens_submit-0.12.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include microlens_submit/assets/rges-pit_logo.png
+include microlens_submit/assets/github-desktop_logo.png 

microlens_submit-0.12.1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: microlens-submit
+Version: 0.12.1
+Summary: A stateful submission toolkit for the Microlensing Data Challenge.
+Author-email: Amber Malpas <malpas.1@osu.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/AmberLee2427/microlens-submit
+Project-URL: Repository, https://github.com/AmberLee2427/microlens-submit
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: markdown>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx_rtd_theme; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://github.com/AmberLee2427/microlens-submit">
+    <img src="./microlens_submit/assets/rges-pit_logo.png" alt="logo" width="300"/>
+  </a>
+</p>
+
+<h1 align="center">microlens-submit</h1>
+
+*A stateful submission toolkit for the RGES-PIT Microlensing Data Challenge.*
+
+[![PyPI - v0.12.1](https://img.shields.io/pypi/v/microlens-submit.svg)](https://pypi.org/project/microlens-submit/)
+[![CI](https://github.com/AmberLee2427/microlens-submit/actions/workflows/ci.yml/badge.svg)](https://github.com/AmberLee2427/microlens-submit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<br>
+
+`microlens-submit` provides a robust, version-controlled workflow for managing, validating, and packaging your challenge submission over a long period. It supports both a programmatic Python API and a full-featured Command Line Interface (CLI) for language-agnostic use.
+
+Full documentation is hosted on [Read the Docs](https://microlens-submit.readthedocs.io/en/latest/). A comprehensive tutorial notebook is available at `docs/Submission_Tool_Tutorial.ipynb`. Challenge participants who prefer not to use this tool can consult [SUBMISSION_MANUAL.md](SUBMISSION_MANUAL.md) for the manual submission format.
+
+## Key Features
+
+* **Persistent Projects:** Treat your submission as a local project that you can load, edit, and save over weeks or months.
+* **Python API & CLI:** Use the tool directly in your Python analysis scripts or via the command line.
+* **Solution Management:** Easily add, update, and deactivate degenerate solutions for any event without losing your work history.
+* **Active Solution Control:** Quickly list just the active solutions or mark
+  all solutions inactive in one call.
+* **Automatic Validation:** Aggressive data validation powered by Pydantic ensures your submission is always compliant with the challenge rules.
+* **Parameter Validation:** Centralized validation logic checks parameter completeness, types, and physical consistency based on model type and higher-order effects.
+* **Rich Documentation:** Notes field supports Markdown formatting for creating detailed, structured documentation and submission dossiers.
+* **Environment Capture:** Automatically records your Python dependencies for each specific model fit, ensuring reproducibility.
+* **Optional Posterior Storage:** Record the path to posterior samples for any solution.
+* **Simple Export:** Packages all your active solutions into a clean, standardized `.zip` archive for final submission.
+
+## Installation
+
+This package is pre-release. It is currently available on TestPyPI:
+
+```bash
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple microlens-submit==0.12.0-dev
+```
+
+The package will be available on PyPI:
+
+```bash
+pip install microlens-submit
+```
+
+### Quickstart Using the Command Line Interface (CLI)
+
+The CLI is the recommended way to interact with your submission project.
+
+You can pass ``--no-color`` to any command if your terminal does not support ANSI colors.
+
+1. Initialize your project: `microlens-submit init --team-name "Planet Pounders" --tier "advanced"`
+2. Add a new solution to an event:
+   ```bash
+   microlens-submit add-solution ogle-2025-blg-0042 1S2L \
+       --param t0=555.5 \
+       --param u0=0.1 \
+       --param tE=25.0 \
+       --notes "This is a great fit!"
+   ```
+   Model types must be one of `1S1L`, `1S2L`, `2S1L`, `2S2L`, `1S3L`, `2S3L`, or `other`.
+   This will create a new solution and print its unique `solution_id`.
+   You can run the same command with `--dry-run` first to verify the
+   parsed input without saving anything.
+3. Deactivate a solution that didn't work out: `microlens-submit deactivate <solution_id>`
+4. List all solutions for an event: `microlens-submit list-solutions ogle-2025-blg-0042`
+5. Validate solutions and check for issues: `microlens-submit validate-solution <solution_id>`
+6. Export your final submission: `microlens-submit export final_submission.zip`
+
+**Note:** When you add a solution, it's automatically validated and any warnings are displayed. Use `--dry-run` to check validation without saving.
+
+### Using the Python API
+
+For those who want to integrate the tool directly into their Python analysis pipeline.
+
+```python
+import microlens_submit
+
+# Load or create the project
+sub = microlens_submit.load(project_path="./my_challenge_submission")
+sub.team_name = "Planet Pounders"
+sub.tier = "advanced"
+
+# Get an event and add a solution
+evt = sub.get_event("ogle-2025-blg-0042")
+params = {"t0": 555.5, "u0": 0.1, "tE": 25.0}
+sol = evt.add_solution(model_type="1S2L", parameters=params)
+
+# Record compute info for this specific run
+sol.set_compute_info(cpu_hours=15.5)
+sol.notes = "This fit was generated from our Python script."
+
+# Save progress to disk
+sub.save()
+
+# When ready, export the final package
+sub.export("final_submission.zip")
+```
+
+## Development
+
+The full development plan can be found in agents.md. Contributions are welcome!
+
+To build and test this project, the development environment needs the following Python libraries. You can provide these to Codex or set up a `requirements-dev.txt` file.
+
+### Core Dependencies:
+* **`typer[all]`**: For building the powerful command-line interface. The `[all]` extra ensures shell completion support is included.
+* **`pydantic`**: For aggressive data validation and settings management.
+
+### Testing Dependencies:
+* **`pytest`**: The standard framework for testing Python code.
+* **`pytest-cov`**: To measure test coverage.
+
+### Packaging & Distribution Dependencies:
+* **`build`**: For building the package from the `pyproject.toml` file.
+* **`twine`**: For uploading the final package to PyPI.
+
+## Citation
+
+If you use **microlens-submit** in your research, please cite the project using
+the metadata provided in the `CITATION.cff` file. Most reference managers can
+import this file directly.
+

microlens_submit-0.12.1/README.md

@@ -0,0 +1,126 @@
+<p align="center">
+  <a href="https://github.com/AmberLee2427/microlens-submit">
+    <img src="./microlens_submit/assets/rges-pit_logo.png" alt="logo" width="300"/>
+  </a>
+</p>
+
+<h1 align="center">microlens-submit</h1>
+
+*A stateful submission toolkit for the RGES-PIT Microlensing Data Challenge.*
+
+[![PyPI - v0.12.1](https://img.shields.io/pypi/v/microlens-submit.svg)](https://pypi.org/project/microlens-submit/)
+[![CI](https://github.com/AmberLee2427/microlens-submit/actions/workflows/ci.yml/badge.svg)](https://github.com/AmberLee2427/microlens-submit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<br>
+
+`microlens-submit` provides a robust, version-controlled workflow for managing, validating, and packaging your challenge submission over a long period. It supports both a programmatic Python API and a full-featured Command Line Interface (CLI) for language-agnostic use.
+
+Full documentation is hosted on [Read the Docs](https://microlens-submit.readthedocs.io/en/latest/). A comprehensive tutorial notebook is available at `docs/Submission_Tool_Tutorial.ipynb`. Challenge participants who prefer not to use this tool can consult [SUBMISSION_MANUAL.md](SUBMISSION_MANUAL.md) for the manual submission format.
+
+## Key Features
+
+* **Persistent Projects:** Treat your submission as a local project that you can load, edit, and save over weeks or months.
+* **Python API & CLI:** Use the tool directly in your Python analysis scripts or via the command line.
+* **Solution Management:** Easily add, update, and deactivate degenerate solutions for any event without losing your work history.
+* **Active Solution Control:** Quickly list just the active solutions or mark
+  all solutions inactive in one call.
+* **Automatic Validation:** Aggressive data validation powered by Pydantic ensures your submission is always compliant with the challenge rules.
+* **Parameter Validation:** Centralized validation logic checks parameter completeness, types, and physical consistency based on model type and higher-order effects.
+* **Rich Documentation:** Notes field supports Markdown formatting for creating detailed, structured documentation and submission dossiers.
+* **Environment Capture:** Automatically records your Python dependencies for each specific model fit, ensuring reproducibility.
+* **Optional Posterior Storage:** Record the path to posterior samples for any solution.
+* **Simple Export:** Packages all your active solutions into a clean, standardized `.zip` archive for final submission.
+
+## Installation
+
+This package is pre-release. It is currently available on TestPyPI:
+
+```bash
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple microlens-submit==0.12.0-dev
+```
+
+The package will be available on PyPI:
+
+```bash
+pip install microlens-submit
+```
+
+### Quickstart Using the Command Line Interface (CLI)
+
+The CLI is the recommended way to interact with your submission project.
+
+You can pass ``--no-color`` to any command if your terminal does not support ANSI colors.
+
+1. Initialize your project: `microlens-submit init --team-name "Planet Pounders" --tier "advanced"`
+2. Add a new solution to an event:
+   ```bash
+   microlens-submit add-solution ogle-2025-blg-0042 1S2L \
+       --param t0=555.5 \
+       --param u0=0.1 \
+       --param tE=25.0 \
+       --notes "This is a great fit!"
+   ```
+   Model types must be one of `1S1L`, `1S2L`, `2S1L`, `2S2L`, `1S3L`, `2S3L`, or `other`.
+   This will create a new solution and print its unique `solution_id`.
+   You can run the same command with `--dry-run` first to verify the
+   parsed input without saving anything.
+3. Deactivate a solution that didn't work out: `microlens-submit deactivate <solution_id>`
+4. List all solutions for an event: `microlens-submit list-solutions ogle-2025-blg-0042`
+5. Validate solutions and check for issues: `microlens-submit validate-solution <solution_id>`
+6. Export your final submission: `microlens-submit export final_submission.zip`
+
+**Note:** When you add a solution, it's automatically validated and any warnings are displayed. Use `--dry-run` to check validation without saving.
+
+### Using the Python API
+
+For those who want to integrate the tool directly into their Python analysis pipeline.
+
+```python
+import microlens_submit
+
+# Load or create the project
+sub = microlens_submit.load(project_path="./my_challenge_submission")
+sub.team_name = "Planet Pounders"
+sub.tier = "advanced"
+
+# Get an event and add a solution
+evt = sub.get_event("ogle-2025-blg-0042")
+params = {"t0": 555.5, "u0": 0.1, "tE": 25.0}
+sol = evt.add_solution(model_type="1S2L", parameters=params)
+
+# Record compute info for this specific run
+sol.set_compute_info(cpu_hours=15.5)
+sol.notes = "This fit was generated from our Python script."
+
+# Save progress to disk
+sub.save()
+
+# When ready, export the final package
+sub.export("final_submission.zip")
+```
+
+## Development
+
+The full development plan can be found in agents.md. Contributions are welcome!
+
+To build and test this project, the development environment needs the following Python libraries. You can provide these to Codex or set up a `requirements-dev.txt` file.
+
+### Core Dependencies:
+* **`typer[all]`**: For building the powerful command-line interface. The `[all]` extra ensures shell completion support is included.
+* **`pydantic`**: For aggressive data validation and settings management.
+
+### Testing Dependencies:
+* **`pytest`**: The standard framework for testing Python code.
+* **`pytest-cov`**: To measure test coverage.
+
+### Packaging & Distribution Dependencies:
+* **`build`**: For building the package from the `pyproject.toml` file.
+* **`twine`**: For uploading the final package to PyPI.
+
+## Citation
+
+If you use **microlens-submit** in your research, please cite the project using
+the metadata provided in the `CITATION.cff` file. Most reference managers can
+import this file directly.
+

microlens_submit-0.12.1/microlens_submit/__init__.py

@@ -0,0 +1,163 @@
+"""microlens-submit: A stateful submission toolkit for the Microlensing Data Challenge.
+
+This package provides a comprehensive toolkit for managing and submitting microlensing
+data challenge solutions. It offers both programmatic API access and command-line
+interface for creating, validating, and exporting microlensing submissions.
+
+**Core Features:**
+- Project initialization and management
+- Solution creation and parameter validation
+- Submission validation and completeness checking
+- HTML dossier generation with rich visualizations
+- Export functionality for challenge submission
+- Command-line interface for all operations
+
+**Main Components:**
+- Submission: Top-level container for all submission data
+- Event: Container for microlensing events and their solutions
+- Solution: Individual microlensing solutions with parameters and metadata
+- Validation: Comprehensive parameter and submission validation
+- Dossier: HTML report generation with Tailwind CSS styling
+
+**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 = "advanced"
+    >>> 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 "advanced" ./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
+
+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 = "advanced"
+    >>> 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
+    >>> 
+    >>> # 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"))
+
+Note:
+    This package is designed for the Microlensing Data Challenge and provides
+    comprehensive tools for managing submission data. All data is stored in
+    JSON format for portability and human readability. The package includes
+    extensive validation to ensure submission completeness and correctness.
+    The HTML dossier generation creates professional, printable reports with
+    Tailwind CSS styling and syntax-highlighted markdown notes.
+"""
+
+__version__ = "0.12.1"
+
+from .api import Event, Solution, Submission, load
+
+__all__ = ["Event", "Solution", "Submission", "load"]