Implement MultiEndpointTerrain

.gitignore

@@ -172,3 +172,6 @@ cython_debug/
 # Add student folder
 .entregas/
 results.csv
+
+# Agents information
+devs/

apps/autograder/autograder.ipynb

@@ -0,0 +1,93 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# AutoGrader\n",
+    "Evaluate one notebook (`.ipynb`) or a zip archive of notebooks (`.zip`) against a grader YAML configuration and write results to a CSV file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ── Configuration ────────────────────────────────────────────────────────────\n",
+    "INPUT          = \"path/to/submission.ipynb\"   # .ipynb or .zip\n",
+    "CONFIG         = \"path/to/grader.yaml\"         # grader YAML config\n",
+    "OUTPUT         = \"results.csv\"                 # output CSV path\n",
+    "ITERATIONS     = 1                             # measurement iterations per terrain\n",
+    "DEBUG          = False                         # enable debug output\n",
+    "AUTHOR_PATTERN = r\"^(?P<author>[^_]+)\"         # regex to derive author from file stem\n",
+    "# ─────────────────────────────────────────────────────────────────────────────"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "066624b2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# INSTALL LIBRARY\n",
+    "import subprocess\n",
+    "import sys\n",
+    "\n",
+    "SIARENA_BRANCH = \"main\"\n",
+    "\n",
+    "# Check if installed\n",
+    "if \"sIArena\" in sys.modules:\n",
+    "    print(\"sIArena already installed.\")\n",
+    "else:\n",
+    "\n",
+    "    try:\n",
+    "        subprocess.check_call([\"pip\", \"install\", f\"git+https://github.com/jparisu/sIArena.git@{SIARENA_BRANCH}\"])\n",
+    "        print(\"sIArena Package installed.\")\n",
+    "\n",
+    "    except Exception as e:\n",
+    "\n",
+    "        print(f\"Error installing the package: {e}. Installing by magic command.\")\n",
+    "\n",
+    "        %pip install --upgrade git+https://github.com/jparisu/sIArena.git@main"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from sIArena.grading import grade_input_to_csv\n",
+    "\n",
+    "batch_result = grade_input_to_csv(\n",
+    "    INPUT,\n",
+    "    CONFIG,\n",
+    "    OUTPUT,\n",
+    "    iterations=ITERATIONS,\n",
+    "    debug=DEBUG,\n",
+    "    author_pattern=AUTHOR_PATTERN,\n",
+    ")\n",
+    "\n",
+    "print(f\"Assignment: {batch_result.assignment_id}\")\n",
+    "print(f\"Input: {INPUT}\")\n",
+    "print(f\"Output CSV: {OUTPUT}\")\n",
+    "print(f\"Processed submissions: {len(batch_result.submission_grades)}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.10.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/rst/modules/elements/path.rst

@@ -27,6 +27,7 @@ In order to be **complete**, the path must be valid and:
 - The first coordinate must be the ``origin`` point of the terrain.
 - The last coordinate must be the ``destination`` point of the terrain.
 - In case of multiple destinations, the path must pass through all of them (order is not important).
+- In case of multi endpoint terrains, the path must start in any allowed origin and end in any allowed destination.
 
 
 In Python, the Path is represented as a list of coordinates:

docs/rst/modules/elements/terrain.rst

@@ -1,9 +1,9 @@
 
 .. _elements_terrain:
 
-=======
+#######
 Terrain
-=======
+#######
 
 .. code-block:: python
 
@@ -22,7 +22,7 @@ These cells are used to determine the start and end of the path to be found.
 It also counts with a *cost_function* that is used to determine the cost of moving from one cell to another depending on their values.
 
 Attributes
-----------
+**********
 
 - ``n``: number of rows
 - ``m``: number of columns
@@ -32,7 +32,7 @@ Attributes
 - ``cost_function``: function that receives 2 integers ``x,y`` and returns the cost of moving from one cell with value ``x`` to another with value ``y``
 
 Built-in Methods
-----------------
+****************
 
 - ``str``: returns a string representation of the matrix of the terrain.
   The origin and destination cells are marked with the characters ``+`` and ``x`` respectively.
@@ -55,7 +55,7 @@ Built-in Methods
 
 
 Methods
--------
+*******
 
 - ``size``: returns a tuple with ``(n,m)``.
 - ``get_neighbors``: returns a list of the coordinates of the cells that are adjacent to the given cell.
@@ -76,7 +76,7 @@ Methods
 .. _elements_terrain_cost_function:
 
 Cost Function
--------------
+*************
 
 The cost function is a function that receives 2 integers ``x,y``
 referring to the *height* of 2 adjacent cells,
@@ -85,7 +85,7 @@ and returns the cost of moving from one cell with value ``x`` to another with va
 .. _elements_terrain_default_cost_function:
 
 Default cost function
-*********************
+=====================
 
 The default cost function is as follows:
 
@@ -106,13 +106,13 @@ The following snippet shows the implementation of the default cost function:
 
 
 Visualization
