{"id":27650234,"url":"https://github.com/inventwithdean/flow-match-3d-gaussian","last_synced_at":"2025-07-25T00:35:25.742Z","repository":{"id":284957514,"uuid":"956616609","full_name":"inventwithdean/flow-match-3d-gaussian","owner":"inventwithdean","description":"Implementation of Flow Matching to convert standard normal distribution to multi-modal gaussian","archived":false,"fork":false,"pushed_at":"2025-03-28T15:17:18.000Z","size":5846,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-24T03:36:33.999Z","etag":null,"topics":["flowmatching","gaussian","machine-learning","vectorfield"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inventwithdean.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-28T14:59:48.000Z","updated_at":"2025-03-28T15:17:22.000Z","dependencies_parsed_at":"2025-03-28T16:33:24.706Z","dependency_job_id":null,"html_url":"https://github.com/inventwithdean/flow-match-3d-gaussian","commit_stats":null,"previous_names":["inventwithdean/flow-match-3d-gaussian"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/inventwithdean/flow-match-3d-gaussian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventwithdean%2Fflow-match-3d-gaussian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventwithdean%2Fflow-match-3d-gaussian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventwithdean%2Fflow-match-3d-gaussian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventwithdean%2Fflow-match-3d-gaussian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inventwithdean","download_url":"https://codeload.github.com/inventwithdean/flow-match-3d-gaussian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inventwithdean%2Fflow-match-3d-gaussian/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266931149,"owners_count":24008282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flowmatching","gaussian","machine-learning","vectorfield"],"created_at":"2025-04-24T03:33:09.310Z","updated_at":"2025-07-25T00:35:25.734Z","avatar_url":"https://github.com/inventwithdean.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flow-Match-3d-Gaussian: Transforming a Gaussian into a Multi-Modal Gaussian with Flow Matching\n\n![simulation](https://github.com/user-attachments/assets/a594c240-067b-400d-a9c7-1f27c9cbec5e)\n\nThis repository implements **flow matching** to transform a 3D Gaussian distribution into a multi-modal Gaussian distribution using a neural network to approximate the marginal vector field. The transformation is achieved by simulating particle flow via the Euler method, and the results are visualized in 3D to show the evolution of the distribution over time.\n\n## Project Overview\n\nFlow matching is a generative modeling technique that learns a vector field to transport samples from a source distribution to a target distribution. In this project:\n\n- **Source Distribution**: A 3D standard Gaussian $`\\mathcal{N}(0, I)`$.\n- **Target Distribution**: A multi-modal Gaussian distribution in 3D space.\n- **Method**: A neural network (MLP) parameterizes the vector field, which is trained to minimize the difference between the predicted and true velocities along the flow path.\n- **Simulation**: The learned vector field is used to simulate particle trajectories from $`t=0`$ to $`t=1`$ using the Euler method.\n- **Visualization**: 3D scatter plots illustrate the transformation of the distribution.\n\nThis project demonstrates the power of flow matching for distribution transformation and provides a clear, visual way to understand the process.\n\n\n### Training Loss\n\nThe training loss curve shows the convergence of the neural network as it learns the vector field:\n\n![loss_curve](https://github.com/user-attachments/assets/eba5c125-fb7e-4c94-9964-35e3cbda7dd8)\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11 or higher\n- PyTorch\n- Matplotlib\n- NumPy\n- tqdm (for progress bars)\n\n### Setup\n\nClone the repository:\n\n```bash\ngit clone https://github.com/inventwithdean/flow-match-3d-gaussian.git\ncd flow-match-gaussian\n```\n\n## Usage\n\n### 1. Train the Model\n\nRun the training script to learn the vector field:\n\n```bash\npython train.py\n```\n\nThis will:\n\n- Sample points from the target multi-modal Gaussian distribution.\n- Train the neural network to approximate the vector field.\n- Save the trained model's state dict as `vf`.\n- Generate a loss curve plot (`loss_curve.png`).\n\n### 2. Generate Visualizations\n\nRun the visualization script to simulate and visualize the particle flow:\n\n```bash\npython simulate.py\n```\n\nThis will:\n\n- Load the trained model.\n- Simulate the flow of 3,000 particles from $`t=0`$ to $`t=1`$.\n- Save the simulation video as `out.mp4`.\n\n## Implementation Details\n\n- **Dataset**: The target distribution is a multi-modal Gaussian, created by sampling from a mixture of Gaussians in 3D space.\n- **Model**: A multi-layer perceptron (MLP) with ReLU activations, taking 4 inputs ($`x, y, z, t`$) and outputting a 3D velocity vector.\n- **Training**: The vector field is trained using flow matching, minimizing the MSE between the predicted and true velocities along straight-line paths.\n- **Simulation**: The Euler method is used to integrate the ODE:\n\n  $`\\frac{dx}{dt} = v(x, t)`$\n\n  from $`t=0`$ to $`t=1`$ .\n\n- **Visualization**: Matplotlib is used to create 3D scatter plots of particle positions at various time steps.\n\n## Future Work\n\n- Experiment with more complex target distributions (e.g., 3D shapes like a torus).\n- Implement advanced ODE solvers (e.g., using `torchdiffeq`) for more accurate simulations.\n- Explore conditional flow matching for controlled transformations.\n\n## Contributing\n\nContributions are welcome! If you have ideas for improvements or new features, please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Acknowledgments\n\n- Inspired by recent work on flow matching for generative modeling.\n- Thanks to the PyTorch and Matplotlib communities for their excellent tools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finventwithdean%2Fflow-match-3d-gaussian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finventwithdean%2Fflow-match-3d-gaussian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finventwithdean%2Fflow-match-3d-gaussian/lists"}