file closer. documentation

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION "3.14")
 cmake_policy(SET CMP0148 OLD)
-project(Photochem LANGUAGES Fortran C VERSION "0.5.4")
+project(Photochem LANGUAGES Fortran C VERSION "0.5.5")
 
 include(FortranCInterface)
 FortranCInterface_VERIFY()

photochem/cython/Atmosphere.pyx

@@ -3,7 +3,7 @@ cimport Atmosphere_pxd as a_pxd
 
 cdef class Atmosphere:
   """A photochemical model which assumes a background gas (e.g. N2). Once initialized,
-  this class can integrate an atmosphere forward in time, and can investigate
+  this class can integrate an atmosphere forward in time and can investigate
   the reactions producing and destroying each molecule.
   """
 
@@ -27,9 +27,26 @@ cdef class Atmosphere:
       raise PhotoException('The "__init__" method of Atmosphere has not been called.')
     PyObject_GenericSetAttr(self, name, value)
 
-  def __init__(self, mechanism_file = None, settings_file = None, 
-               flux_file = None, atmosphere_txt = None, data_dir = None):           
-
+  def __init__(self, str mechanism_file, str settings_file, 
+               str flux_file, str atmosphere_txt, data_dir = None):           
+    """Initializes the photochemical model.
+
+    Parameters
+    ----------
+    mechanism_file : str
+        Path to the reaction mechanism file (yaml format).
+    settings_file : str
+        Path to the settings file (yaml format).
+    flux_file : str
+        Path to the file describing the stellar flux.
+    atmosphere_txt : str
+        Path to the file containing altitude, total number density, temperature, 
+        eddy diffusion, initial concentrations of each gas (mixing ratios), 
+        and particle radii.
+    data_dir : str, optional
+        Path to the data directory containing photolysis cross sections and other data
+        needed to run the model
+    """
     self._init_called = True
 
     if data_dir == None:
@@ -142,7 +159,7 @@ cdef class Atmosphere:
     if len(err.strip()) > 0:
       raise PhotoException(err.decode("utf-8").strip())
 
-  def out2atmosphere_txt(self,filename = None, int number_of_decimals=5, bool overwrite = False, bool clip = True):
+  def out2atmosphere_txt(self,str filename, int number_of_decimals=5, bool overwrite = False, bool clip = True):
     """Saves state of the atmosphere using the mixing ratios in self.wrk.usol.
 
     Parameters
@@ -201,7 +218,7 @@ cdef class Atmosphere:
     -------
     tuple
         First element are the surface fluxes, and the second are top-of-atmosphere
-        fluxes.
+        fluxes. Units are molecules/cm^2/s
     """
     cdef ndarray surf_fluxes = np.empty(self.dat.nq, np.double)
     cdef ndarray top_fluxes = np.empty(self.dat.nq, np.double)
@@ -220,7 +237,7 @@ cdef class Atmosphere:
       top[names[i]] = top_fluxes[i]
     return surface, top
 
