proposaldm.vodsl

/*
 *  created on 09-Jul-2021 
 */
 
 model proposal (0.6)  "A model to represent an application for observing time. The model is intended to express all
of the concepts required to specify the scientific parameters of the application in sufficient detail to allow the 
proposal to be reviewed and allocated time. It does not cover all the technical detail of instrument setup that would be needed to actually schedule the 
observations, although the intention is that information about targets etc. could be automatically transferred to an observing system."
 author "Paul Harrison"
 title "Proposal"
 
 include "../../../build/tmp/IVOA-v1.0.vodsl" // note that this is auto generated from dependencies by vodslToVodml command
 include "../../../build/tmp/Coords-v1.0.vodsl" // this is a case where recursive import would be better - https://github.com/ivoa/vo-dml/issues/7 - here stc is really only used in the proposaldm

 
 primitive WikiDataId -> ivoa:stringIdentifier "a WikiData identifier"
 enum ProposalKind  //IMPL -is this universal enough to be an enum?
 {
 	Standard "Normal proposal",
 	ToO "target of opportunity",
 	Survey "Part of a large programme" 	
 }
 
 abstract otype AbstractProposal "base proposal"
 {
 	  ^title: ivoa:string   "the proposal title" ;
    summary: ivoa:string   "a short summary/abstract of the proposal" ;
    scientificJustification: Justification as composition "scientific justification";
    technicalJustification: Justification as composition "technical justification"; //IMPL this probably needs to be attached to each observatory as likely to be different for each.
    investigators: Investigator @+ as composition  "the person(s) making the proposal";
    kind : ProposalKind "the type of proposal";
    relatedProposals: RelatedProposal @* as composition "";
    supportingDocuments: SupportingDocument @* as ordered composition "any additional documents";
    targets: Target @* as composition "the targets of the proposal";
    fields: Field @* as composition "the fields observed in the proposal";
    technicalGoals: TechnicalGoal @+ as ordered composition "the technical goals of the proposal";
    observations : Observation @+ as ordered composition "the proposed observations";
 //   submitted: ivoa:boolean @? "whether the proposal is submitted"; //note that submitted proposals are not expected to be editable..  made optional to allow for not setting for not submitted proposals
    
 }
 
 otype ObservingProposal -> AbstractProposal "a complete proposal" {
 	
 }
 
 
 otype RelatedProposal "a related proposal" // note that this is being done to follow the vodml aggregation pattern
 {
 	proposal references AbstractProposal "the related proposal" ;
 	//IMPL could also put information about the type of relationship
 }
 
  otype Person "person connected with the proposal" {
 	fullName : ivoa:string "The given names for the person";
 	eMail : ivoa:string "an email that can be used to communicate with the person"; // note that this is not considered a unique identifier for the person in any fashion.
 	homeInstitute references Organization ""; //IMPL - this might not be necessary - could probably be learned from ORCID if needed
  orcidId : ivoa:stringIdentifier @? "orcid id see https://orcid.org"; /* something like ORCID this is going to have to be the globally unique identifier that can be used with different AAI systems  */
  
 }
 
 
 enum InvestigatorKind {
 	PI "principal investigator",
 	COI "co-investigator"
 }
 
 //REQ - anonymity of proposers
 otype Investigator { // note that the key that is the surrogate key for this object would be a good candidate for an anonymous key
 	person references Person "the investigator";
 	type : InvestigatorKind "the investigator type";
 	forPhD : ivoa:boolean @? "is the investigator making proposal for their PhD"; //IMPL - might be better attached to ObservingProposal directly
 }
 
 
 otype Organization "An institution that is a collection of people"
 {
 	name: ivoa:string "The name of the organization";
 	address : ivoa:string "";
 	ivoid : ivoa:ivoid @? "the registry identifier for the organization"; 	// IMPL perhaps do this more
 	wikiId : WikiDataId @? "the wikidata id for the Organization";
 	
 }
 
   
  enum TextFormats "acceptable text formats for document submission"{ //IMPL this list is up for debate
 	latex "LaTeX using standard document style" ,//IMPL document sytle to be specified
 	rst "restructured text",
 	asciidoc ""
 }
 
 //REQ - don't use pdf as document submission standard
 otype Justification  "The justification for the proposal. Note that the justification is for reading by humans 
                       and is not parsed to extract things like source lists - that sort of information
                       must be entered in the correct place in the model." {
 	text: ivoa:string "the full text of the justification";
 	format: TextFormats "the format of the text";	
 }
 
 otype SupportingDocument "a document" { //IMPL might want to restrict to this being only graphics files
 	^title : ivoa:string "document title";
 	location : ivoa:anyURI "location of document";//IMPL might want this in-line with code only blobs
 	//IMPL could have acceptable mime types.
 }
 
  abstract otype Target "A target source" {
     sourceName: ivoa:string   "A common name for the source" ;// perhaps could be used for Vizier search?
  	
  }
  
  otype CelestialTarget -> Target  "The basic target setup for a celestial Target."
  {   //IMPL most of these source parameters should be in an ivoa source model.
        sourceCoordinates: coords:EquatorialPoint   "" ;
        positionEpoch : coords:Epoch "the epoch at which the position was measured";
        pmRA: ivoa:RealQuantity @?  "" ;
        pmDec: ivoa:RealQuantity @?  "" ;
        parallax: ivoa:RealQuantity @? "" ;
        sourceVelocity: ivoa:RealQuantity @?   "" ;
 }
 
 otype SolarSystemTarget -> Target ""
 {
 	//TODO needs ephemeris data.
 }
 
 //TODO more target specializations?
 
 abstract otype Field  "Definition of an observing field pointing"
  {   
        name: ivoa:string   "" ;
  }
  
  otype TargetField -> Field "the field points to the associated target"
  {
  	
  }
  
  otype Point -> Field "Single point on the sky" {
  	  centre: coords:Point   "" ;
  }
  
  otype Polygon  -> Field  "Polygonal map"
  {   
        points: coords:EquatorialPoint   @*   "an array of points...." ; 
  }
  
  otype Ellipse  -> Field "Specialization of a Field for an elliptical map."
  {   
        semiMajor: ivoa:RealQuantity   "" ;
        semiMinor: ivoa:RealQuantity   "" ;
        pAMajor: ivoa:RealQuantity   "" ;
  }
  
  
  abstract otype ObservingConstraint "a form of constraint on the observation" {
  	
  }
  
  abstract otype TimingConstraint -> ObservingConstraint  "Any specific timing requirements for the observing"
  {   
        note: ivoa:string  @?   "" ;
        isAvoidConstraint: ivoa:boolean  @?   "" ;
  }
  
  otype TimingWindow -> TimingConstraint "particular time range"
  {
        startTime: ivoa:datetime  @?   "" ;
        endTime: ivoa:datetime  @?   "" ;
  }
 
 otype SimultaneityConstraint -> TimingConstraint "A constraint that requires that two observations occur simultaneously"
 {
 	//TODO needs more thought
 }
 
 abstract otype PointingConstaint -> ObservingConstraint "A constraint that limits the telescope pointing"
 {
 	//TODO needs some concrete types
 }
  
  otype ScienceSpectralWindow  "A spectral window for science use."
  {   
        spectralWindowSetup: SpectralWindowSetup  @?     "" ;
        expectedSpectralLine: ExpectedSpectralLine  @*   as ordered composition  "" ;
  }
 
  dtype SpectralWindowSetup  "Science oriented definition of a spectral window."
  {   
        start: ivoa:RealQuantity   "The start of the spectral window" ;
        end: ivoa:RealQuantity    "The end of the spectral window" ;
        spectralResolution: ivoa:RealQuantity @?  "channel width" ; //IMPL would like this to be optional, but cannot have optional embedded in JPA - if resolution not important then set same as width.
        isSkyFrequency: ivoa:boolean   "represents an observed frequency" ;
        polarization: coords:PolStateEnum  "desired polarization"; //FIXME - in general the STC polstate enum is not enough - how to say L circular for instance. - also do want multiple pol states in same window defn.
   }  
 
  
  otype ExpectedSpectralLine  "Brief description of a spectral line."
  {   
        restFrequency: ivoa:RealQuantity   "" ;
        transition: ivoa:string @?  "" ;
        splatalogId: ivoa:stringIdentifier   "" ; // IMPL is VAMDC more client friendly?
        description: ivoa:string   "" ;
  }
  
 otype PerformanceParameters "The parameters required for observation to be useful for the science goal" 
 {
 	//TODO these need to be fleshed out.
 	desiredAngularResolution: ivoa:RealQuantity @?  "";
 	desiredLargestScale:  ivoa:RealQuantity @?  "";
 	desiredSensitivity:  ivoa:RealQuantity @?  "";
 	desiredDynamicRange:  ivoa:RealQuantity @?  "";  //TODO sensitivity or dynamic range?
 	representativeSpectralPoint: ivoa:RealQuantity "the the point in the EM where these parameters should be evaluated";
 }
 
 
 abstract otype Observation "An observation - a pointing of the telescope at a part of the sky, occurs in a single non-overlapping time period" {
 	target @* references Target  "The actual target of the observation"; //IMPL this chould be multiple if field is to have any separate meaning - however aggregation pattern is discouraged.
 	field references Field "The Field for the observation";
 	technicalGoal references TechnicalGoal "The technical goals of the observation";
 	constraints: ObservingConstraint @* as ordered composition "any constraints on the observation";
  
 }
 
 otype TargetObservation -> Observation "an observation of the scientific target "{
 }
 
 otype CalibrationObservation -> Observation "An observation that is intended for calibration"{
 	intent : CalibrationTarget_intendedUse "The use of the calibration observation";
 }
 
 enum CalibrationTarget_intendedUse  "" //IMPL is this enum sufficient - does it cover the range of values is it more appropriate to have an extensible type?
{
Amplitude  "" ,
Atmospheric  "used to measure atmospheric effects" ,
Bandpass  "" ,
Phase  "" ,
Pointing  "" ,
Focus  "" ,
Polarization  "" ,
Delay  "" 
}
 
 //REQ define technical aspects in science terms
 otype TechnicalGoal "collects together the technical goals of the proposal" {
 	performance : PerformanceParameters as composition "";
 	spectrum: ScienceSpectralWindow @+ as ordered composition "";
 	
 }