Documentation
¶
Index ¶
- func FreeInstance(id FMUID)
- func GetTypesPlatform() string
- func GetVersion() string
- func Instantiate(instanceName string, fmuType FMUType, fmuGUID string, ...) C.fmi2Component
- func RegisterModel(model Model) error
- type BaseUnit
- type BooleanType
- type BooleanVariable
- type CoSimulation
- type CoSimulator
- type DeclaredType
- type DisplayUnit
- type EnumerationItem
- type EnumerationType
- type Experiment
- type FMU
- type FMUID
- type FMUShared
- type FMUType
- type IntegerType
- type IntegerVariable
- type Logger
- type LoggerCallback
- type Model
- type ModelDescription
- type ModelExchange
- type ModelExchanger
- type ModelInstance
- type ModelState
- type ModelStructure
- type ModelVariables
- type RealType
- type RealVariable
- type ScalarVariable
- type ScalarVariableType
- type SimpleType
- type StateDecoder
- type StateEncoder
- type Status
- func DoStep(id FMUID, currentCommunicationPoint, communicationStepSize float64, ...) Status
- func EnterInitializationMode(id FMUID) Status
- func ExitInitializationMode(id FMUID) Status
- func GetBoolean(id FMUID, vr ValueReference) ([]bool, Status)
- func GetFMUState(id FMUID) ([]byte, Status)
- func GetInteger(id FMUID, vr ValueReference) ([]int32, Status)
- func GetReal(id FMUID, vr ValueReference) ([]float64, Status)
- func GetString(id FMUID, vr ValueReference) ([]string, Status)
- func Reset(id FMUID) Status
- func SetBoolean(id FMUID, vr ValueReference, bs []bool) Status
- func SetDebugLogging(id FMUID, loggingOn bool, categories []string) Status
- func SetFMUState(id FMUID, bs []byte) Status
- func SetInteger(id FMUID, vr ValueReference, is []int32) Status
- func SetReal(id FMUID, vr ValueReference, fs []float64) Status
- func SetString(id FMUID, vr ValueReference, ss []string) Status
- func SetupExperiment(id FMUID, toleranceDefined bool, tolerance float64, startTime float64, ...) Status
- func Terminate(id FMUID) Status
- type StepResult
- type StringAttributeList
- type StringType
- type StringVariable
- type ToolAnnotation
- type TypeDefinition
- type UintAttributeList
- type Unit
- type Unknown
- type ValueGetter
- type ValueGetterSetter
- type ValueReference
- type ValueSetter
- type VariableCausality
- type VariableInitial
- type VariableType
- type VariableVariability
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetTypesPlatform ¶
func GetTypesPlatform() string
GetTypesPlatform is wrapper for fmi2GetTypesPlatform
func Instantiate ¶
func Instantiate(instanceName string, fmuType FMUType, fmuGUID string, fmuResourceLocation string, loggingOn bool, logFn LoggerCallback) C.fmi2Component
Instantiate returns a new instance of an FMU. If a null pointer is returned, then instantiation failed. In that case, `functions->logger` is called with detailed information about the reason. An FMU can be instantiated many times (provided capability flag canBeInstantiatedOnlyOncePerProcess = false).
This function must be called successfully before any of the following functions can be called. For co-simulation, this function call has to perform all actions of a slave which are necessary before a simulation run starts (for example, loading the model file, compilation...).
Argument `instanceName` is a unique identifier for the FMU instance. It is used to name the instance, for example, in error or information messages generated by one of the fmi2XXXFunctional Mock-up Interface 2.0.2 functions. It is not allowed to provide a null pointer and this string must be non-empty (in other words, must have at least one character that is no white space). [If only one FMU is simulated, as instanceName attribute modelName or <ModelExchange/CoSimulation modelIdentifier=”..”> from the XML schema fmiModelDescription might be used.]
Argument `fmuType` defines the type of the FMU:
- fmi2ModelExchange : FMU with initialization and events; between events simulation of continuous systems is performed with external integrators from the environment
- fmi2CoSimulation : Black box interface for co-simulation.
Argument `fmuGUID` is used to check that the modelDescription.xml file is compatible with the C code of the FMU. It is a vendor specific globally unique identifier of the XML file (for example, it is a “fingerprint” of the relevant information stored in the XML file). It is stored in the XML file as attribute “guid” and has to be passed to the fmi2Instantiate function via argument fmuGUID. It must be identical to the one stored inside the fmi2Instantiate function; otherwise the C code and the XML file of the FMU are not consistent with each other. This argument cannot be null.
Argument fmuResourceLocation is a URI according to the IETF RFC3986 syntax to indicate the location to the "resources" directory of the unzipped FMU archive. [Function fmi2Instantiate is then able to read all needed resources from this directory, for example maps or tables used by the FMU.]
Argument `functions` provides callback functions to be used from the FMU functions to utilize resources from the environment. Only logging is implemented here. Memory management callbacks will be removed in FMI v3.0.
Argument visible = fmi2False defines that the interaction with the user should be reduced to a minimum (no application window, no plotting, no animation, etc.). In other words, the FMU is executed in batch mode. If visible = fmi2True , the FMU is executed in interactive mode, and the FMU might require to explicitly acknowledge start of simulation / instantiation / initialization (acknowledgment is non-blocking). `visible` is ignored by this implementation.
If loggingOn = fmi2True , debug logging is enabled. If loggingOn = fmi2False , debug logging is disabled. [The FMU enable/disables LogCategories which are useful for debugging according to this argument. Which LogCategories the FMU sets is unspecified.]
func RegisterModel ¶
RegisterModel registers a model implementation and description with this FMI implementation. Multiple separate models can be registered, as long as they have different GUIDs. When Instantiated, the model will be looked up by GUID in the generated modelDescription.xml file in the FMI.
Types ¶
type BaseUnit ¶
type BaseUnit struct { // KG exponent of SI base unit "kg" KG *int `xml:"kg,attr,omitempty"` // M exponent of SI base unit "m" M *int `xml:"m,attr,omitempty"` // S exponent of SI based unit "s" S *int `xml:"s,attr,omitempty"` // A exponent of SI based unit "A" A *int `xml:"A,attr,omitempty"` // K exponent of SI based unit "K" K *int `xml:"K,attr,omitempty"` // Mol exponent of SI based unit "mol" Mol *int `xml:"mol,attr,omitempty"` // CD exponent of SI based unit "cd" CD *int `xml:"cd,attr,omitempty"` // Rad exponent of SI based unit "rad" Rad *int `xml:"rad,attr,omitempty"` // Factor for base unit conversion Factor *float64 `xml:"factor,attr,omitempty"` // Offset for base unit conversion Offset *float64 `xml:"offset,attr,omitempty"` }
BaseUnit is used to convert Unit with factor and offset attributes
type BooleanType ¶
type BooleanType struct {
TypeDefinition
}
BooleanType is used for type definitions and in variable types
type BooleanVariable ¶
type BooleanVariable struct { BooleanType DeclaredType // Start is defined as per RealVariable.Start Start *bool `xml:"start,attr,omitempty"` }
BooleanVariable is used in scalar variables to define Boolean
type CoSimulation ¶
type CoSimulation struct { CanHandleVariableCommunicationStepSize bool `xml:"canHandleVariableCommunicationStepSize,attr,omitempty"` CanInterpolateInputs bool `xml:"canInterpolateInputs,attr,omitempty"` MaxOutputDerivativeOrder uint `xml:"maxOutputDerivativeOrder,attr,omitempty"` CanRunAsynchronuously bool `xml:"canRunAsynchronuously,attr,omitempty"` }
CoSimulation defines fields for model and simulation engine/comms tool to a simulation engine. The environment provides the master algorithm to couple FMUs together.
func (CoSimulation) MarshalXML ¶
func (m CoSimulation) MarshalXML(e *xml.Encoder, start xml.StartElement) error
type CoSimulator ¶
type CoSimulator interface { ValueGetterSetter // DoStep is called by fmi2DoStep DoStep( currentCommunicationPoint, communicationStepSize float64, noSetFMUStatePriorToCurrentPoint bool) (StepResult, error) }
CoSimulator implements methods for co-simulation
type DeclaredType ¶
type DeclaredType struct { /* DeclaredType is the name of type defined with TypeDefinitions / SimpleType. The value defined in the corresponding TypeDefinition is used as default. [For example, if “ min ” is present both in Real (of TypeDefinition ) and in “Real” (of ScalarVariable ), then the “min” of ScalarVariable is actually used.] For Real, Integer, Boolean, String, this attribute is optional. For Enumeration it is required, because the Enumeration items are defined in TypeDefinitions / SimpleType. */ DeclaredType string `xml:"declaredType,attr,omitempty"` }
type DisplayUnit ¶
type DisplayUnit struct { // Name of DisplayUnit element, e.g. if Unit name is "rad", DisplayUnit name might be "deg". // Name must be unique with respect to other names in same DisplayUnit list. Name string `xml:"name,attr"` // Factor for display unit conversion Factor *float64 `xml:"factor,attr,omitempty"` // Offset for display unit conversion Offset *float64 `xml:"offset,attr,omitempty"` }
DisplayUnit defines unit conversion for display purposes with factor and offset. A value with respect to Unit is converted with respect to DisplayUnit by the equation: display_unit = factor*unit + offset.
type EnumerationItem ¶
type EnumerationItem struct { Name string `xml:"name,attr"` Value int32 `xml:"value,attr"` Description string `xml:"description,attr,omitempty"` }
EnumerationItem defines an enum item inside an enumeration type
type EnumerationType ¶
type EnumerationType struct { TypeDefinition /* Item of an enumeration has a sequence of “name” and “value” pairs. The values can be any integer number but must be unique within the same enumeration (in order that the mapping between “ name ” and “ value ” is bijective). An Enumeration element must have at least one Item. */ Item []EnumerationItem `xml:"Item,omitempty"` }
EnumerationType is used to define an enumeration that is referenced from variable enumeration types
type Experiment ¶
type Experiment struct { // StartTime is optional start time StartTime *float64 `xml:"startTime,attr,omitempty"` // StopTime is optional stop time StopTime *float64 `xml:"stopTime,attr,omitempty"` // Tolerance is default tolerance Tolerance *float64 `xml:"tolerance,attr,omitempty"` // StepSize is default step size StepSize *float64 `xml:"stepSize,attr,omitempty"` }
Experiment element for model description default experiment
type FMU ¶
type FMU struct { Name string Typee FMUType GUID string ResourceLocation string State ModelState // contains filtered or unexported fields }
FMU represents an active FMU instance
func (*FMU) CoSimulator ¶
func (f *FMU) CoSimulator() (CoSimulator, error)
CoSimulator gets cosimulator instance for the FMU. Returns an error if the fmu type is not cosimulation and implements the interface.
func (*FMU) StateDecoder ¶
func (f *FMU) StateDecoder() (StateDecoder, error)
func (*FMU) StateEncoder ¶
func (f *FMU) StateEncoder() (StateEncoder, error)
func (*FMU) ValueGetter ¶
func (f *FMU) ValueGetter() (ValueGetter, error)
func (*FMU) ValueSetter ¶
func (f *FMU) ValueSetter() (ValueSetter, error)
type FMUID ¶
type FMUID uintptr
FMUID holds a simple pointer that can be shared from this library to the calling system The id is mapped internally to the actual FMU stored in Go memory
type FMUShared ¶
type FMUShared struct { string `xml:"modelIdentifier,attr"` NeedsExecutionTool bool `xml:"needsExecutionTool,attr,omitempty"` CanBeInstantiatedOnlyOncePerProcess bool `xml:"canBeInstantiatedOnlyOncePerProcess,attr,omitempty"` // contains filtered or unexported fields }ModelIdentifier
FMUShared contains fields shared between ModelExchange and CoSimulation
type IntegerType ¶
type IntegerType struct { TypeDefinition // Min is min value, see RealType.Min definition. Min *int32 `xml:"min,attr,omitempty"` // Max is max value, see RealType.Max definition. Max *int32 `xml:"max,attr,omitempty"` }
IntegerType is used for type definitions and in variable types
type IntegerVariable ¶
type IntegerVariable struct { IntegerType DeclaredType // Start is defined as per RealVariable.Start Start *int32 `xml:"start,attr,omitempty"` }
IntegerVariable is used in scalar variables to define Integer
type Logger ¶
type Logger interface { // Error logs an error to the FMU logger Error(err error) // Fatal logs a fatal error to the FMU logger Fatal(err error) // Warning logs warning to FMU logger Warning(msg string) // Discard logs discard message to FMU logger Discard(msg string) // Event logs event message to FMU logger Event(msg string) // Info logs info messages to FMU logger Info(msg string) // contains filtered or unexported methods }
Logger abstracts the fmi2CallbackLogger callback function Log messages are not sent if logging is disabled in fmi2Instantiate
type LoggerCallback ¶
type Model ¶
type Model interface { // Description provides XML compatible model description // used to generated `modelDescription.xml` as well as set defaults for initialisation Description() ModelDescription // Instantiate returns a new model instance. // ModelInstance should be a new thread-safe instance. // Can return an error if the implementation needs to. Instantiate(Logger) (ModelInstance, error) }
Model represents an FMU model to be executed in model-exchange or co-simulation
type ModelDescription ¶
type ModelDescription struct { XMLName xml.Name `xml:"fmiModelDescription"` // Name is the name of the model as used in the modeling environment that generated the XML file. Name string `xml:"modelName,attr"` /* GUID is a “Globally Unique IDentifier” that used to check that the XML file is compatible with the C functions of the FMU. Set this constant in the FMU library so that the XML and library can be verified. */ GUID string `xml:"guid,attr"` // Description optional string with a brief description of the model. Description string `xml:"description,attr,omitempty"` // Author is optional string with the name and organization of the model author. Author string `xml:"author,attr,omitempty"` // Version is optional version of the model, for example “1.0”. Version string `xml:"version,attr,omitempty"` // Copyright is optional information on the intellectual property copyright for this FMU. Copyright string `xml:"copyright,attr,omitempty"` // License is optional information on the intellectual property licensing for this FMU. License string `xml:"license,attr,omitempty"` // GenerationTool is optional name of the tool that generated the XML file. GenerationTool string `xml:"generationTool,attr,omitempty"` /* GenerationDateAndTime is optional date and time when the XML file was generated. The format is a subset of “xs:dateTime” and should be: “YYYY-MM-DDThh:mm:ssZ". */ GenerationDateAndTime *time.Time `xml:"generationDateAndTime,attr,omitempty"` /* NumberOfEventIndicators is the (fixed) number of event indicators for an FMU based on FMI for Model Exchange. For Co-Simulation, this value is ignored. */ NumberOfEventIndicators uint `xml:"numberOfEventIndicators,attr,omitempty"` /* ModelExchange, if present, signals that the FMU is based on “FMI for Model Exchange” [(in other words, the FMU includes the model or the communication to a tool that provides the model, and the environment provides the simulation engine)]. */ ModelExchange *ModelExchange `xml:"ModelExchange,omitempty"` /* CoSimulation, if present, signals that the FMU is based on “FMI for Co-Simulation” [(in other words, the FMU includes the model and the simulation engine, or a communication to a tool that provides the model and the simulation engine, and the environment provides the master algorithm to run coupled FMU co-simulation slaves together)]. */ CoSimulation *CoSimulation `xml:"CoSimulation,omitempty"` /* UnitDefinitions is a global list of unit and display unit definitions [for example, to convert display units into the units used in the model equations]. These definitions are used in the XML element “ModelVariables”. */ UnitDefinitions *[]Unit `xml:"UnitDefinitions>Unit,omitempty"` // TypeDefinitions to be shared by ModelVariables TypeDefinitions *[]SimpleType `xml:"TypeDefinitions>SimpleType,omitempty"` // DefaultExperiment is optional default experiment parameters. DefaultExperiment *Experiment `xml:"DefaultExperiment,omitempty"` // VendorAnnotations is optional data for vendor tools containing list of Tool elements VendorAnnotations *[]ToolAnnotation `xml:"VendorAnnotations>Tool,omitempty"` /* ModelVariables consists of ordered set of "ScalarVariable" elements. The first element has index = 1, the second index=2, etc. This ScalarVariable index is used in element ModelStructure to uniquely and efficiently refer to ScalarVariable definitions. A “ScalarVariable” represents a variable of primitive type, like a real or integer variable. For simplicity, only scalar variables are supported in the schema file in this version and structured entities (like arrays or records) have to be mapped to scalars. */ ModelVariables []ScalarVariable `xml:"ModelVariables>ScalarVariable"` /* ModelStructure defines the structure of the model. Especially, the ordered lists of outputs, continuous-time states and initial unknowns (the unknowns during Initialization Mode) are defined here. Furthermore, the dependency of the unknowns from the knowns can be optionally defined. [This information can be, for example, used to compute efficiently a sparse Jacobian for simulation, or to utilize the input/output dependency in order to detect that in some cases there are actually no algebraic loops when connecting FMUs together.] */ ModelStructure ModelStructure `xml:"ModelStructure"` // contains filtered or unexported fields }
ModelDescription represents root node of a modelDescription.xml file
func (ModelDescription) MarshalXML ¶
func (m ModelDescription) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
func (ModelDescription) MarshallIndent ¶
func (m ModelDescription) MarshallIndent() ([]byte, error)
type ModelExchange ¶
type ModelExchange struct { /* CompletedIntegratorStepNotNeeded, if true, the function fmi2CompletedIntegratorStep need not be called (this gives a slightly more efficient integration). If it is called, it has no effect. If false (the default), the function must be called after every completed integrator step. */ CompletedIntegratorStepNotNeeded bool `xml:"completedIntegratorStepNotNeeded,attr,omitempty"` }
ModelExchange defines fields for model or comms tool that provides a model. The environment provides the simulation engine for the model.
func (ModelExchange) MarshalXML ¶
func (m ModelExchange) MarshalXML(e *xml.Encoder, start xml.StartElement) error
type ModelExchanger ¶
type ModelExchanger interface { ValueGetterSetter }
ModelExchanger implements methods for model exchange
type ModelInstance ¶
type ModelInstance interface { // SetupExperiment called from fmi2SetupExperiment. // error can be returned if there are issues. SetupExperiment(toleranceDefined bool, tolerance float64, startTime float64, stopTimeDefined bool, stopTime float64) error // EnterInitializationMode called from fmi2EnterInitializationMode EnterInitializationMode() error // ExitInitializationMode called from fmi2ExitInitializationMode ExitInitializationMode() error // Terminate called from fmi2Terminate Terminate() error // Reset called from fmi2Reset Reset() error }
ModelInstance represents a live FMU that is being simulated through FMI interface
type ModelState ¶
type ModelState uint
ModelState represents state machine of model
const ( ModelStateStartAndEnd ModelState = 1 << iota ModelStateInstantiated ModelStateInitializationMode // ME states ModelStateEventMode ModelStateContinuousTimeMode // CS states ModelStateStepComplete ModelStateStepInProgress ModelStateStepFailed ModelStateStepCanceled ModelStateTerminated ModelStateError ModelStateFatal )
type ModelStructure ¶
type ModelStructure struct { /* Outputs is an ordered list of all outputs, in other words a list of ScalarVariable indices where every corresponding ScalarVariable must have causality = "output" (and every variable with causality=”output” must be listed here). [Note that all output variables are listed here, especially discrete and continuous outputs. The ordering of the variables in this list is defined by the exporting tool. Usually, it is best to order according to the declaration order in the source model, since then the <Outputs> list does not change if the declaration order of outputs in the source model is not changed. This is, for example, important for linearization, in order that the interpretation of the output vector does not change for a re-exported FMU.]. Attribute dependencies defines the dependencies of the outputs from the knowns at the current super dense time instant in Event and in Continuous-Time Mode (ModelExchange) and at the current Communication Point (CoSimulation). */ Outputs *[]Unknown `xml:"Outputs>Unknown,omitempty"` /* Derivatives is an ordered list of all state derivatives, in other words, a list of ScalarVariable indices where every corresponding ScalarVariable must be a state derivative. [Note that only continuous Real variables are listed here. If a state or a derivative of a state shall not be exposed from the FMU, or if states are not statically associated with a variable (due to dynamic state selection), then dummy ScalarVariables have to be introduced. The ordering of the variables in this list is defined by the exporting tool. Usually, it is best to order according to the declaration order of the states in the source model, since then the <Derivatives> list does not change if the declaration order of states in the source model is not changed. This is, for example, important for linearization, in order that the interpretation of the state vector does not change for a re-exported FMU.]. The number of Unknown elements in the Derivatives element uniquely define the number of continuous time state variables, as required by the corresponding Model Exchange functions (integer argument nx of fmi2GetContinuousStates, fmi2SetcontinuousStates, fmi2GetDerivatives, fmi2GetNominalsOfContinuousStates) that require it. The corresponding continuous-time states are defined by attribute derivative of the corresponding ScalarVariable state derivative element. [Note that higher order derivatives must be mapped to first order derivatives but the mapping definition can be preserved due to attribute derivative. For Co-Simulation, element “Derivatives” is ignored if capability flag providesDirectionalDerivative has a value of false, in other words, it cannot be computed. [This is the default. If an FMU supports both ModelExchange and CoSimulation, then the “Derivatives” element might be present, since it is needed for ModelExchange. If the above flag is set to false for the CoSimulation case, then the “Derivatives” element is ignored for CoSimulation. If “inline integration” is used for a CoSimulation slave, then the model still has continuous-time states and just a special solver is used (internally the implementation results in a discrete-time system, but from the outside, it is still a continuous-time system).] */ Derivatives *[]Unknown `xml:"Derivatives>Unknown,omitempty"` /* InitialUnknowns is ordered list of all exposed Unknowns in Initialization Mode. This list consists of all variables with (1) causality = "output" and ( initial="approx" or "calculated" ), and (2) causality = "calculatedParameter" and (3) all continuous-time states and all state derivatives (defined with element <Derivatives> from <ModelStructure> ) with initial="approx" or "calculated" [if a Co-Simulation FMU does not define the <Derivatives> element, (3) cannot be present.]. The resulting list is not allowed to have duplicates (for example, if a state is also an output, it is included only once in the list). The Unknowns in this list must be ordered according to their ScalarVariable index (for example, if for two variables A and B the ScalarVariable index of A is less than the index of B, then A must appear before B in InitialUnknowns ). Attribute dependencies defines the dependencies of the Unknowns from the Knowns in Initialization Mode at the initial time. */ InitialUnknowns *[]Unknown `xml:"InitialUnknowns>Unknown,omitempty"` }
ModelStructure is with respect to the underlying model equations, independently how these model equations are solved. [For example, when exporting a model both in Model Exchange and Co-Simulation format; then the model structure is identical in both cases. The Co-Simulation FMU has either an integrator included that solves the model equations, or the discretization formula of the integrator and the model equations are solved together (“inline integration”). In both cases the model has the same continuous-time states. In the second case the internal implementation is a discrete -time system, but from the outside this is still a continuous-time model that is solved with an integration method.]
The required part defines an ordering of the outputs and of the (exposed) derivatives, and defines the unknowns that are available during Initialization [Therefore, when linearizing an FMU, every tool will use the same ordering for the outputs, states, and derivatives for the linearized model. The ordering of the inputs should be performed in this case according to the ordering in ModelVariables.] A ModelExchange FMU must expose all derivatives of its continuous-time states in element <Derivatives>. A Co-Simulation FMU does not need to expose these state derivatives. [If a Co-Simulation FMU exposes its state derivatives, they are usually not utilized for the co-simulation, but, for example, to linearize the FMU at a communication point.]
The optional part defines in which way derivatives and outputs depend on inputs, and continuous-time states at the current super dense time instant (ModelExchange) or at the current Communication Point (CoSimulation). [A simulation environment can utilize this information to improve the efficiency, for example, when connecting FMUs together, or when computing the partial derivative of the derivatives with respect to the states in the simulation engine.]
type ModelVariables ¶
type ModelVariables interface { ValueGetterSetter StateEncoder StateDecoder // Variables returns scalar variables to be used in model description Variables() []ScalarVariable }
ModelVariables encapsulates model state as fmi compatible variables. Implements value getting and settings and state encoding.
func NewModelVariables ¶
func NewModelVariables(model interface{}) (ModelVariables, error)
NewModelVariables reflects the provided value to create a model variables list. The type should be a struct with all exported fields. Struct field tags are used to annotate the fields so we can infer model structure. This implementation uses gob encoding to handle state transmission from library.
type RealType ¶
type RealType struct { TypeDefinition // Unit of the variable defined with UnitDefinitions.Unit.name that is used for the model equations. Unit string `xml:"unit,attr,omitempty"` /* DisplayUnit default display unit. The conversion to the “unit” is defined with the element “<fmiModelDescription><UnitDefinitions> ”. If the corresponding “displayUnit” is not defined under <UnitDefinitions><Unit><DisplayUnit>, then displayUnit is ignored. It is an error if displayUnit is defined in element Real, but unit is not, or unit is not defined under <UnitDefinitions><Unit>. */ DisplayUnit string `xml:"displayUnit,attr,omitempty"` /* RelativeQuantity if set attribute to true, then the “offset” of “baseUnit” and “displayUnit” must be ignored (for example, 10 degree Celsius = 10 Kelvin if “relativeQuantity = true” and not 283.15 Kelvin). */ RelativeQuantity bool `xml:"relativeQuantity,attr,omitempty"` /* Min value of variable (variable Value ≥ min ). If not defined, the minimum is the largest negative number that can be represented on the machine. The min definition is information from the FMU to the environment defining the region in which the FMU is designed to operate. */ Min *float64 `xml:"min,attr,omitempty"` /* Max value of variable (variableValue ≤ max ). If not defined, the maximum is the largest positive number that can be represented on the machine. The max definition is information from the FMU to the environment defining the region in which the FMU is designed to operate. */ Max *float64 `xml:"max,attr,omitempty"` /* Nominal value of variable. If not defined and no other information about the nominal value is available, then nominal = 1 is assumed. [The nominal value of a variable can be, for example, used to determine the absolute tolerance for this variable as needed by numerical algorithms: absoluteTolerance = nominal * tolerance *0.01 where tolerance is, for example, the relative tolerance defined in <DefaultExperiment>. */ Nominal *float64 `xml:"nominal,attr,omitempty"` /* Unbounded if true, indicates that during time integration, the variable gets a value much larger than its nominal value. [Typical examples are the monotonically increasing rotation angles of crank shafts and the longitudinal position of a vehicle along the track in long distance simulations. This information can, for example, be used to increase numerical stability and accuracy by setting the corresponding bound for the relative error to zero. */ Unbounded bool `xml:"unbounded,attr,omitempty"` }
RealType is used for type definitions and in variable types
type RealVariable ¶
type RealVariable struct { RealType DeclaredType /* Start is initial or guess value of variable. This value is also stored in the Go data structures. [Therefore, calling fmi2SetXXX to set start values is only necessary, if a different value as stored in the xml file is desired. WARNING: It is not recommended to change the start values in the modelDescription.xml file of an FMU, as this would break the consistency with the hard-coded start values in the C Code. This could lead to unpredictable behaviour of the FMU in different importing tools, as it is not mandatory to call fmi2SetXXX to set start values during initialization. If initial = ′′exact′′ or ′′approx′′ or causality = ′′input′′ , a start value must be provided. If initial = ′′calculated′′ or causality = ′′independent′′ , it is not allowed to provide a start value. Variables with causality = "parameter" or "input" , as well as variables with variability = "constant" , must have a "start" value. If causality = "parameter" , the start -value is the value of it. If causality = "input" , the start value is used by the model as value of the input, if the input is not set by the environment. If variability = "constant" , the start value is the value of the constant. If causality = "output" or "local" then the start value is either an “initial” or a “guess” value, depending on the setting of attribute "initial" . */ Start *float64 `xml:"start,attr,omitempty"` /* Derivative, if present, this variable is the derivative of variable with ScalarVariable index "derivative". [For example, if there are 10 ScalarVariables and derivative = 3 for ScalarVariable 8, then ScalarVariable 8 is the derivative of ScalarVariable 3 with respect to the independent variable (usually time). This information might be especially used if an input or an output is the derivative of another input or output, or to define the states.] The state derivatives of an FMU are listed under element <ModelStructure><Derivatives> . All ScalarVariables listed in this element must have attribute derivative (in order that the continuous-time states are uniquely defined). */ Derivative *float64 `xml:"derivative,attr,omitempty"` /* Reinit only for ModelExchange (if only CoSimulation FMU, this attribute must not be present. If both ModelExchange and CoSimulation FMU, this attribute is ignored for CoSimulation): Can only be present for a continuous-time state. If true, state can be reinitialized at an event by the FMU. If false, state will not be reinitialized at an event by the FMU. */ Reinit bool `xml:"reinit,attr,omitempty"` }
RealVariable is used in scalar variables to define Reals
type ScalarVariable ¶
type ScalarVariable struct { /* Name is the full, unique name of the variable. Every variable is uniquely identified within an FMU instance by this name or by its ScalarVariable index (the element position in the ModelVariables list; the first list element has index=1 ). */ Name string `xml:"name,attr"` /* ValueReference is a handle of the variable to efficiently identify the variable value in the model interface. This handle is a secret of the tool that generated the C functions; it is not required to be unique. The only guarantee is that valueReference is sufficient to identify the respective variable value in the call of the C functions. This implies that it is unique for a particular base data type ( Real, Integer/Enumeration, Boolean, String ) with exception of variables that have identical values (such variables are also called “alias” variables). This attribute is “required”. */ ValueReference uint `xml:"valueReference,attr"` // Description is optional describing the meaning of the variable Description string `xml:"description,attr,omitempty"` /* Causality is an enumeration that defines the causality of the variable. Allowed values of this enumeration: - "parameter": Independent parameter (a data value that is constant during the simulation and is provided by the environment and cannot be used in connections). variability must be "fixed" or "tunable" . initial must be exact or not present (meaning exact). - "calculatedParameter": A data value that is constant during the simulation and is computed during initialization or when tunable parameters change. variability must be "fixed" or "tunable" . initial must be "approx", "calculated" or not present (meaning calculated ). - "input": The variable value can be provided from another model or slave. It is not allowed to define initial. - "output": The variable value can be used by another model or slave. - "local": Local variable that is calculated from other variables or is a continuous- time state. - "independent": The independent variable (usually “time”). All variables are a function of this independent variable. variability must be "continuous". At most one ScalarVariable of an FMU can be defined as "independent". If no variable is defined as "independent" , it is implicitly present with name = "time" and unit = "s" . The default of causality is “ local ”. */ Causality *VariableCausality `xml:"causality,attr,omitempty"` /* Variability enumeration that defines the time dependency of the variable, in other words, it defines the time instants when a variable can change its value. [The purpose of this attribute is to define when a result value needs to be inquired and to be stored. For example, discrete variables change their values only at event instants (ModelExchange) or at a communication point (CoSimulation) and it is therefore only necessary to inquire them with fmi2GetXXX and store them at event times]. Allowed values of this enumeration: - "constant": The value of the variable never changes. - "fixed": The value of the variable is fixed after initialization, in other words, after fmi2ExitInitializationMode was called the variable value does not change anymore. - "tunable": The value of the variable is constant between external events (ModelExchange) and between Communication Points (Co-Simulation) due to changing variables with causality = "parameter" or "input" and variability = "tunable". Whenever a parameter or input signal with variability = "tunable" changes, an event is triggered externally (ModelExchange), or the change is performed at the next Communication Point (Co-Simulation) and the variables with variability = "tunable" and causality = "calculatedParameter" or "output" must be newly computed. - "discrete": ModelExchange: The value of the variable is constant between external and internal events (= time, state, step events defined implicitly in the FMU). Co-Simulation: By convention, the variable is from a “real” sampled data system and its value is only changed at Communication Points (also inside the slave). - "continuous": Only a variable of type = "Real" can be “continuous”. ModelExchange: No restrictions on value changes. Co-Simulation: By convention, the variable is from a differential The default is “continuous”. */ Variability *VariableVariability `xml:"variability,attr,omitempty"` /* Initial is an enumeration that defines how the variable is initialized. It is not allowed to provide a value for initial if causality = "input" or "independent": - "exact": The variable is initialized with the start value (provided under Real , Integer , Boolean , String or Enumeration ). - "approx": The variable is an iteration variable of an algebraic loop and the iteration at initialization starts with the start value. - "calculated": The variable is calculated from other variables during initialization. It is not allowed to provide a “start” value. If initial is not present, it is defined based on causality and variability. */ Initial *VariableInitial `xml:"initial,attr,omitempty"` /* CanHandleMultipleSetPerTimeInstant is only for ModelExchange (if only CoSimulation FMU, this attribute must not be present. If both ModelExchange and CoSimulation FMU, this attribute is ignored for CoSimulation). only for variables with variability = "input" : If present with value = false then only one fmi2SetXXX call is allowed at one super dense time instant (model evaluation) on this variable. That is, this input is not allowed to appear in a (real) algebraic loop requiring multiple calls of fmi2SetXXX on this variable [for example, due to a Newton iteration]. [This flag must be set by FMUs where (internal) discrete-time states are directly updated when assigned (xd := f(xd) instead of xd = f(previous(xd)), and at least one output depends on this input and on discrete states. */ CanHandleMultipleSetPerTimeInstant bool `xml:"canHandleMultipleSetPerTimeInstant,attr,omitempty"` // Annotations contains custom tool annotations for this variable Annotations *[]ToolAnnotation `xml:"Annotations>Tool,omitempty"` *ScalarVariableType }
ScalarVariable represents variable node in ModelVariables
type ScalarVariableType ¶
type ScalarVariableType struct { // Real holds attributes for real (float64) variable Real *RealVariable `xml:",omitempty"` // Integer holds attributes for integer (int32) variable Integer *IntegerVariable `xml:",omitempty"` // Boolean holds attributes for boolean variable Boolean *BooleanVariable `xml:",omitempty"` // String holds attributes for string variable String *StringVariable `xml:",omitempty"` // contains filtered or unexported fields }
func (*ScalarVariableType) Type ¶
func (v *ScalarVariableType) Type() VariableType
type SimpleType ¶
type SimpleType struct { // Name of SimpleType, unique with respect to all other elements in this list. // Name of SimpleType must be different to all "name"s of ScalarVariables. Name string `xml:"name,attr"` // Description of SimpleType. Description string `xml:"description,attr,omitempty"` // Real type Real *RealType `xml:"Real,omitempty"` // Integer type Integer *IntegerType `xml:"Integer,omitempty"` // Boolean type Boolean *BooleanType `xml:"Boolean,omitempty"` // String type String *StringType `xml:"String,omitempty"` // Enumeration type Enumeration *EnumerationType `xml:"Enumeration,omitempty"` }
SimpleType represents shared properties to be used by one or more ScalarVariables. One of the elements Real, Integer, Boolean, String or Enumeration must be present.
type StateDecoder ¶
type StateDecoder interface { // Decode state byte slice and replace internal state or return error Decode([]byte) error }
StateDecoder to be implemented by models that support state serialization Used by fmi2SetFMUstate and fmi2DeSerializeFMUstate.
type StateEncoder ¶
type StateEncoder interface { // Encode internal state into byte slice or return error Encode() ([]byte, error) }
StateEncoder to be implemented by models that support state serialization. Used by fmi2GetFMUstate, fmi2SerializedFMUstateSize and fmi2SerializeFMUstate.
type Status ¶
type Status uint
Status is return status of functions
func DoStep ¶
func DoStep(id FMUID, currentCommunicationPoint, communicationStepSize float64, noSetFMUStatePriorToCurrentPoint bool) Status
DoStep - computation of a time step is started. Argument currentCommunicationPoint is the current communication point of the master (tc i ) and argument communicationStepSize is the communication step size (hc i ). The latter must be > 0.0. The slave must integrate until time instant tc i+1 = tc i + hc i . [The calling environment defines the communication points and DoStep must synchronize to these points by always integrating exactly to tc i + hc i . It is up to DoStep how to achieve this.] At the first call to fmiDoStep after fmi2ExitInitializationMode was called currentCommunicationPoint must be equal to startTime as set with fmi2SetupExperiment . [Formally, argument currentCommunicationPoint is not needed. It is present in order to handle a mismatch between the master and the FMU state of the slave: The currentCommunicationPoint and the FMU state of the slaves defined by former DoStep or fmi2SetFMUState calls have to be consistent with respect to each other. For example, if the slave does not use the update formula for the independent variable as required above, tc i+1 = tc i + hc i (using argument tc i = currentCommunicationPoint of DoStep ) but uses internally an own update formula, such as tc s,i+1 = tc s,i + hc s,i then the slave could use as time increment hc s,i : = (tc i − tc s,i ) + hc i (instead of hc s,i : = hc i ,) to avoid a mismatch between the master time tc i+1 and the slave internal time tc s,i+1 for large i.] Argument noSetFMUStatePriorToCurrentPoint is fmi2True if fmi2SetFMUState will no longer be called for time instants prior to currentCommunicationPoint in this simulation run [the slave can use this flag to flush a result buffer]. The function returns: fmi2OK – if the communication step was computed successfully until its end. fmi2Discard – if the slave computed successfully only a subinterval of the communication step. The master can call the appropriate fmi2GetXXXStatus functions to get further information. If possible, the master should retry the simulation with a shorter communication step size. [Redoing a step is only possible if the FMU state has been recorded at the beginning of the current (failed) step with fmi2GetFMUState . Redoing a step is performed by calling fmi2SetFMUState and afterwards calling DoStep with the new communicationStepSize . Note that it is not possible to change currentCommunicationPoint in such a call.] fmi2Error – the communication step could not be carried out at all. The master can try to repeat the step with other input values and/or a different communication step size in the same way as described in the fmi2Discard case above. fmi2Fatal – if an error occurred which corrupted the FMU irreparably. [The master should stop the simulation run immediatlely.] See section 2.1.3 for details. fmi2Pending – this status is returned if the slave executes the function asynchronously. That means the slave starts the computation but returns immediately. The master has to call fmi2GetStatus(...,DoStep,...) to find out if the slave is done. An alternative is to wait until the callback function fmi2StepFinished is called by the slave. fmi2CancelStep can be called to cancel the current computation. It is not allowed to call any other function during a pending DoStep.
func EnterInitializationMode ¶
EnterInitializationMode informs the FMU to enter Initialization Mode. Before calling this function, all variables with attribute < ScalarVariable initial = "exact" or "approx"> can be set with the `fmi2SetXXX` functions (the ScalarVariable attributes are defined in the Model Description File). Setting other variables is not allowed. Furthermore, fmi2SetupExperiment must be called at least once before calling fmi2EnterInitializationMode, in order that startTime is defined.
func ExitInitializationMode ¶
ExitInitializationMode informs the FMU to exit Initialization Mode. For fmuType = fmi2ModelExchange , this function switches off all initialization equations, and the FMU enters Event Mode implicitly; that is, all continuous-time and active discrete- time equations are available.
func GetBoolean ¶
func GetBoolean(id FMUID, vr ValueReference) ([]bool, Status)
GetBoolean gets boolean values by value reference
func GetFMUState ¶
GetFMUstate makes a copy of the internal FMU state and returns a byte array. (FMUstate). If on entry *FMUstate == NULL, a new allocation is required. If *FMUstate != NULL , then *FMUstate points to a previously returned FMUstate that has not been modified since. In particular, fmi2FreeFMUstate had not been called with this FMUstate as an argument. [Function fmi2GetFMUstate typically reuses the memory of this FMUstate in this case and returns the same pointer to it, but with the actual FMUstate .]
func GetInteger ¶
func GetInteger(id FMUID, vr ValueReference) ([]int32, Status)
GetInteger gets integer values by value reference
func GetReal ¶
func GetReal(id FMUID, vr ValueReference) ([]float64, Status)
GetReal gets real values by value reference
func GetString ¶
func GetString(id FMUID, vr ValueReference) ([]string, Status)
GetString gets string values by value reference
func Reset ¶
Reset is called by the environment to reset the FMU after a simulation run. The FMU goes into the same state as if fmi2Instantiate would have been called. All variables have their default values. Before starting a new run, fmi2SetupExperiment and fmi2EnterInitializationMode have to be called.
func SetBoolean ¶
func SetBoolean(id FMUID, vr ValueReference, bs []bool) Status
SetBoolean sets bools by value references
func SetDebugLogging ¶
SetDebugLogging controls debug logging that is output via the logger function callback. If loggingOn = fmi2True, debug logging is enabled, otherwise it is switched off. If loggingOn = fmi2True and nCategories = 0, then all debug messages shall be output. If loggingOn=fmi2True and nCategories > 0, then only debug messages according to the categories argument shall be output. Vector categories has nCategories elements. The allowed values of categories are defined by the modeling environment that generated the FMU. Depending on the generating modeling environment, none, some or all allowed values for categories for this FMU are defined in the modelDescription.xml file via element `fmiModelDescription.LogCategories `. Supported log categories are in `logger.go`.
func SetFMUState ¶
SetFMUstate copies the content of the previously copied FMUstate back and uses it as actual new FMU state. The FMUstate copy still exists.
func SetInteger ¶
func SetInteger(id FMUID, vr ValueReference, is []int32) Status
SetInteger sets ints by value references
func SetReal ¶
func SetReal(id FMUID, vr ValueReference, fs []float64) Status
SetReal sets floats by value references
func SetString ¶
func SetString(id FMUID, vr ValueReference, ss []string) Status
SetString sets strings by value references
func SetupExperiment ¶
func SetupExperiment(id FMUID, toleranceDefined bool, tolerance float64, startTime float64, stopTimeDefined bool, stopTime float64) Status
SetupExperiment informs the FMU to setup the experiment. This function must be called after fmi2Instantiate and before fmi2EnterInitializationMode is called. Arguments toleranceDefined and tolerance depend on the FMU type:
fmuType = fmi2ModelExchange: If `toleranceDefined = fmi2True`, then the model is called with a numerical integration scheme where the step size is controlled by using `tolerance` for error estimation (usually as relative tolerance). In such a case, all numerical algorithms used inside the model (for example, to solve non-linear algebraic equations) should also operate with an error estimation of an appropriate smaller relative tolerance.
fmuType = fmi2CoSimulation: If `toleranceDefined = fmi2True`, then the communication interval of the slave is controlled by error estimation. In case the slave utilizes a numerical integrator with variable step size and error estimation, it is suggested to use `tolerance` for the error estimation of the internal integrator (usually as relative tolerance). An FMU for Co-Simulation might ignore this argument.
The arguments startTime and stopTime can be used to check whether the model is valid within the given boundaries or to allocate memory which is necessary for storing results. Argument startTime is the fixed initial value of the independent variable 5 [if the independent variable is `time`, startTime is the starting time of initializaton]. If `stopTimeDefined = fmi2True`, then `stopTime` is the defined final value of the independent variable [if the independent variable is `time`, stopTime is the stop time of the simulation] and if the environment tries to compute past stopTime the FMU has to return `fmi2Status = fmi2Error`. If `stopTimeDefined = fmi2False`, then no final value of the independent variable is defined and argument stopTime is meaningless.
func Terminate ¶
Terminate informs the FMU that the simulation run is terminated. After calling this function, the final values of all variables can be inquired with the fmi2GetXXX(..) functions. It is not allowed to call this function after one of the functions returned with a status flag of fmi2Error or fmi2Fatal .
type StepResult ¶
type StepResult uint
StepResult is returned from cosim DoStep
const ( // StepResultSuccess means DoStep worked fine StepResultSuccess StepResult = iota // StepResultPartial means only a partial result was computed StepResultPartial // StepResultAsync means the slave has returned and is running async StepResultAsync )
func (StepResult) Status ¶
func (r StepResult) Status() Status
type StringAttributeList ¶
type StringAttributeList []string
StringAttributeList represents space delimited list of strings in an xml attribute
func (StringAttributeList) MarshalText ¶
func (l StringAttributeList) MarshalText() (text []byte, err error)
type StringType ¶
type StringType struct {
TypeDefinition
}
StringType is used for type definition and in variable types
type StringVariable ¶
type StringVariable struct { StringType DeclaredType // Start is defined as per RealVariable.Start Start string `xml:"start,attr,omitempty"` }
StringVariable is used in scalar variables to define String
type ToolAnnotation ¶
ToolAnnotation is a tool specific annotation. Allows any xml to be embedded for another system to use.
type TypeDefinition ¶
type TypeDefinition struct { // Quantity is the physical quantity of the variable, for example Angle or Energy. Quantity string `xml:"quantity,attr,omitempty"` }
type UintAttributeList ¶
type UintAttributeList []uint
UintAttributeList represents space delimited list of unsigned integers in an xml attribute
func (UintAttributeList) MarshalText ¶
func (l UintAttributeList) MarshalText() (text []byte, err error)
type Unit ¶
type Unit struct { // Name of unit element, e.g. N.m, Nm, %/s. Name must be unique with respect to all other elements of the UnitDefinitions list Name string `xml:"name,attr"` // BaseUnit is optional unit conversion BaseUnit *BaseUnit `xml:"BaseUnit,omitempty"` // DisplayUnits for Unit to display types DisplayUnits []DisplayUnit `xml:"DisplayUnit,omitempty"` }
Unit is defined by its name attribute such as “N.m” or “N*m” or “Nm”, which must be unique with respect to all other defined elements of the UnitDefinitions list. If a variable is associated with a Unit , then the value of the variable has to be provided with the fmi2SetXXX functions and is returned by the fmi2GetXXX functions with respect to this Unit.
type Unknown ¶
type Unknown struct { // Index is ScalarVariable index of Unknown Index uint `xml:"index,attr"` /* Dependencies attribute defining the dependencies of the unknown v unknown (directly or indirectly via auxiliary variables) with respect to v known . If not present, it must be assumed that the Unknown depends on all Knowns. If present as empty list, the Unknown depends on none of the Knowns. Otherwise the Unknown depends on the Knowns defined by the given ScalarVariable indices. The indices are ordered according to magnitude, starting with the smallest index. */ Dependencies UintAttributeList `xml:"dependencies,attr,omitempty"` /* DependenciesKind is an attribute list of type of dependencies in "dependencies" attribute. If not present, it must be assumed that the Unknown v unknown depends on the Knowns v known without a particular structure. Otherwise, the corresponding Known v known,i enters the equation as: If "dependenciesKind" is present, "dependencies" must be present and must have the same number of list elements - dependent: no particular structure Only for Real unknowns: - constant: constant factor Only for Real unknowns in event and continuous-time mode (model exchange) and at comms points (CoSimulation), and not for InitialUnknowns for Initialization Mode: - fixed: fixed factor - tunable: tunable factor - discrete: discrete factor */ DependenciesKind StringAttributeList `xml:"dependenciesKind,attr,omitempty"` }
Unknown is dependency of scalar Unknown from Knowns in Continuous-Time and Event Mode (ModelExchange), and at Communication Points (CoSimulation): Unknown=f(Known_1, Known_2, ...). Knowns are "inputs", "continuous states" and "independent variable" (usually time).
type ValueGetter ¶
type ValueGetter interface { // GetReal called from fmi2GetReal GetReal(ValueReference) ([]float64, error) // GetInteger called from fmi2GetInteger GetInteger(ValueReference) ([]int32, error) // GetBoolean called from fmi2GetBoolean GetBoolean(ValueReference) ([]bool, error) // GetString called from fmi2GetString GetString(ValueReference) ([]string, error) }
ValueGetter retrieves values from the model
type ValueGetterSetter ¶
type ValueGetterSetter interface { ValueGetter ValueSetter }
type ValueSetter ¶
type ValueSetter interface { // SetReal called from fmi2SetReal SetReal(ValueReference, []float64) error // SetInteger called from fmi2SetInteger SetInteger(ValueReference, []int32) error // SetBoolean called from fmi2SetBoolean SetBoolean(ValueReference, []bool) error // SetString called from fmi2SetString SetString(ValueReference, []string) error }
ValueSetter sets values in the model
type VariableCausality ¶
type VariableCausality uint
VariableCausality enum for scalar variable
const ( // Variable causality local is default VariableCausalityLocal VariableCausality = iota VariableCausalityParameter VariableCausalityCalculatedParameter VariableCausalityInput VariableCausalityOutput VariableCausalityIndependent )
func (*VariableCausality) MarshalText ¶
func (e *VariableCausality) MarshalText() (text []byte, err error)
func (*VariableCausality) UnmarshalText ¶
func (e *VariableCausality) UnmarshalText(text []byte) error
type VariableInitial ¶
type VariableInitial uint
VariableInitial enum for scalar variable
const ( // Variable initial will be unset if omitted VariableInitialExact VariableInitial = iota VariableInitialApprox VariableInitialCalculated )
func (*VariableInitial) MarshalText ¶
func (e *VariableInitial) MarshalText() (text []byte, err error)
func (*VariableInitial) UnmarshalText ¶
func (e *VariableInitial) UnmarshalText(text []byte) error
type VariableType ¶
type VariableType uint
VariableType enum for type definitions and scalars variables
const ( VariableTypeReal VariableType = iota + 1 VariableTypeInteger VariableTypeBoolean VariableTypeString VariableTypeEnumeration )
type VariableVariability ¶
type VariableVariability uint
VariableVariability enum for scalar variable
const ( // Variable variability continuous is default VariableVariabilityContinuous VariableVariability = iota VariableVariabilityConstant VariableVariabilityFixed VariableVariabilityTunable VariableVariabilityDiscrete )
func (*VariableVariability) MarshalText ¶
func (e *VariableVariability) MarshalText() (text []byte, err error)
func (*VariableVariability) UnmarshalText ¶
func (e *VariableVariability) UnmarshalText(text []byte) error