document state priority

Author: vyudu

docs/src/basics/Variable_metadata.md

@@ -186,6 +186,15 @@ it can be accessed in [callbacks](@ref events)
 isirreducible(important_value)
 ```
 
+## State Priority
+
+When a model is structurally simplified, the algorithm will try to ensure that the variables with higher state priority become states of the system. A variable's state priority is a number set using the `state_priority` metadata.
+
+```@example metadata
+@variable important_dof [state_priority = 10] unimportant_dof [state_priority = 2]
+state_priority(important_dof)
+```
+
 ## Units
 
 Units for variables can be designated using symbolic metadata. For more information, please see the [model validation and units](@ref units) section of the docs. Note that `getunit` is equivalent to `get_unit`.