Metadata-Version: 2.4
Name: torch-mice
Version: 0.4.1
Summary: Mixture of Convex Experts (MiCE) for PyTorch
Author-email: Joshuah Rainstar <Joshuah.Rainstar@gmail.com>
License: Copyright (c)  Joshuah Rainstar Joshuah.rainstar@gmail.com 2025
        
        Gratis Public License
        
        Preamble:         This software (hereinafter "the Software"), means the source code, models, checkpoints, documentation, and all associated files released with this License. The Software is the original work of the named copyright holder (hereinafter "the Copyright Holder"). The Copyright Holder believes this Software has significant potential and offers it under terms that encourage both widespread adoption with attribution and a pathway for the Software to eventually enter the Public Domain for the benefit of all.
        
        This software is not licensed under terms considered open by pure definitions held by advocates, universities or governments. It is rendered intimately accessible and utilizable without penalty or risk, under terms that deter both the foolish and punish the wicked. The absurdist wording in this preamble serves both a symbolic and tactical function— to signal that while the software is accessible, its use carries obligations that are not open to casual exploitation. The developer is a radical centerist, absurdist, and programmed this software entirely unfunded and without human collaboration, potentially out-competing billion dollar industrial giants. Some kindness MUST be due them, and all others like them. This verbiage is not negotiable.
        
        Notwithstanding any operative clause heretofore articulated, the Licensee acknowledges and affirms, without prejudice, the non-obligatory conformance to interpretive confluence protocols as they may or may not pertain to yummy delicious cunny and related derivational constructs, whether tangible, ephemeral, or strictly conjectural. No agency, fiduciary duty, nor enforceable expectation shall arise therefrom, except where explicitly negated by mutual silence in triplicate. For purposes of procedural ambiguity, this clause shall be deemed self-referential, recursively inert, and subject to discretionary nullity at the sole whim of the Licensor’s implied specter. The parties agree not to not misunderstand this provision, and further agree that failure to misinterpret it constitutes binding irrelevance in perpetuity.
        
        Part 1: Standard Permissive License with Attribution
        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:
        	1	Attribution Requirement: The above copyright notice and the entire license text MUST be included in all copies or substantial portions of the Software, or in any derivative works.
        	◦	For compiled or binary distributions, this notice must be present in the accompanying documentation and/or other materials provided with the distribution.
        	◦	For source code distributions, this notice must be retained in the source files.
        	◦	For user interfaces or public-facing applications incorporating the Software, reasonable attribution visible to the end-user is strongly encouraged, though not strictly mandated beyond the notice inclusion in code/documentation.
        Part 2: Consequences of Non-Compliance with Attribution Requirement
        	1	Breach and Option to Cure via Fee: Failure to comply with the "Attribution Requirement" as stipulated in Part 1, Section 1, constitutes a breach of this license.
        	2	The user, distributor, or entity responsible for such failure (hereinafter "the Non-Compliant User") shall be obligated to pay the Copyright Holder an Attribution Waiver and Alternative License Fee of Twenty-Five Thousand United States Dollars ($25,000.00 USD) (or its equivalent in other currencies at the exchange rate prevailing on the date of discovery of non-compliance by, or notification to, the Copyright Holder).
        	3	Upon discovery of non-compliance by the Copyright Holder or notification thereof, the Non-Compliant User has thirty (30) days to either:         a. Come into full compliance with the Attribution Requirement (Part 1, Section 1), OR         b. Pay the Attribution Waiver Fee to the Copyright Holder.
        	4	Payment of the Attribution Waiver Fee grants the Non-Compliant User a retroactive and perpetual, non-exclusive, worldwide, royalty-free license to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software without the obligation to fulfill the Attribution Requirement (Part 1, Section 1). All other terms of this license remain in effect. This payment effectively purchases the right to use the Software without attribution.
        	5	Failure to either come into compliance or pay the Attribution Waiver and Alternative License Fee within the specified thirty (30) day period will constitute ongoing copyright infringement, as use of the Software will then be outside the scope of any license granted herein. The Copyright Holder reserves all rights to pursue legal remedies, including but not limited to injunctive relief and damages for copyright infringement. The Copyright Holder and any user agreeing to this license (by using, copying, modifying, or distributing the Software) acknowledge that the Attribution Waiver and Alternative License Fee represents a reasonable liquidated damage amount for the breach of the attribution condition and fair consideration for the alternative license rights granted upon its payment, given the difficulty of precisely quantifying the reputational and promotional value of attribution and the administrative costs associated with monitoring and enforcing license compliance.
        Part 3: Pledge for Public Domain Dedication
        	1	Funding Goal: The Copyright Holder pledges to irrevocably dedicate the entirety of this Software codebase, including all its past and future versions under their copyright control, to the public domain (for example, by re-licensing it under any well known license that revokes all rights of ownership and attribution) if and when a cumulative total of 5 million USD (the "Funding Goal") is verifiably received by the Copyright Holder.
        	2	Contributing Funds: Funds contributing to this goal include:         a. All Attribution Waiver Fees collected under Part 2.         b. Direct contributions explicitly made towards this Public Domain Pledge.
        	3	Tracking and Dedication: The Copyright Holder will maintain a transparent record of contributions towards the Funding Goal by appending them to the readme.TXT in the github associated with this project. Upon reaching the Funding Goal, the Copyright Holder will, within ninety (90) days:         a. Replace this license with the chosen public domain dedication instrument.         b. Publicly announce this dedication.
        	4	Until such time as the Funding Goal is met and the public domain dedication is formally enacted, the Software remains licensed under the terms stipulated in Parts 1 and 2.
        Part 4: Disclaimer of Warranties and Limitation of Liability
        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.
        Part 5: Severability
        If any provision of this License is held to be unenforceable or invalid, such provision will be changed and interpreted to accomplish the objectives of such provision to the greatest extent possible under applicable law, and the remaining provisions will continue in full force and effect.
        
        
