[Draft] TODOs for Better sim.lattice

Author: ax3l

src/ImpactX.H

@@ -142,7 +142,18 @@ namespace impactx
          */
         void ResizeMesh ();
 
-        /** these are elements defining the accelerator lattice */
+        /** Elements defining the accelerator lattice (stored by value).
+         *
+         * Python exposes this as sim.lattice; pybind append/extend copy C++ lattice elements
+         * into this list — not Python reference identity. See KnownElementsList in elements.cpp.
+         *
+         * TODO: own std::shared_ptr<SimulationLifetime> here (create in ImpactX ctor, i.e.
+         *       before init_grids()) so elements created early from Python can safely hold
+         *       std::weak_ptr to it.
+         * TODO: track readiness on the token (e.g. amrex_ready=false until init_grids(),
+         *       then true) for clear host-vs-GPU usage errors.
+         * TODO: invalidate/reset token in finalize() for use-after-finalize checks.
+         */
         std::list<elements::KnownElements> m_lattice;
 
         /** Was init_grids already called?

src/python/elements.cpp

@@ -2664,6 +2664,20 @@ void init_elements(py::module& m)
 
 
     // all-element type list
+    //
+    // Ref semantics (Python vs this binding): a Python list keeps references to mutable
+    // objects, but here each append/extend materializes a C++ KnownElements value in this
+    // list (copy or move). The original Python handle is a separate object unless we
+    // intentionally bind shared ownership (e.g. std::shared_ptr element types later).
+    //
+    // TODO: register GPU-heavy element types with py::class_<T, std::shared_ptr<T>> and
+    //       store std::shared_ptr in KnownElements (or a thin wrapper) so append/extend
+    //       match Python mutable-object reference semantics.
+    // TODO: optional weak_ptr to a SimulationLifetime/session object on elements for
+    //       clear errors on use after sim.finalize() (coordinate with pyAMReX session work).
+    //       The shared token should be created with ImpactX construction (not init_grids),
+    //       and expose readiness (amrex_ready) so pre-init objects can exist but reject
+    //       GPU use until sim.init_grids() makes AMReX ready.
     using KnownElementsList = std::list<KnownElements>;
     py::class_<KnownElementsList> kel(me, "KnownElementsList");
     kel