-  def set_lower_bc(self, species = None, bc_type = None, vdep = None, mix = None,
+  def set_lower_bc(self, str species, str bc_type, vdep = None, mix = None,
                             flux = None, height = None):
     """Sets a lower boundary condition.
 
@@ -279,7 +296,7 @@ cdef class Atmosphere:
     if len(err.strip()) > 0:
       raise PhotoException(err.decode("utf-8").strip())
 
-  def set_upper_bc(self, species = None, bc_type = None, veff = None,flux = None):
+  def set_upper_bc(self, str species, str bc_type, veff = None, flux = None):
     """Sets upper boundary condition.
 
     Parameters

photochem/cython/EvoAtmosphere.pyx

@@ -3,9 +3,9 @@ cimport EvoAtmosphere_pxd as ea_pxd
 
 cdef class EvoAtmosphere:
   """A photochemical model which assumes no background gas. Once initialized,
-  this class can integrate an atmosphere forward in time, and can investigate
-  the reactions producing and destroying each molecule. The model can also
-  optionally self-consistently evolve climate.
+  this class can integrate an atmosphere forward in time to a steady
+  state. The model can also, optionally, self-consistently evolve climate for
+  terrestrial planets.
   """
 
   cdef ea_pxd.EvoAtmosphere *_ptr
@@ -28,9 +28,26 @@ cdef class EvoAtmosphere:
       raise PhotoException('The "__init__" method of EvoAtmosphere has not been called.')
     PyObject_GenericSetAttr(self, name, value)
 
-  def __init__(self, mechanism_file = None, settings_file = None, 
-               flux_file = None, atmosphere_txt = None, data_dir = None):           
+  def __init__(self, str mechanism_file, str settings_file, 
+               str flux_file, str atmosphere_txt, data_dir = None):           
+    """Initializes the photochemical model.
 
+    Parameters
+    ----------
+    mechanism_file : str
+        Path to the reaction mechanism file (yaml format).
+    settings_file : str
+        Path to the settings file (yaml format).
+    flux_file : str
+        Path to the file describing the stellar flux.
+    atmosphere_txt : str
+        Path to the file containing altitude, total number density, temperature, 
+        eddy diffusion, initial concentrations of each gas (mixing ratios), 
+        and particle radii.
+    data_dir : str, optional
+        Path to the data directory containing photolysis cross sections and other data
+        needed to run the model
+    """
     self._init_called = True
 
     if data_dir == None:
@@ -94,7 +111,7 @@ cdef class EvoAtmosphere:
     Parameters
     ----------
     usol : ndarray[double,ndim=2]
-        densities
+        Number densities (molecules/cm^3)
     """
     cdef char err[ERR_LEN+1]
     cdef int nq = self.dat.nq
@@ -107,8 +124,8 @@ cdef class EvoAtmosphere:
     if len(err.strip()) > 0:
       raise PhotoException(err.decode("utf-8").strip())
 
-  def out2atmosphere_txt(self,filename = None, int number_of_decimals=5, bool overwrite = False, bool clip = True):
-    """Saves state of the atmosphere using the mixing ratios in self.wrk.usol.
+  def out2atmosphere_txt(self,str filename, int number_of_decimals=5, bool overwrite = False, bool clip = True):
+    """Saves state of the atmosphere using the concentrations in self.wrk.usol.
 
     Parameters
     ----------
@@ -138,7 +155,7 @@ cdef class EvoAtmosphere:
     -------
     tuple
         First element are the surface fluxes, and the second are top-of-atmosphere
-        fluxes.
+        fluxes. Units molecules/cm^2/s.
     """
     cdef ndarray surf_fluxes = np.empty(self.dat.nq, np.double)
     cdef ndarray top_fluxes = np.empty(self.dat.nq, np.double)
@@ -157,7 +174,7 @@ cdef class EvoAtmosphere:
       top[names[i]] = top_fluxes[i]
     return surface, top
 
-  def set_lower_bc(self, species = None, bc_type = None, vdep = None, den = None, press = None,
+  def set_lower_bc(self, str species, str bc_type, vdep = None, den = None, press = None,
                             flux = None, height = None):
     """Sets a lower boundary condition.
 
@@ -224,7 +241,7 @@ cdef class EvoAtmosphere:
     if len(err.strip()) > 0:
       raise PhotoException(err.decode("utf-8").strip())
 
-  def set_upper_bc(self, species = None, bc_type = None, veff = None,flux = None):
+  def set_upper_bc(self, str species, str bc_type, veff = None,flux = None):
     """Sets upper boundary condition.
 
     Parameters
@@ -437,6 +454,8 @@ cdef class EvoAtmosphere:
         times to evaluate the solution
     overwrite : bool
         If true, then overwrites pre-existing files with `filename`
+    restart_from_file : bool
+        If true, then the integration restarts from the input file.
 
     Returns
     -------
@@ -474,7 +493,7 @@ cdef class EvoAtmosphere:
     Parameters
     ----------
     usol_start : ndarray[double,ndim=2]
-        Initial mixing ratios
+        Initial number densities (molecules/cm^3)
     """   
     cdef char err[ERR_LEN+1]
     cdef int nq = self.dat.nq

src/atmosphere/photochem_atmosphere.f90

@@ -169,11 +169,11 @@ module subroutine initialize_stepper(self, usol_start, err)
     end subroutine
 
     !> Takes one internal integration step. Function `initialize_stepper`
-    !> must have been called befe this
+    !> must have been called before this
     module function step(self, err) result(tn)
       class(Atmosphere), target, intent(inout) :: self
       character(:), allocatable, intent(out) :: err
-      real(dp) :: tn
+      real(dp) :: tn !! Current time in the integration.
     end function
 
     !> Deallocates memory created during `initialize_stepper`

src/dependencies/CMakeLists.txt

@@ -1,9 +1,9 @@
 
 CPMAddPackage(
   NAME futils
-  VERSION 0.1.9
+  VERSION 0.1.11
   GITHUB_REPOSITORY "Nicholaswogan/futils"
-  GIT_TAG "v0.1.9"
+  GIT_TAG "v0.1.11"
   EXCLUDE_FROM_ALL ON
 )
 
@@ -49,15 +49,15 @@ CPMAddPackage(
 
 CPMAddPackage(
   NAME clima 
-  VERSION 0.4.5
+  VERSION 0.4.6
   OPTIONS 
     "BUILD_EXECUTABLE OFF"
     "BUILD_WITH_OPENMP ${BUILD_WITH_OPENMP}"
     "SKBUILD ${SKBUILD}"
     "BUILD_PYTHON_CLIMA ${BUILD_PYTHON_PHOTOCHEM}"
     "PYTHON_CLIMA_DESTINATION photochem"
   GITHUB_REPOSITORY "Nicholaswogan/clima"
-  GIT_TAG "v0.4.5"
+  GIT_TAG "v0.4.6"
   EXCLUDE_FROM_ALL OFF
 )