--------------
+*************
 
 There are several ways to easily visualize the terrain:
 
 
 String
-******
+======
 
 Function ``str`` returns a string representation of the matrix of the terrain:
 The origin and destination cells are marked with the characters ``+`` and ``x`` respectively.
@@ -137,23 +137,23 @@ The origin and destination cells are marked with the characters ``+`` and ``x``
 
 
 2D plot
-*******
+=======
 
 .. image:: /resources/images/2dplot_5_5.png
 
 In order to learn how to visualize a 2D plot of the terrain, please refer to the :ref:`plotting_2d` section.
 
 
 3D plot
-*******
+=======
 
 .. image:: /resources/images/3dplot_5_5.png
 
 In order to learn how to visualize a 3D plot of the terrain, please refer to the :ref:`plotting_3d` section.
 
 
 Multiple Destinations Terrain
------------------------------
+*****************************
 
 There is other class for Terrain that is called ``MultipleDestinationTerrain``.
 This class allows to have multiple destinations in the terrain.
@@ -188,8 +188,99 @@ Example on how to create a ``MultipleDestinationTerrain``:
     destinations = terrain.destinations
 
 
+Multi Endpoint Terrain
+**********************
+
+There is another Terrain class called ``MultiEndpointTerrain``.
+This class is used when the problem has several possible starting points and several possible ending points.
+Paths valid are those that start in any of the allowed origins and end in any of the allowed destinations, as long as they are valid paths in the terrain.
+
+.. code-block:: python
+
+    from sIArena.terrain.Terrain import MultiEndpointTerrain
+
+Difference with Terrain
+=======================
+
+The complete-path rule for ``MultiEndpointTerrain`` is:
+
+- The path must be valid: every consecutive pair of coordinates must be neighbors in the terrain.
+- The first coordinate of the path must belong to the set of allowed origins.
+- The last coordinate of the path must belong to the set of allowed destinations.
+- The path may pass through other origins or destinations in the middle, but this is not required.
+- The path does not need to visit all destinations.
+
+This ``MultiEndpointTerrain`` class is similar to ``Terrain`` with some minor differences:
+
+- Method `get_origins()` returns the set of allowed origins, instead of a single origin.
+- Method `get_destinations()` returns the set of allowed destinations, instead of a single destination.
+- There is no attribute ``origin`` or ``destination``.
+
+The constructor keeps the same parameter names as the standard ``Terrain`` constructor:
+
+- ``origin``: a single ``Coordinate`` or a collection of ``Coordinate`` values.
+- ``destination``: a single ``Coordinate`` or a collection of ``Coordinate`` values.
+
+Examples
+========
+
+Example with several origins and several destinations:
+
+.. code-block:: python
+
+    from sIArena.terrain.Terrain import MultiEndpointTerrain
+
+    matrix = [
+        [0, 0, 0, 0],
+        [0, 5, 5, 0],
+        [0, 0, 0, 0],
+    ]
+
+    terrain = MultiEndpointTerrain(
+        matrix,
+        origin={(0, 0), (2, 0)},
+        destination={(0, 3), (2, 3)},
+    )
+
+    path = [(2, 0), (2, 1), (2, 2), (2, 3)]
+
+    terrain.is_complete_path(path)      # True
+    terrain.get_origins()               # {(0, 0), (2, 0)}
+    terrain.get_destinations()          # {(0, 3), (2, 3)}
+
+
+The following path is also complete in the same terrain, because it starts in another valid origin and ends in another valid destination:
+
+.. code-block:: python
+
+    other_path = [(0, 0), (0, 1), (0, 2), (0, 3)]
+
+    terrain.is_complete_path(other_path)  # True
+
+
+However, this path is not complete, even if it is a valid sequence of neighboring cells, because it does not start in one of the allowed origins:
+
+.. code-block:: python
+
+    wrong_start = [(1, 0), (2, 0), (2, 1), (2, 2), (2, 3)]
+
+    terrain.is_valid_path(wrong_start)     # True
+    terrain.is_complete_path(wrong_start)  # False
+
+
+And this path is not complete because it does not end in one of the allowed destinations:
+
+.. code-block:: python
+
+    wrong_end = [(2, 0), (2, 1), (2, 2)]
+
+    terrain.is_valid_path(wrong_end)       # True
+    terrain.is_complete_path(wrong_end)    # False
+
+
+
 Sequential Destinations Terrain
--------------------------------
+*******************************
 
 There is other class for Terrain that is called ``SequentialDestinationTerrain``.
 This class have multiple destinations, but in this case the path must pass through them in the same order as they are provided.

docs/rst/modules/grading.rst

@@ -76,6 +76,7 @@ Supported generators:
 Supported terrain types:
 
 - ``Terrain``
+- ``MultiEndpointTerrain``
 - ``MultipleDestinationTerrain``
 - ``SequentialDestinationTerrain``
 - ``NoPathTerrain``