Updates to documentation

Author: AstroPatty

docs/source/collection_ref.rst

@@ -8,6 +8,7 @@ Collections within a single file can always be loaded with :py:func:`opencosmo.o
    :members:
    :exclude-members: open,read,close,write
    :undoc-members:
+   :member-order: bysource
 
 
 .. autoclass:: opencosmo.StructureCollection

docs/source/conf.py

@@ -14,7 +14,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_rtd_theme"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_rtd_theme", "sphinxcontrib.autodoc_pydantic"]
 
 templates_path = ["_templates"]
 exclude_patterns = []

docs/source/index.rst

@@ -39,5 +39,6 @@ The OpenCosmo Python Toolkit provides utilities for reading, writing and manipul
    io_ref
    dataset_ref
    collection_ref
+   parameters_ref
 
 

docs/source/parameters_ref.rst

@@ -0,0 +1,24 @@
+Simulation Parameters
+=====================
+
+You can access the parameters of the simulation any dataset is drawn from with :py:attr:`opencosmo.Dataset.simulation`. All datasets regardless of simulation will have the parameters in :py:class:`opencosmo.parameters.SimulationParameters`. Hydrodynamic simulations will additionally contain the parameters in :py:class:`opencosmo.parameters.SubgridParameters`
+
+
+.. autoclass:: opencosmo.parameters.SimulationParameters
+   :members:
+   :undoc-members:
+   :exclude-members: model_config,empty_string_to_none,cosmology_parameters
+   :member-order: bysource
+
+
+.. autoclass:: opencosmo.parameters.HydroSimulationParameters
+   :members:
+   :undoc-members:
+   :exclude-members: model_config
+   :member-order: bysource
+
+.. autoclass:: opencosmo.parameters.SubgridParameters
+   :members:
+   :undoc-members:
+   :exclude-members: model_config
+   :member-order: bysource

opencosmo/collection/collection.py

@@ -183,7 +183,7 @@ def cosmology(self) -> dict[str, Cosmology]:
         """
         Get the cosmologies of the simulations in the collection
 
-        Returns:
+        Returns
         --------
         cosmologies: dict[str, astropy.cosmology.Cosmology]
         """
@@ -194,7 +194,7 @@ def redshift(self) -> dict[str, float]:
         """
         Get the redshift slices for the simulations in the collection
 
-        Returns:
+        Returns
         --------
         redshifts: dict[str, float]
         """
@@ -205,7 +205,7 @@ def simulation(self) -> dict[str, SimulationParameters]:
         """
         Get the simulation parameters for the simulations in the collection
 
-        Returns:
+        Returns
         --------
         simulation_parameters: dict[str, opencosmo.parameters.SimulationParameters]
         """
@@ -254,6 +254,27 @@ def select(self, *args, **kwargs) -> SimulationCollection:
         """
         return self.__map("select", *args, **kwargs)
 
+    def take(self, n: int, at: str = "random") -> SimulationCollection:
+        """
+        Take a subest of rows from all datasets or collections in this collection.
+        This method will delegate to the underlying method in
+        :class:`opencosmo.Dataset`, or :class:`opencosmo.StructureCollection` depending 
+        on  the context. As such, behavior may vary depending on what this collection 
+        contains. See their documentation for more info.
+
+        Parameters
+        ----------
+        n: int
+            The number of rows to take
+        at: str, default = "random"
+            The method to use to take rows. Must be one of "start", "end", "random".
+
+        """
+        if any(len(ds) < n for ds in self.values()):
+            raise ValueError(f"Not all datasets in this collection have at least {n} rows!")
+        return self.__map("take", n, at)
+
+
     def with_units(self, convention: str) -> SimulationCollection:
         """
         Transform all datasets or collections to use the given unit convention. This
@@ -268,15 +289,6 @@ def with_units(self, convention: str) -> SimulationCollection:
         """
         return self.__map("with_units", convention)
 
-    def take(self, *args, **kwargs) -> SimulationCollection:
-        """
-        Take a subest of rows from all datasets or collections in this collection.
-        This method will delegate to the underlying method in
-        :class:`opencosmo.Dataset`, or :class:`opencosmo.Collection` depending on  the
-        context. As such, behaviormay vary depending on what this collection contains.
-        """
-
-        return self.__map("take", *args, **kwargs)
 
 
 def open_single_dataset(

opencosmo/dataset/dataset.py

@@ -73,32 +73,21 @@ def cosmology(self) -> Cosmology:
         return self.__header.cosmology
 
     @property
-    def dtype(self) -> str:
+    def redshift(self) -> float:
         """
-        Get the data type of this dataset
+        The redshift slice this dataset was drawn from
 
         Returns
         -------
-        dtype: str
-        """
-        return self.__header.file.data_type
-
-    @property
-    def redshift(self) -> float:
-        """
-        Get the redshift slice this dataset was drawn from
-
-        Returns:
-        --------
-        redshift: gloat
+        redshift: float
 
         """
         return self.__header.file.redshift
 
     @property
     def simulation(self) -> SimulationParameters:
         """
-        Get the parameters of the simulation this dataset is drawn
+        The parameters of the simulation this dataset is drawn
         from.
 
         Returns

opencosmo/link/collection.py

@@ -59,6 +59,9 @@ def __repr__(self):
         dtype_str = ", ".join(self.__handlers.keys())
         return f"Collection of {structure_type} with linked datasets {dtype_str}"
 
+    def __len__(self):
+        return len(self.__properties)
+
     @classmethod
     def open(
         cls, file: File, datasets_to_get: Optional[Iterable[str]] = None

opencosmo/parameters/simulation.py

@@ -80,13 +80,16 @@ def empty_string_to_none(v):
 
 class SimulationParameters(BaseModel):
     box_size: float = Field(ge=0, description="Size of the simulation box (Mpc/h)")
-    z_ini: float = Field(ge=0.01, description="Initial redshift")
-    z_end: float = Field(ge=0.0, description="Final redshift")
+    z_ini: float = Field(ge=0.01, description="Initial redshift of the simulation")
+    z_end: float = Field(ge=0.0, description="Final redshift of the simulation")
     n_gravity: Optional[int] = Field(
-        ge=2, description="Number of gravity-only particles (per dimension)"
+        ge=2, 
+        description=
+            "Number of gravity-only particles (per dimension). "
+            "In hydrodynamic simulations, this parameter will be replaced with \"n_dm\""
     )
     n_steps: int = Field(ge=1, description="Number of time steps")
-    pm_grid: int = Field(ge=2, description="Grid resolution (per dimension)")
+    pm_grid: int = Field(ge=2, description="Number of grid points (per dimension)")
     offset_gravity_ini: Optional[float] = Field(
         description="Lagrangian offset for gravity-only particles"
     )
@@ -104,6 +107,11 @@ def empty_string_to_none(cls, data):
 
     @cached_property
     def step_zs(self) -> list[float]:
+        """
+        Get the redshift of the steps in this simulation. Outputs such that
+        redshift[step_number] returns the redshift for that step. Keep in 
+        mind that steps go from high z -> low z.
+        """
         a_ini = 1 / (1 + self.z_ini)
         a_end = 1 / (1 + self.z_end)
         # Steps are evenly spaced in log(a)
@@ -123,9 +131,9 @@ class SubgridParameters(BaseModel):
     agn_kinetic_eps: float = Field(description="AGN feedback efficiency")
     agn_kinetic_jet_vel: float = Field(description="AGN feedback velocity")
     agn_nperh: float = Field(description="AGN sphere of influence")
-    agn_seed_mass: float = Field(description="AGN seed mass")
+    agn_seed_mass: float = Field(description="AGN seed mass (Msun / h)")
     wind_egy_w: float = Field(description="Wind mass loading factor")
-    wind_kappa_w: float = Field(description="Wind belovity")
+    wind_kappa_w: float = Field(description="Wind velocity")
 
 
 class HydroSimulationParameters(SimulationParameters):
@@ -142,6 +150,6 @@ class HydroSimulationParameters(SimulationParameters):
         description="Lagrangian offset for dark matter particles"
     )
     subgrid_parameters: SubgridParameters = Field(
-        description="Parameters for subgrid physics",
+        description="Parameters for subgrid hydrodynamic physics",
         exclude=True,
     )

poetry.lock

@@ -31,6 +31,7 @@ optional = true
 [tool.poetry.group.docs.dependencies]
 sphinx = "^8.1.3"
 sphinx-rtd-theme = "^3.0.2"
+autodoc-pydantic = "^2.2.0"
 
 
 [tool.poetry.group.mpi]