Opossum

<h1>Opossum</h1>

<p>Opossum is an optimization plug-in for Grasshopper (for Rhino) that implements model-based and evolutionary optimization algorithms for single- and multi-objective problems. The plugin integrates GUI components into Grasshopper to configure runs, visualize results, and persist optimizer state inside Grasshopper documents.</p>

<p>This repository contains a .NET/Grasshopper plugin project targeting .NET Framework 4.8.</p>

<h2>Highlights</h2>
<ul>
<li>Model-based single-objective optimization (RBFOpt)</li>
<li>Evolutionary single-objective optimizer (CMA-ES)</li>
<li>Multi-objective RBFMOpt optimizer</li>
<li>Multiple multi-objective algorithms via pygmo</li>
<li>Interactive Grasshopper window and result serialization</li>
</ul>

<h2>Notable folders and classes</h2>
<ul>
<li><code>Opossum2_0_Proto_A/</code> — main plugin project. Contains component classes, UI windows, serialization utilities, and resources.
<ul>
<li><code>OptComponent.cs</code> — main Grasshopper component implementation: UI hooks, serialization/deserialization, and component registration.</li>
<li><code>Resources/</code> — embedded icons, images, and other resource files used by the plugin.</li>
<li><code>Solver/</code> — optimization solver interface and implementations (RBFOpt, pygmo, etc.).</li>
</ul>
</li>
</ul>

<h2>Requirements and dependencies</h2>

<h3>Development / build</h3>
<ul>
<li>Microsoft Visual Studio (2017, 2019, or 2022) with .NET Framework 4.8 targeting pack installed.</li>
<li>The Grasshopper and Rhino SDK (or runtime assemblies) to resolve references to <code>Grasshopper.dll</code>, <code>GH_IO.dll</code>, and <code>RhinoCommon.dll</code>.</li>
</ul>

<h3>Runtime</h3>
<ul>
<li>Rhino with a matching version of Grasshopper (the plugin runs inside Grasshopper).</li>
<li>Opossum installed via Food4Rhino or PackageManager to obtain Python backend and dependencies.</li>
</ul>

<p>The plugin expects to be loaded inside Grasshopper; it does not run as a standalone .NET application.</p>

<h2>Build instructions</h2>
<ol>
<li>Open the solution in Visual Studio.</li>
<li>Ensure project references to Rhino/Grasshopper assemblies are valid (point to the installed Rhino/Grasshopper runtime or SDK). These references are typically not committed and must be resolved on your machine.</li>
<li>Restore NuGet packages.</li>
<li>Build the <code>Opossum2_0_Proto_A</code> project in <code>Debug</code> or <code>Release</code> configuration.</li>
</ol>

<p>The produced assembly will generally be a <code>.dll</code> file or <code>.gha</code> (Grasshopper plugin), depending on how the project is configured.</p>

<h2>Install and run</h2>
<ol>
<li>Install Opossum from Food4Rhino or PackageManager.</li>
<li>Copy the built <code>.gha</code>/<code>.dll</code> to Grasshopper's Components folder.</li>
<li>Restart Rhino/Grasshopper.</li>
<li>The plugin registers its component(s) under the category set in the component registration (for example <code>Params</code> -> <code>Util</code>).</li>
</ol>

<h2>Usage notes</h2>
<ul>
<li><code>OptComponent</code> manages component serialization (stores GUIDs of linked variables, simulators, and objectives) so saved Grasshopper files keep references and results across sessions.</li>
<li>Results can be serialized into the Grasshopper document and later reloaded. The component distinguishes whether results were produced by the optimizer or loaded from a file.</li>
<li>If your installation uses an external Python optimizer, verify that the Python environment is accessible from the host machine and any interop code is configured to find the Python interpreter and libraries.</li>
</ul>

<h2>Development notes</h2>
<ul>
<li>To debug the plugin, run Rhino and attach the Visual Studio debugger to the Rhino process.</li>
<li>When changing serialization formats (chunk names, GUIDs, or data layout), be careful to preserve compatibility with existing saved Grasshopper documents or provide migration logic.</li>
<li>UI classes (windows) are created at runtime and registered with Grasshopper's <code>FormShepard</code>; ensure proper disposal to avoid resource leaks.</li>
</ul>