1 //------------------------------------------------------------------------------ 2 // <auto-generated /> 3 // 4 // This file was automatically generated by SWIG (http://www.swig.org). 5 // Version 4.0.2 6 // 7 // Do not make changes to this file unless you know what you are doing--modify 8 // the SWIG interface file instead. 9 //------------------------------------------------------------------------------ 10 11 namespace libsbml { 12 13 using System; 14 using System.Runtime.InteropServices; 15 16 /** 17 * @sbmlpackage{core} 18 * 19 @htmlinclude pkg-marker-core.html The priority of execution of an SBML <em>event</em>. 20 * 21 * The Priority object class (which was introduced in SBML Level 3 22 * Version 1), like Delay, is derived from SBase and contains a MathML 23 * formula stored in the element 'math'. This formula is used to compute a 24 * dimensionless numerical value that influences the order in which a 25 * simulator is to perform the assignments of two or more events that 26 * happen to be executed simultaneously. The formula may evaluate to any 27 * @c double value (and thus may be a positive or negative number, or 28 * zero), with positive numbers taken to signifying a higher priority than 29 * zero or negative numbers. If no Priority object is present on a given 30 * Event object, no priority is defined for that event. 31 * 32 * @section priority-interp The interpretation of priorities on events in a model 33 * 34 * For the purposes of SBML, <em>simultaneous event execution</em> is 35 * defined as the situation in which multiple events have identical 36 * times of execution. The time of execution is calculated as the 37 * sum of the time at which a given event's Trigger is <em>triggered</em> 38 * plus its Delay duration, if any. Here, <em>identical times</em> means 39 * <em>mathematically equal</em> instants in time. (In practice, 40 * simulation software adhering to this specification may have to 41 * rely on numerical equality instead of strict mathematical 42 * equality; robust models will ensure that this difference will not 43 * cause significant discrepancies from expected behavior.) 44 * 45 * If no Priority subobjects are defined for two or more Event objects, 46 * then those events are still executed simultaneously but their order of 47 * execution is <em>undefined by the SBML Level 3 48 * specification</em>. A software implementation may choose to execute 49 * such simultaneous events in any order, as long as each event is executed 50 * only once and the requirements of checking the 'persistent' attribute 51 * (and acting accordingly) are satisfied. 52 * 53 * If Priority subobjects are defined for two or more 54 * simultaneously-triggered events, the order in which those particular 55 * events must be executed is dictated by their Priority objects, 56 * as follows. If the values calculated using the two Priority 57 * objects' 'math' expressions differ, then the event having 58 * the higher priority value must be executed before the event with 59 * the lower value. If, instead, the two priority values are 60 * mathematically equal, then the two events must be triggered in a 61 * <em>random</em> order. It is important to note that a <em>random 62 * order is not the same as an undefined order</em>: given multiple 63 * runs of the same model with identical conditions, an undefined 64 * ordering would permit a system to execute the events in (for 65 * example) the same order every time (according to whatever scheme 66 * may have been implemented by the system), whereas the explicit 67 * requirement for random ordering means that the order of execution 68 * in different simulation runs depends on random chance. In other 69 * words, given two events <em>A</em> and <em>B</em>, a randomly-determined 70 * order must lead to an equal chance of executing <em>A</em> first or 71 * <em>B</em> first, every time those two events are executed 72 * simultaneously. 73 * 74 * A model may contain a mixture of events, some of which have 75 * Priority subobjects and some do not. Should a combination of 76 * simultaneous events arise in which some events have priorities 77 * defined and others do not, the set of events with defined 78 * priorities must trigger in the order determined by their Priority 79 * objects, and the set of events without Priority objects must be 80 * executed in an <em>undefined</em> order with respect to each other 81 * and with respect to the events with Priority subobjects. (Note 82 * that <em>undefined order</em> does not necessarily mean random 83 * order, although a random ordering would be a valid implementation 84 * of this requirement.) 85 * 86 * The following example may help further clarify these points. 87 * Suppose a model contains four events that should be executed 88 * simultaneously, with two of the events having Priority objects 89 * with the same value and the other two events having Priority 90 * objects with the same, but different, value. The two events with 91 * the higher priorities must be executed first, in a random order 92 * with respect to each other, and the remaining two events must be 93 * executed after them, again in a random order, for a total of four 94 * possible and equally-likely event executions: A-B-C-D, A-B-D-C, 95 * B-A-C-D, and B-A-D-C. If, instead, the model contains four events 96 * all having the same Priority values, there are 4! or 24 97 * possible orderings, each of which must be equally likely to be 98 * chosen. Finally, if none of the four events has a Priority 99 * subobject defined, or even if exactly one of the four events has a 100 * defined Priority, there are again 24 possible orderings, but the 101 * likelihood of choosing any particular ordering is undefined; the 102 * simulator can choose between events as it wishes. (The SBML 103 * specification only defines the effects of priorities on Event 104 * objects with respect to <em>other</em> Event objects with 105 * priorities. Putting a priority on a <em>single</em> Event object 106 * in a model does not cause it to fall within that scope.) 107 * 108 * @section priority-eval Evaluation of Priority expressions 109 * 110 * An event's Priority object 'math' expression must be 111 * evaluated at the time the Event is to be <em>executed</em>. During 112 * a simulation, all simultaneous events have their Priority values 113 * calculated, and the event with the highest priority is selected for 114 * next execution. Note that it is possible for the execution of one 115 * Event object to cause the Priority value of another 116 * simultaneously-executing Event object to change (as well as to 117 * trigger other events, as already noted). Thus, after executing 118 * one event, and checking whether any other events in the model have 119 * been triggered, all remaining simultaneous events that 120 * <em>either</em> (i) have Trigger objects with attributes 121 * 'persistent'=@c false <em>or</em> (ii) have Trigger 122 * expressions that did not transition from @c true to 123 * @c false, must have their Priority expression reevaluated. 124 * The highest-priority remaining event must then be selected for 125 * execution next. 126 * 127 * @section priority-units Units of Priority object's mathematical expressions 128 * 129 * The unit associated with the value of a Priority object's 130 * 'math' expression should be @c dimensionless. This is 131 * because the priority expression only serves to provide a relative 132 * ordering between different events, and only has meaning with 133 * respect to other Priority object expressions. The value of 134 * Priority objects is not comparable to any other kind of object in 135 * an SBML model. 136 * 137 * @note The Priority construct exists only in SBML Level 3; it cannot 138 * be used in SBML Level 2 or Level 1 models. 139 * 140 * @section priority-restrictions Restrictions relaxed in SBML Level 3 Version 2 141 * 142 * In SBML Level 3 Version 2, the requirement that a Priority 143 * have a 'math' subelement was relaxed, making it optional. In 144 * this case, the Priority remains undefined, and unless that information 145 * is provided in some other form (such as with an SBML Level 3 146 * package), the Event behaves as if it had no Priority. 147 * 148 * @see Event 149 * @see Delay 150 * @see EventAssignment 151 */ 152 153 public class Priority : SBase { 154 private HandleRef swigCPtr; 155 Priority(IntPtr cPtr, bool cMemoryOwn)156 internal Priority(IntPtr cPtr, bool cMemoryOwn) : base(libsbmlPINVOKE.Priority_SWIGUpcast(cPtr), cMemoryOwn) 157 { 158 //super(libsbmlPINVOKE.PriorityUpcast(cPtr), cMemoryOwn); 159 swigCPtr = new HandleRef(this, cPtr); 160 } 161 getCPtr(Priority obj)162 internal static HandleRef getCPtr(Priority obj) 163 { 164 return (obj == null) ? new HandleRef(null, IntPtr.Zero) : obj.swigCPtr; 165 } 166 getCPtrAndDisown(Priority obj)167 internal static HandleRef getCPtrAndDisown (Priority obj) 168 { 169 HandleRef ptr = new HandleRef(null, IntPtr.Zero); 170 171 if (obj != null) 172 { 173 ptr = obj.swigCPtr; 174 obj.swigCMemOwn = false; 175 } 176 177 return ptr; 178 } 179 Dispose(bool disposing)180 protected override void Dispose(bool disposing) { 181 lock(this) { 182 if (swigCPtr.Handle != global::System.IntPtr.Zero) { 183 if (swigCMemOwn) { 184 swigCMemOwn = false; 185 libsbmlPINVOKE.delete_Priority(swigCPtr); 186 } 187 swigCPtr = new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero); 188 } 189 base.Dispose(disposing); 190 } 191 } 192 193 194 /** 195 * Creates a new Priority object using the given SBML @p level and @p 196 * version values. 197 * 198 * @param level a long integer, the SBML Level to assign to this Priority. 199 * 200 * @param version a long integer, the SBML Version to assign to this 201 * Priority. 202 * 203 * 204 * @throws SBMLConstructorException 205 * Thrown if the given @p level and @p version combination are invalid 206 * or if this object is incompatible with the given level and version. 207 * 208 * 209 * 210 * 211 * @note Attempting to add an object to an SBMLDocument having a different 212 * combination of SBML Level, Version and XML namespaces than the object 213 * itself will result in an error at the time a caller attempts to make the 214 * addition. A parent object must have compatible Level, Version and XML 215 * namespaces. (Strictly speaking, a parent may also have more XML 216 * namespaces than a child, but the reverse is not permitted.) The 217 * restriction is necessary to ensure that an SBML model has a consistent 218 * overall structure. This requires callers to manage their objects 219 * carefully, but the benefit is increased flexibility in how models can be 220 * created by permitting callers to create objects bottom-up if desired. In 221 * situations where objects are not yet attached to parents (e.g., 222 * SBMLDocument), knowledge of the intented SBML Level and Version help 223 * libSBML determine such things as whether it is valid to assign a 224 * particular value to an attribute. 225 * 226 * 227 * 228 * 229 * @note The Priority construct exists only in SBML Level 3; it 230 * cannot be used in SBML Level 2 or Level 1 models. 231 * 232 * 233 */ public Priority(long level, long version)234 Priority(long level, long version) : this(libsbmlPINVOKE.new_Priority__SWIG_0(level, version), true) { 235 if (libsbmlPINVOKE.SWIGPendingException.Pending) throw libsbmlPINVOKE.SWIGPendingException.Retrieve(); 236 } 237 238 239 /** 240 * Creates a new Priority object using the given SBMLNamespaces object 241 * @p sbmlns. 242 * 243 * 244 * 245 * The SBMLNamespaces object encapsulates SBML Level/Version/namespaces 246 * information. It is used to communicate the SBML Level, Version, and (in 247 * Level 3) packages used in addition to SBML Level 3 Core. A 248 * common approach to using libSBML's SBMLNamespaces facilities is to create an 249 * SBMLNamespaces object somewhere in a program once, then hand that object 250 * as needed to object constructors that accept SBMLNamespaces as arguments. 251 * 252 * 253 * 254 * @param sbmlns an SBMLNamespaces object. 255 * 256 * 257 * @throws SBMLConstructorException 258 * Thrown if the given @p sbmlns is inconsistent or incompatible 259 * with this object. 260 * 261 * 262 * 263 * 264 * @note Attempting to add an object to an SBMLDocument having a different 265 * combination of SBML Level, Version and XML namespaces than the object 266 * itself will result in an error at the time a caller attempts to make the 267 * addition. A parent object must have compatible Level, Version and XML 268 * namespaces. (Strictly speaking, a parent may also have more XML 269 * namespaces than a child, but the reverse is not permitted.) The 270 * restriction is necessary to ensure that an SBML model has a consistent 271 * overall structure. This requires callers to manage their objects 272 * carefully, but the benefit is increased flexibility in how models can be 273 * created by permitting callers to create objects bottom-up if desired. In 274 * situations where objects are not yet attached to parents (e.g., 275 * SBMLDocument), knowledge of the intented SBML Level and Version help 276 * libSBML determine such things as whether it is valid to assign a 277 * particular value to an attribute. 278 * 279 * 280 * 281 * 282 * @note The Priority construct exists only in SBML Level 3; it 283 * cannot be used in SBML Level 2 or Level 1 models. 284 * 285 */ public Priority(SBMLNamespaces sbmlns)286 Priority(SBMLNamespaces sbmlns) : this(libsbmlPINVOKE.new_Priority__SWIG_1(SBMLNamespaces.getCPtr(sbmlns)), true) { 287 if (libsbmlPINVOKE.SWIGPendingException.Pending) throw libsbmlPINVOKE.SWIGPendingException.Retrieve(); 288 } 289 290 291 /** 292 * Copy constructor; creates a copy of this Priority. 293 * 294 * @param orig the object to copy. 295 */ public Priority(Priority orig)296 Priority(Priority orig) : this(libsbmlPINVOKE.new_Priority__SWIG_2(Priority.getCPtr(orig)), true) { 297 if (libsbmlPINVOKE.SWIGPendingException.Pending) throw libsbmlPINVOKE.SWIGPendingException.Retrieve(); 298 } 299 300 301 /** 302 * Creates and returns a deep copy of this Priority object. 303 * 304 * @return the (deep) copy of this Priority object. 305 */ public new clone()306 Priority clone() { 307 global::System.IntPtr cPtr = libsbmlPINVOKE.Priority_clone(swigCPtr); 308 Priority ret = (cPtr == global::System.IntPtr.Zero) ? null : new Priority(cPtr, true); 309 return ret; 310 } 311 312 313 /** 314 * Get the mathematical formula for the priority and return it 315 * as an AST. 316 * 317 * @return the math of this Priority, or @c null if the math is not set. 318 */ public new getMath()319 ASTNode getMath() { 320 global::System.IntPtr cPtr = libsbmlPINVOKE.Priority_getMath(swigCPtr); 321 ASTNode ret = (cPtr == global::System.IntPtr.Zero) ? null : new ASTNode(cPtr, false); 322 return ret; 323 } 324 325 326 /** 327 * Predicate to test whether the formula for this delay is set. 328 * 329 * @return @c true if the formula (meaning the @c math subelement) of 330 * this Priority is set, @c false otherwise. 331 */ public isSetMath()332 bool isSetMath() { 333 bool ret = libsbmlPINVOKE.Priority_isSetMath(swigCPtr); 334 return ret; 335 } 336 337 338 /** 339 * Sets the math expression of this Priority instance to a copy of the given 340 * ASTNode. 341 * 342 * @param math an ASTNode representing a formula tree. 343 * 344 * 345 * @return integer value indicating success/failure of the 346 * function. @if clike The value is drawn from the 347 * enumeration #OperationReturnValues_t. @endif The possible values 348 * returned by this function are: 349 * @li @link libsbml#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS@endlink 350 * @li @link libsbml#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT@endlink 351 */ public new setMath(ASTNode math)352 int setMath(ASTNode math) { 353 int ret = libsbmlPINVOKE.Priority_setMath(swigCPtr, ASTNode.getCPtr(math)); 354 return ret; 355 } 356 357 358 /** 359 * Returns the libSBML type code of this object instance. 360 * 361 * 362 * 363 * LibSBML attaches an identifying code to every kind of SBML object. These 364 * are integer constants known as <em>SBML type codes</em>. The names of all 365 * the codes begin with the characters <code>SBML_</code>. 366 * @if clike The set of possible type codes for core elements is defined in 367 * the enumeration #SBMLTypeCode_t, and in addition, libSBML plug-ins for 368 * SBML Level 3 packages define their own extra enumerations of type 369 * codes (e.g., #SBMLLayoutTypeCode_t for the Level 3 Layout 370 * package).@endif@if java In the Java language interface for libSBML, the 371 * type codes are defined as static integer constants in the interface class 372 * {@link libsbmlConstants}. @endif@if python In the Python language 373 * interface for libSBML, the type codes are defined as static integer 374 * constants in the interface class @link libsbml@endlink.@endif@if csharp In 375 * the C# language interface for libSBML, the type codes are defined as 376 * static integer constants in the interface class 377 * @link libsbmlcs.libsbml@endlink.@endif Note that different Level 3 378 * package plug-ins may use overlapping type codes; to identify the package 379 * to which a given object belongs, call the 380 * <code>@if conly SBase_getPackageName() 381 * @else SBase::getPackageName() 382 * @endif</code> 383 * method on the object. 384 * 385 * The exception to this is lists: all SBML-style list elements have the type 386 * @link libsbml#SBML_LIST_OF SBML_LIST_OF@endlink, regardless of what package they 387 * are from. 388 * 389 * 390 * 391 * @return the SBML type code for this object: 392 * @link libsbml#SBML_PRIORITY SBML_PRIORITY@endlink (default). * 393 * 394 * @warning <span class='warning'>The specific integer values of the possible 395 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 396 * packages, To fully identify the correct code, <strong>it is necessary to 397 * invoke both getPackageName() and getTypeCode()</strong> (or 398 * ListOf::getItemTypeCode()).</span> 399 * 400 * 401 * 402 * @see getElementName() 403 * @see getPackageName() 404 */ public new getTypeCode()405 int getTypeCode() { 406 int ret = libsbmlPINVOKE.Priority_getTypeCode(swigCPtr); 407 return ret; 408 } 409 410 411 /** 412 * Returns the XML element name of this object, which for Priority, is 413 * always @c 'priority'. 414 * 415 * @return the name of this element, i.e., @c 'priority'. 416 * 417 * @see getTypeCode() 418 */ public new getElementName()419 string getElementName() { 420 string ret = libsbmlPINVOKE.Priority_getElementName(swigCPtr); 421 return ret; 422 } 423 424 425 /** 426 * Predicate returning @c true if all the required elements for this 427 * Priority object have been set. 428 * 429 * @note The required elements for a Priority object are: 430 * @li 'math' inSBML Level 2 and Level 3 Version 1. 431 * (In SBML Level 3 Version 2+, it is no longer required.) 432 * 433 * @return a boolean value indicating whether all the required 434 * elements for this object have been defined. 435 */ public new hasRequiredElements()436 bool hasRequiredElements() { 437 bool ret = libsbmlPINVOKE.Priority_hasRequiredElements(swigCPtr); 438 return ret; 439 } 440 441 442 /** 443 * Finds this Priority's Event parent and calls unsetPriority() on it, 444 * indirectly deleting itself. 445 * 446 * Overridden from the SBase function since the parent is not a ListOf. 447 * 448 * 449 * @return integer value indicating success/failure of the 450 * function. @if clike The value is drawn from the 451 * enumeration #OperationReturnValues_t. @endif The possible values 452 * returned by this function are: 453 * @li @link libsbml#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS@endlink 454 * @li @link libsbml#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED@endlink 455 */ public new removeFromParentAndDelete()456 int removeFromParentAndDelete() { 457 int ret = libsbmlPINVOKE.Priority_removeFromParentAndDelete(swigCPtr); 458 return ret; 459 } 460 461 462 /** 463 * 464 * Replaces all uses of a given @c SIdRef type attribute value with another 465 * value. 466 * 467 * 468 * 469 470 * In SBML, object identifiers are of a data type called <code>SId</code>. 471 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 472 * introduced for attribute values that refer to <code>SId</code> values; in 473 * previous Levels of SBML, this data type did not exist and attributes were 474 * simply described to as 'referring to an identifier', but the effective 475 * data type was the same as <code>SIdRef</code> in Level 3. These and 476 * other methods of libSBML refer to the type <code>SIdRef</code> for all 477 * Levels of SBML, even if the corresponding SBML specification did not 478 * explicitly name the data type. 479 * 480 * 481 * 482 * This method works by looking at all attributes and (if appropriate) 483 * mathematical formulas in MathML content, comparing the referenced 484 * identifiers to the value of @p oldid. If any matches are found, the 485 * matching values are replaced with @p newid. The method does @em not 486 * descend into child elements. 487 * 488 * @param oldid the old identifier. 489 * @param newid the new identifier. 490 * 491 * 492 */ public new renameSIdRefs(string oldid, string newid)493 void renameSIdRefs(string oldid, string newid) { 494 libsbmlPINVOKE.Priority_renameSIdRefs(swigCPtr, oldid, newid); 495 } 496 497 498 /** 499 * 500 * Replaces all uses of a given @c UnitSIdRef type attribute value with 501 * another value. 502 * 503 * 504 * 505 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 506 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 507 * introduced for attribute values that refer to <code>UnitSId</code> values; in 508 * previous Levels of SBML, this data type did not exist and attributes were 509 * simply described to as 'referring to a unit identifier', but the effective 510 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 511 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 512 * Levels of SBML, even if the corresponding SBML specification did not 513 * explicitly name the data type. 514 * 515 * 516 * 517 * This method works by looking at all unit identifier attribute values 518 * (including, if appropriate, inside mathematical formulas), comparing the 519 * referenced unit identifiers to the value of @p oldid. If any matches 520 * are found, the matching values are replaced with @p newid. The method 521 * does @em not descend into child elements. 522 * 523 * @param oldid the old identifier. 524 * @param newid the new identifier. 525 * 526 * 527 */ public new renameUnitSIdRefs(string oldid, string newid)528 void renameUnitSIdRefs(string oldid, string newid) { 529 libsbmlPINVOKE.Priority_renameUnitSIdRefs(swigCPtr, oldid, newid); 530 } 531 532 533 /** */ /* libsbml-internal */ public new replaceSIDWithFunction(string id, ASTNode function)534 void replaceSIDWithFunction(string id, ASTNode function) { 535 libsbmlPINVOKE.Priority_replaceSIDWithFunction(swigCPtr, id, ASTNode.getCPtr(function)); 536 } 537 538 } 539 540 } 541