clarify the role (API) of this repo in different use cases

[yymao]

@philbull I move the discussion here so we can be more focused without jamming the tjp channel.

I think we are on the right track here already, but I want to further distinguish different use cases and what (in my opinion) this repo's rule would be.

I think there are 3 different use cases:

• (A) code that implements a custom class to construct cosmology objects.
• (B) code that uses cosmology objects (but not constructing them).
• (C) code that provides common utility functions (e.g., validation and sterilization) for cosmology objects.

Here, (C) is really just the combination of a subset of (A) and a subset of (B). However, by splitting (C) from (A) and (B), we can enforce the specification with code. In other words, instead of just asking people who writes (A) and (B) to conform to the specification, we can use (C) to make sure they do conform to the specification.

So, I think what we want to do is to implement is (C) (in both C and Python), and by doing so, we would have automatically fully specified our specification.

Here's an some examples (in Python only) of this imaginary (C) module which I call desccosmo

• A function takes a cosmology object from other module:

  import desccosmo
  def my_func(x, y, z, cosmo):
    assert desccosmo.validate(cosmo), "`cosmo` not valid"
    print('using cosmology:', desccosmo.dumps(cosmo))
    # do my thing with cosmo

• A custom class that modifies the base class:

  import desccosmo
  
  class MyCosmo(desccosmo.CosmoBase):    
    def __init__(self, Omega_m):
        super(MyCosmo, self).__init__(Omega_c=Omega_m-0.05, Omega_b=0.05, 
                                      Omega_l=0.69, h=0.67, n_s=0.96, A_s=1e-9)
  cosmo = MyCosmo(0.3)
  assert desccosmo.validate(cosmo)

• A totally different cosmology object but conforming to the specification:

  from collections import namedtuple
  import desccosmo
  
  MyCosmo = namedtuple('MyCosmo', 'Omega_c Omega_b Omega_l h n_s A_s=None sigma_8 Omega_g Omega_n_mass Omega_n_rel w0 wa N_nu_mass N_nu_rel mnu')
  cosmo = MyCosmo(Omega_c=0.27, Omega_b=0.05, Omega_l=0.69, h=0.67, n_s=0.96, 
                A_s=1e-9, sigma_8=None, Omega_g=0.0, Omega_n_mass=0.0, 
                Omega_n_rel=0.0, w0=-1., wa=0., N_nu_mass=0, N_nu_rel = 3.046, mnu=0.0
  assert desccosmo.validate(cosmo)

• Saving a conforming cosmology object to file and loading from file: (using an API similar to that of json)

  import desccosmo
  with open('cosmo_params.txt', 'w') as f:
    desccosmo.dump(cosmo, f)
  with open('cosmo_params.txt', 'r') as f:
    cosmo = desccosmo.load(f)
  assert isinstance(cosmo, desccosmo.CosmoBase), "something is wrong!"

As always, comments are welcome. And thanks to @philbull again for taking a lead on this!

[philbull]

Yes, I agree that having a standalone validation function (C) will be the best way of testing compliance with the standard. I think we can provide reference implementations and a standalone validation function at the same time in this repo.

[yymao]

Sure. I think my earlier confusion came from that I thought that SPECIFICATION was written for who's working on (A) and (B). If SPECIFICATION is intended to instruct who will implement (C) then it makes perfect sense.

The hash function you just added in the specification and also be a function in this module (in my example above it would look like desccosmo.hash(cosmo)).

[philbull]

I think the specification should still be useful to people implementing their own class (case A). I guess you could think of it as the "documentation" of code (C). People doing (B) don't need to worry about it, but people writing their own implementations do need to follow the spec.

[yymao]

Yep, sure.