From d798f9b666bd59da8c0696535e369f782f0d1745 Mon Sep 17 00:00:00 2001
From: Iglesia Dolci <daia.dolci@gmail.com>
Date: Fri, 28 Jun 2024 11:57:20 +0100
Subject: [PATCH 1/6] Get OverloadType PETSc.vec

---
 pyadjoint/adjfloat.py        |  5 +++++
 pyadjoint/overloaded_type.py | 11 +++++++++++
 2 files changed, 16 insertions(+)

diff --git a/pyadjoint/adjfloat.py b/pyadjoint/adjfloat.py
index e92e2a05..482c2b83 100644
--- a/pyadjoint/adjfloat.py
+++ b/pyadjoint/adjfloat.py
@@ -130,6 +130,11 @@ def _ad_str(self):
         """Return the string of the taped value of this variable."""
         return str(self.block_variable.saved_output)
 
+    def _ad_petsc_vec(self):
+        raise NotImplementedError(
+            "It requires more thought to return a PETSc Vec from `AdjFloat`"
+        )
+
 
 _exp = math.exp
 _log = math.log
diff --git a/pyadjoint/overloaded_type.py b/pyadjoint/overloaded_type.py
index a6a02f68..e6e392d4 100644
--- a/pyadjoint/overloaded_type.py
+++ b/pyadjoint/overloaded_type.py
@@ -320,6 +320,17 @@ def _ad_str(self):
         """
         return str(self)
 
+    def _ad_petsc_vec(self):
+        """This method must be overridden.
+
+        The method should implement a routine to return a PETSc Vec object.
+
+        Returns:
+            PETSc.Vec: A PETSc Vec object containing the data of the overloaded.
+
+        """
+        raise NotImplementedError
+
 
 class FloatingType(OverloadedType):
     def __init__(self, *args, **kwargs):

From c9b4e82ec103777a690102a7a5fc911be9a06cdc Mon Sep 17 00:00:00 2001
From: Iglesia Dolci <daia.dolci@gmail.com>
Date: Tue, 2 Jul 2024 16:23:28 +0100
Subject: [PATCH 2/6] write and read only petsc vecs

---
 pyadjoint/overloaded_type.py | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/pyadjoint/overloaded_type.py b/pyadjoint/overloaded_type.py
index e6e392d4..20297ce6 100644
--- a/pyadjoint/overloaded_type.py
+++ b/pyadjoint/overloaded_type.py
@@ -320,10 +320,21 @@ def _ad_str(self):
         """
         return str(self)
 
-    def _ad_petsc_vec(self):
+    def _ad_petsc_vec_read_only(self):
         """This method must be overridden.
 
-        The method should implement a routine to return a PETSc Vec object.
+        The method should implement a routine to return a read only PETSc Vec object.
+
+        Returns:
+            PETSc.Vec: A PETSc Vec object containing the data of the overloaded.
+
+        """
+        raise NotImplementedError
+
+    def _ad_petsc_vec_write_only(self):
+        """This method must be overridden.
+
+        The method should implement a routine to return a write only PETSc Vec object.
 
         Returns:
             PETSc.Vec: A PETSc Vec object containing the data of the overloaded.

From e45ede456cfc346fa6722a42ae3792176556ae4a Mon Sep 17 00:00:00 2001
From: Iglesia Dolci <daia.dolci@gmail.com>
Date: Wed, 3 Jul 2024 07:37:13 +0100
Subject: [PATCH 3/6] write and read only petsc vecs

---
 pyadjoint/adjfloat.py        | 9 +++++++--
 pyadjoint/overloaded_type.py | 4 ++--
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/pyadjoint/adjfloat.py b/pyadjoint/adjfloat.py
index 482c2b83..9712eb9d 100644
--- a/pyadjoint/adjfloat.py
+++ b/pyadjoint/adjfloat.py
@@ -130,9 +130,14 @@ def _ad_str(self):
         """Return the string of the taped value of this variable."""
         return str(self.block_variable.saved_output)
 
-    def _ad_petsc_vec(self):
+    def _ad_petsc_vec_write_only(self):
         raise NotImplementedError(
-            "It requires more thought to return a PETSc Vec from `AdjFloat`"
+            "It requires more thought to write only a PETSc Vec from `AdjFloat`."
+        )
+
+    def _ad_petsc_vec_read_only(self):
+        raise NotImplementedError(
+            "It requires more thought to read only a PETSc Vec from `AdjFloat`."
         )
 
 
diff --git a/pyadjoint/overloaded_type.py b/pyadjoint/overloaded_type.py
index 20297ce6..79722daa 100644
--- a/pyadjoint/overloaded_type.py
+++ b/pyadjoint/overloaded_type.py
@@ -323,7 +323,7 @@ def _ad_str(self):
     def _ad_petsc_vec_read_only(self):
         """This method must be overridden.
 