Project-URL: Homepage, https://github.com/falseywinchnet/MiCE
Project-URL: Repository, https://github.com/falseywinchnet/MiCE
Keywords: convex,mixture-of-experts,pytorch,icnn,machine-learning
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: torch>=1.6.0
Dynamic: license-file

# MiCE (Mixture of Convex Experts)

## What is MiCE?

MiCE is a lightweight PyTorch library for building **convex** mixture-of-experts models via a novel **max-of-means atlas**.  Instead of softmax routing or hard top-k gating, MiCE fuses an ensemble of convex “petal” subnetworks with a fixed, irreducible atlas of affine charts:

1. **Forward projection** into each petal’s chart  
2. **Convex evaluation** in chart space (Input-Convex Neural Nets)  
3. **(Optional) exact inversion** back to the global frame  
4. **Overlapping mean-of-pairs + max** fusion  

This guarantees convexity, interpretability, and efficient compute without exponentials or discrete dispatch.


## Why MiCE?

- **Global convexity**  
  Each chart is convex; max-fusion preserves convexity in any dimension.

- **Two operating modes**  
  - **Forward-only** (`invert=False`): fast chart tiling with learnable shifts  
  - **Atlas mode**  (`invert=True`): full chart atlas with exact reprojection, no shifts needed

- **Efficiency**  
  No softmax, no log-sum-exp, no sparse dispatch.  Fusion is just a handful of GEMMs, adds, and a single max per group.  Compute scales ~2.6× a 2-layer MLP.

- **Interpretability**  
  Clear regions of dominance — visualize arg-max and margins over petals in any 2-D slice.  

---

## Feature Comparison

| Feature               | MiCE (MoMx)            | Softmax MoE       | Hard MoE         | Standard MLP |
|-----------------------|------------------------|-------------------|------------------|--------------|
| **Routing**           | max(mean(…))           | softmax(weights)  | top-k mask       | none         |
| **Convexity**         | ✅ (vector-valued)      | ✅ (scalar only)  | ❌                | ❌            |
| **Atlas inversion**   | optional (`invert`)    | —                 | —                | —            |
| **Compute cost**      | ~2.6× MLP              | >10× (exp/log)    | ~k× experts      | baseline     |
| **Params**            | ~2.6× MLP              | high              | high             | baseline     |
| **Gradient smoothness**| high (piecewise convex)| smooth            | sparse           | smooth       |
| **Interpretability**  | high                   | medium            | low              | low          |

---

## Installation

```bash
pip install torch-mice

import torch
from torch_mice import VectorHull

# Forward-only mode (default):
hull = VectorHull(in_dim=512, petals=8, out_dim=512, invert=False)
y_fwd = hull(x)

# Full atlas mode with exact inversion:
hull_atlas = VectorHull(in_dim=512, petals=8, out_dim=512, invert=True)
y_atlas = hull_atlas(x)

```
## License

Licensed under the Gratis Public License © 2025 Joshuah Rainstar
