From a3a6c97d562e7b0f879a3d9ffb7e4e28c8ec089e Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Fri, 12 Jul 2024 10:28:18 -0700
Subject: [PATCH] Add model attributes objective states to docs

---
 docs/reference/models.rst    |  9 +++++++++
 dwave/optimization/model.pxd | 30 ++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/docs/reference/models.rst b/docs/reference/models.rst
index 08febf31..4f3052c5 100644
--- a/docs/reference/models.rst
+++ b/docs/reference/models.rst
@@ -19,6 +19,15 @@ Model Class
 
 .. autoclass:: Model
 
+Model Attributes 
+----------------
+
+.. autosummary::
+    :toctree: generated/
+
+    ~Model.objective
+    ~Model.states
+
 Model Primitives  
 ----------------
 
diff --git a/dwave/optimization/model.pxd b/dwave/optimization/model.pxd
index 365335b9..96f43b73 100644
--- a/dwave/optimization/model.pxd
+++ b/dwave/optimization/model.pxd
@@ -40,8 +40,38 @@ cdef class Model:
     cdef cppGraph _graph
 
     cdef readonly object objective  # todo: cdef ArraySymbol?
+    """Objective to be minimized.
+
+    Examples:
+        This example prints the value of the objective of a model representing 
+        the simple polynomial, :math:`y = i^2 - 4i`, for a state with value 
+        :math:`i=2.0`. 
+
+        >>> from dwave.optimization import Model
+        ...
+        >>> model = Model()
+        >>> i = model.integer(lower_bound=-5, upper_bound=5)
+        >>> c = model.constant(4)
+        >>> y = i**2 - c*i
+        >>> model.minimize(y) 
+        >>> with model.lock():
+        ...     model.states.resize(1)
+        ...     i.set_state(0, 2.0)
+        ...     print(f"Objective = {model.objective.state(0)}")
+        Objective = -4.0
+    """
 
     cdef readonly States states
+    """States of the model.
+
+    :ref:`States <intro_optimization_states>` represent assignments of values
+    to a symbol.
+
+    See also:
+        :ref:`States methods <optimization_models>` such as 
+        :meth:`~dwave.optimization.model.States.size` and 
+        :meth:`~dwave.optimization.model.States.resize`.
+    """
 
     # The number of times "lock()" has been called.
     cdef readonly Py_ssize_t _lock_count