-        The method should implement a routine to return a read only PETSc Vec object.
+        The method should implement a routine to return a read only a PETSc Vec object.
 
         Returns:
             PETSc.Vec: A PETSc Vec object containing the data of the overloaded.
@@ -334,7 +334,7 @@ def _ad_petsc_vec_read_only(self):
     def _ad_petsc_vec_write_only(self):
         """This method must be overridden.
 
-        The method should implement a routine to return a write only PETSc Vec object.
+        The method should implement a routine to write only a PETSc Vec object.
 
         Returns:
             PETSc.Vec: A PETSc Vec object containing the data of the overloaded.

From ccc1c739a8660af7d20ae8111d07a1eaf7b17912 Mon Sep 17 00:00:00 2001
From: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com>
Date: Mon, 8 Jul 2024 11:49:45 +0100
Subject: [PATCH 4/6] Update pyadjoint/overloaded_type.py

Co-authored-by: David A. Ham <david.ham@imperial.ac.uk>
---
 pyadjoint/overloaded_type.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyadjoint/overloaded_type.py b/pyadjoint/overloaded_type.py
index 79722daa..5aae9ac3 100644
--- a/pyadjoint/overloaded_type.py
+++ b/pyadjoint/overloaded_type.py
@@ -321,7 +321,7 @@ def _ad_str(self):
         return str(self)
 
     def _ad_petsc_vec_read_only(self):
-        """This method must be overridden.
+        """This method should be overwritten by types which can return a PETSc Vec.
 
         The method should implement a routine to return a read only a PETSc Vec object.
 

From ffb17681ea35f3d3d9e065c990fc005afa98631c Mon Sep 17 00:00:00 2001
From: Daiane Iglesia Dolci <63597005+Ig-dolci@users.noreply.github.com>
Date: Mon, 8 Jul 2024 11:50:31 +0100
Subject: [PATCH 5/6] Update pyadjoint/overloaded_type.py

---
 pyadjoint/overloaded_type.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyadjoint/overloaded_type.py b/pyadjoint/overloaded_type.py
index 5aae9ac3..8f1b387d 100644
--- a/pyadjoint/overloaded_type.py
+++ b/pyadjoint/overloaded_type.py
@@ -332,7 +332,7 @@ def _ad_petsc_vec_read_only(self):
         raise NotImplementedError
 
     def _ad_petsc_vec_write_only(self):
-        """This method must be overridden.
+        """This method should be overwritten by types which can return a PETSc Vec.
 
         The method should implement a routine to write only a PETSc Vec object.
 

From 6ed08b550e766b9712c0eb8b697e3073ff100a46 Mon Sep 17 00:00:00 2001
From: Iglesia Dolci <daia.dolci@gmail.com>
Date: Tue, 9 Jul 2024 13:32:45 +0100
Subject: [PATCH 6/6] documenting

---
 pyadjoint/overloaded_type.py | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/pyadjoint/overloaded_type.py b/pyadjoint/overloaded_type.py
index 8f1b387d..16bc7d41 100644
--- a/pyadjoint/overloaded_type.py
+++ b/pyadjoint/overloaded_type.py
@@ -323,22 +323,36 @@ def _ad_str(self):
     def _ad_petsc_vec_read_only(self):
         """This method should be overwritten by types which can return a PETSc Vec.
 
-        The method should implement a routine to return a read only a PETSc Vec object.
+        This method must be used as a context manager.
 
-        Returns:
-            PETSc.Vec: A PETSc Vec object containing the data of the overloaded.
+        Usage:
+
+        .. code-block:: python
 
+                with OverloadedType._ad_petsc_vec_read_only() as vec:
+                    # Do something with vec
+
+        Returns:
+            PETSc.Vec: A PETSc Vec object containing the read-only data of the overloaded
+            instance, excluding halo data.
         """
         raise NotImplementedError
 
     def _ad_petsc_vec_write_only(self):
         """This method should be overwritten by types which can return a PETSc Vec.
 
-        The method should implement a routine to write only a PETSc Vec object.
+        This method must be used as a context manager.
 
-        Returns:
-            PETSc.Vec: A PETSc Vec object containing the data of the overloaded.
+        Usage:
+
+        .. code-block:: python
 
+                with OverloadedType._ad_petsc_vec_write_only() as vec:
+                    # Do something with vec
+
+        Returns:
+            PETSc.Vec: A PETSc Vec object containing the write-only data of the overloaded
+            instance, excluding halo data.
         """
         raise NotImplementedError