This page is meant to help new users of vCalc make their own equations, calculators, constants, and collections. For any type of vCalc content, you should be familiar with your chosen subject, the type of page (equations, calculator, etc), and the programming language vCalc uses at the time of this writing. If you haven't written code before, don't worry; vCalc has gone to great efforts to make it as simple as possible. This page will provide explanations that assume you know little to nothing about programming, though it will mark which parts more experienced coders can likely skip.
This page will describe one way to go about creating vCalc content, but there is more than one way. If you find that a different approach works better for you, then by all means, have at it.
Just because all of this information in on this one page doesn't mean that you have to learn it all in one go. If you're just looking to make an equation, then there are at least two things you need to know: some basic programming (the "Coding in Groovy" section) and how to create/modify an equation (the "Equations" section). Don't be afraid to take a piecemeal approach, learning what you need one bit at a time. Perhaps one day you can read about Groovy code, and the next day you try to write some. Maybe one day you create an equation, the next day you learn how to take in values from the user with the Algorithms tab. If you decide to write a wiki for your equation, there's a crash-course in that too: the "Wiki-writing" section. All of this information is compiled here for your convenience, and you should learn it at whatever pace is most comfortable for you.
If you're creating a tool for personal use, then whether or not you write a wiki for it is up to you. However, if you plan to make the tool publicly available, then it's strongly recommend that you write a wiki so that others are sure of how to use it. There are some cases where you don't need a very long wiki. If you're making a collection, for example, then you have the option to make a more exhaustive calculator wiki. Then you could write short equation wikis that link the user to the calculator wiki if they want more information.
You may edit a page's wiki by clicking the "Edit" button. Clicking the "Edit" button will take you to the 'Wiki' view. If you instead click the small, down-facing arrow next to "Edit", you will be given the options of 'Wiki' and 'WYSIWYG'. Depending on the type of page you're on, you will receive additional options that are related to the content, not the wiki.
If you do write a wiki and you include information that you took from a book, website, or some other source, then please give the original source credit via some version of a footnote or citation. Very simple information, like "France is a country" or "2+2=4" doesn't need a citation, but more uncommon or complex information should probably be cited in some way. If you're not comfortable with creating citations, then a website like www.easybib.com (or some equivalent webiste, there are many) can help you.
Failing that, even a simple shout-out to the original source can be enough to give them credit. For example, if I'm presenting an mathematical equation that I take from Hypothetical Textbook on page 123, then I could write: "Hypothetical Textbook presents this mathematical equation on page 123 for...", and then I could continue talking about the equation and readers will know where I got my information. Mentioning your sources both makes sure they get proper credit, but also makes you sound more trustworthy.
The Wiki view allows you to make more detailed and complicated changes to the wiki page. I would recommend that people just starting out with vCalc stick to WYSIWYG for a while.
If you want to learn the Wiki syntax, then take a look at this help page.
If you choose to edit via the WYSIWYG view, you will be brought to a screen with two tabs, the WYSIWYG tab and the Source tab. You first start on the WYSIWYG tab. You can click the tab names to switch between them.
The WYSIWYG (What You See Is What You Get) view is just that: what you see on the screen as you type is what you'll get as the wiki page after hitting "Save & View". If you've used Microsoft Word or a similar text editor before, then WYSIWYG will probably seem somewhat familiar. There are a number of buttons near the top of the WYSIWYG tab that let you insert symbols, choose font size, link to equations, and more.
Most of the buttons are fairly straightforward. The dropdown box that defaults to "plain text" allows you to change font size. "Heading 1" is the largest available font size. "Heading 6" is the smallest, even smaller than plain text. I recommend sifting through the buttons to the right of the font-size dropdown; they allow you to insert equations into your wiki, or create an equation pop-up when clicked.
The "Source" tab shows what you would have to type in the "Wiki" editing view to create the page you designed with the WYSIWYG. The Source tab doesn't have the buttons at the top to help you out that the Wiki editor does, but it is a convenient way to learn the Wiki syntax.
The first step to writing a wiki really starts before you type anything. Make sure you're familiar with the subject. If you're writing an equation that's meant to help someone with calculating the total cost of a home loan, then it will help if you have a general understanding of home loans and how they're paid off. This understanding will help with writing not only the wiki, but with ensuring that the related math is correct. Prep-work is also a great time to find sources to cite, if the topic warrants citation.
Once you begin writing the actual wiki, there are a few things to keep in mind. The very first sentence is used for search results, both by vCalc and other search engines such as Google. It helps people know if your tool is what they're looking for if the wiki page begins with a sentence like: "The [equation name] is a tool to help [purpose of equation]". Using the example of a home-loan-related equation, the first sentence might be "The total price of a home loan equation calculates how much a mortgage will cost you and how long it will take to pay off for a given monthly payment."
The rest of the first paragraph should introduce the reader to the general context of the wiki-page. For example, why would someone use this equation? Where does it come from?
The rest of the wiki, ideally, will explain how to use the calculator/equation/content. The wiki body is difficult to outline in detail because it's often where the writer may be most creative. You could go into greater detail about the chosen subject, such as further analyzing a formula or explaining its derivation. You could include a picture related to the topic. You could link to other equations or calculators. The list goes on.
Bayes' Theorem for Disease Testing - this equation's wiki presents a good example of using the wiki body to walk the user through using the content, and breaking a fairly complex idea into something manageable for those who aren't well versed in Bayesian probability theory.
Understanding Eigenvalues and Eigenvectors of a 2x2 Matrix - this calculator's very thorough wiki demonstrates how the wiki body can be used to dive deeper into a given topic.
Rolling Offsets (run) - this equation's wiki uses the first line to present a summary of the equation's purpose, includes a descriptive picture, provides a link to a related equation, and even links to a YouTube video walking the viewer through using the equation.
vCalc currently uses the programming language Groovy. In the future, vCalc may support additional programming languages, but Groovy is the only option at the time of this writing. Groovy is based on Java, so if you're familiar with Java or a similar programming language, then you should be able to skip certain parts of this discussion. A note to Java coders: Groovy is Java-based, but you don't need to end every line with a semicolon.
vCalc Groovy Code Sample is a vCalc help page that provides examples of a lot of Groovy code. If you're an experienced coder, then seeing this sample might be enough to get you started. If you're not, then hopefully you'll be able to read this section and have a good idea of what's happening in the sample.
One of the most common ways to learn coding is to find someone else's code and see if you can figure out how it works. vCalc has an easy way to do that; at the bottom of every equation page is a "Show Algorithm" button that lets you take a peek at the equation's code. If you need a closer look at the code, then you can click the "Duplicate" above and to the left of the equation's wiki. A private copy of someone else's code is a good opportunity to mess around with it a bit, to see if you really understand how it works. If you're just looking to fiddle around with some code, please remember to mess with a private duplicate rather than someone's public code. Instructions on duplicating an equation can be found at Duplicating an Equation. Duplicating other types of content works in essentially the same way.
To get you started on Groovy, we'll run through the basics and provide links to more detailed discussions on the topics. This might be too much to take in all at once; that's alright. It's perfectly fine to just skim this article for whatever answers you need at this moment. Note; we usually write codes in lines, where each new instruction is put on the next line by hitting the "enter" key (or equivalent).
We'll start at the end of every equation - the return command. The return command will take a value and send it to the user as the answer. For example, if the answer to our equation is stored in the variable x, then "return x" will send the value of "x" to the user. If you don't include a "return" anywhere in your code, then vCalc will simply "return" the last value it looked at when running your code. To make sure we know what the user will see, we use the "return" command, rather than betting that vCalc finds the right value to return.
Once you return a value to the user, vCalc will ignore the rest of your code. It ends the algorithm.
Variables in coding are very similar to variables in math - symbols that represent a value. Groovy requires you to "define" variables like so: "def x = 5". If we write the following code:
def x = 5
return x
Then the code will assign a value of 5 to the variable x. Then the code "returns" the value of x, 5, to the user. Giving a variable a value the first time is called "assigning". In the example, we assigned x the value of 5. We can give it a new value with similar code. This is sometimes called "reassigning".
def x = 5
x = 7
return x
First, we defined x and assigned it a value of 5. Next, we reassigned x the value of 7. We didn't have to use the "def" command this time because we had already told the computer that x is a variable with our first "def" command. Finally, we return the value of x, in this case 7, to the user.
Trying to read code you haven't seen before can be confusing. To help people understand our code, or to help us keep track of our own code, programmers use comments. In Groovy, the simple way to comment your code is to type "//". The rest of the line after the "//" won't be treated as code, so it can be used to leave notes for yourself or others.
For comments that might be longer than a line, we can use /* and */. /* will start a comment, and the next */ will end it, even if it's many lines later. Everything in between the /* and */ will be treated as a comment, not as code. Comments will be red in our examples. We could comment our earlier code like:
def x = 5 // we define the variable "x" and assign it a value of 5
return x /* we return the value of x, 5
to the user */
For a short bit of code like we have here, comments may feel unnecessary. As your code gets longer or more complicated, comments can help you sort it out. Since this is a tutorial, we'll comment heavily to make the code as clear as possible.
Having just one variable is nice. We can make a second variable with a similar command. But how do those variables interact? One of the most common ways is arithmetic operations. Let's assume that for the following examples, x = 5, y = 2. More information on the operators used in Groovy can be found at the Groovy documentation.
For experienced coders: the power operator is different from Java, and vCalc treats all division as decimal or float division.
vCalc can do a lot of math, but let's start with something simple - taking the ratio of two numbers.
def x = 4 //define a variable x and give it a value of 4
def y = 2 //define a variable y and give it a value of 2
def ratio = x/y //define a variable 'ratio' and give it a value of 4/2 = 2
return ratio //send the value of ratio, 2, back to the user
If you're not planning to use units for your equation, then you can probably skip this section for the time being. However, if you are going to use units, then you should probably read this section. If this isn't enough, here are the vCalc help pages related to units:
Groovy has support for scientific units, and vCalc has built a lot of their functionality around that. What if we want to make an equation that takes the ratio of two lengths, instead of two arbitrary numbers? If a number or variable doesn't already have units, we can assign it units like so:
def x = 5."m" //defined and assigned x a value of 5 meters
return x //we return the value of x, 5 meters, to the user
Why do we bother with units? Well, they're really handy for measuring things. vCalc also has the ability to convert between units easily. If we return 5 meters to the user, then the user can use vCalc to quickly and easily convert 5 meters to feet, inches, yard, miles, kilometers, nanometers, even astronomical units. This way, we usually won't have to worry about how the user wants the answered measured, whether in kg or pounds. Instead, we give them one value, and they can change it to the form they want.
We can also do math with units. When we add (or subtract) two values of the same units (they must be the same for +/- ), the units stay the same. `5 ft + 5 ft = 10 ft`. When we multiply two values with units, the units multiply, often expressed as a power. `5 ft * 5 ft = 25 ft^2`. When we divide two values of the same units, the units 'cancel out'. `(5 ft )/ (5 ft) = 1 (ft)/(ft) = 1`. Armed with that knowledge, let's take the ratio of two lengths:
def x = 5."m" //we defined and assigned x a value of 5 meters
def y = 2."m" //we defined and assigned y a value of 2 meters
def ratio = x/y /* we define ratio and assign it a value of 5 meters / 2 meters = 2.5, no units because the meters cancelled out */
return ratio //returns 2.5
In this example we see that x is 2.5 times longer than y.
What if x and y have different units? Well, some units can convert from one to another. There are 12 inches in a foot. There are 100 centimeters in a meter. However, some units don't convert. How many pounds are in a meter? That question doesn't really make sense, so we don't convert between pounds and meters. vCalc is smart enough to convert units on its own, provided that there is a conversion between them.
def x = 5."m" //defined and assigned x a value of 5 meters
def y = 2."ft" //defined and assigned y a value of 2 feet
def ratio = x/y /* when vCalc tries to do 5 meters / 2 feet, it has to convert feet to meters. 2 feet is about .61 meters, so vCalc instead calculates 5 meters / .61 meters = 8.2 (we're rounding here, vCalc wouldn't). */
return ratio //returns 8.2 to the user
Even though x was in meters and y in feet to start, we can see that x is 8.2 times longer than y. This example relied on vCalc to convert between units.
We can tell vCalc which units to convert to with a .to("desired units") command. The following code is essentially equivalent to the previous example, but with us telling vCalc when and how to convert units:
def x = 5."m" //defined and assigned x the value of 5 meters
def y = 2."ft".to("m") //defined and assigned y the value of 2 feet
def ratio = x/y //defined and assigned ratio a value of 5 meters / .61 meters = 8.2 meters
return ratio //returns 8.2 to the user
So far we've covered how to define and process variables, but right now, users aren't any part of the equation. The numbers are coded in, and the same answer will be given every time. For an equation to be useful, we need to let the user decide what values we use.
We take in input from the user via an args command, like so:
def x = args.X /* defines x and assigns it a value decided by the user. Here, X could be whatever you want - x, X, argument, first, stuff, etc. */
return x //returns the value of x, whatever the user gave it
You can set restrictions on what the user enters and more. To learn the finer points about taking in information via the args command, please check the Using the Equation Editor Algorithm Tab. For this section, we'll just use args (or the equivalent #) as taking in input and ignore the "args parameter map".
Let's revisit our example of the ratio of lengths, now with user input:
def x = args.X /* defines and assigns x a value decided by the user. Let's assume that the user enter a length, a restriction you can easily set using the args parameter map. */
def y = #Y // As we mentioned, #Y is equivalent to args.Y
def ratio = x/y //computes x/y and assigns the value to 'ratio'
return ratio
Now we have an equation that finds the ratio of any two lengths provided by the user.
There are a lot of ways a user can enter bad data. For example, a negative mass doesn't really make sense. In our example, where we're dividing two lengths, we could run into a snag if the user enters 0 for y - dividing by 0. Instead, we can use an "assert" command to make sure that the data is how we want it, and stop the equation if it's not.
Before we get to assert commands, we should look at logical operators. Logical operators give you either TRUE or FALSE.
If you're planning to write an equation that will require checking multiple logical statements at once, then I'd recommend looking at the AND (&&) and OR (||) operators, or just read more about the logical operators in general, at this Groovy documentation page. We've called all of these operators "logical operators" to simplify things, but in the documentation they're divided between Relational operators, Logical operators, and Conditional operators.
Assertion commands require two things: a logical statement and an error message. To check if y is 0, we can code:
def x = args.x //takes in a length from the user and assigns it to x
def y = args.y //takes in a length from the user and assigns it to y
assert y != 0."m" : "Let's not divide by zero" //to make sure we don't divide by 0
def ratio = x/y //assigns the variable of x/y to 'ratio'
return ratio
Notice the third line of code, "assert y !=0."m" : "Let's not divide by zero". Assertion commands follow the formula of: assert [logical statement] : "[Error message]", and you fill in the brackets with whatever is appropriate. If the logical statement is FALSE, then the assertion command will stop the equation and return the error message. If the logical statement is TRUE, then the equation keeps going. We used 0."m" instead of 0 because 0 is a number, whereas 0."m" is a length. Since y is a length, we should compare it to another length.
The assertion command's logical statement should be what you need for the equation to go forward. In the example above, the assertion commands tells the computer: if y isn't 0, continue on. Otherwise, if y is 0, then give the user the error message."
Negative lengths don't really make sense for this equation, so we can add a little more error checking:
def x = args.x
def y = args.y
assert x >= 0."m" : "x should be at least 0 meters long" /* we aren't dividing by x, so it can be 0, but it at least shouldn't be negative */
assert y > 0."m" : "y should be greater than 0 meters" /* y shouldn't be negative or 0, so we make sure it's greater than 0. */
def ratio = x/y
return ratio
Now the example equation we've been building is reasonably error-proof.
If you're familiar with Java, you can definitely skip this section. Groovy uses the state control structures as Java. There are many control structures, and they're all discussed in section 1.3 of the Groovy semantics documentation.
One of the most commons control structures is the if-statement. We can use an if-statement to mimic an assert like so:
def x = args.x
def y = args.y
if (!(x >= 0."m")) { //if x is not greater than or equal to 0."m", then run the return line
return "x should be at least 0 meters long"
}
if (!(y > 0."m")) { //if y is not greater than 0."m", then run the return line
return "y should be greater than 0 meters"
}
def ratio = x/y
return ratio
The if-statement follows the pattern of: if (logical statement) {...code in brackets...}. The code in the brackets will only run if the logical statement is TRUE. We can follow an if-statement with an else-statement, like so:
def x = args.x
def y = args.y
if (!(x >= 0."m")) {
return "x should be at least 0 meters long"
} else { // the "else" only happens if the previous if-statement was FALSE.
assert y > 0."m" : "y should be greater than 0 meters"
}
def ratio = x/y
return ratio
An else-statement only runs if the previous if-statement's logical statement evaluated to FALSE. In the example above, the assert command only runs if x is greater than or equal to 0."m". We've done two unrelated if-statements, and an if-else-statement, but what if you have two if-statements and the second one only needs to run if the first one failed? That's when we use an else-if, with syntax like:
def x = args.x
def y = args.y
if (!(x >= 0."m")) {
return "x should be at least 0 meters long"
} else if (!(y > 0."m")) { //this else-if only runs if the previous if was FALSE
return "y should be greater than 0 meters"
}
def ratio = x/y
return ratio
In this example, the computer will only bother to check y's length if x's length has already passed inspection (technically this would be the case anyway since x not passing inspection would have triggered a return, ending the program).
Now that we have control statements, we can worry about returning more complicated answers. A "String" is a computer science word for a certain kind of data. More information is available about Groovy Strings at this Groovy documentation page, but we'll provide a basic rundown here. Strings get their name because they're essentially strings of characters. A bunch of characters, one after the other. Strings can be words ("potato"), sentences ("Potatoes contain starch."), a bunch of spaces (" "), random gibberish ("asldkfj9283hf"), or anything in between.
We can add Strings with the +, but that's about the only arithmetic operator that works with them. Adding two Strings will concatenate them, attaching the second to the end of the first. E.g. "Hello" + " there!" = "Hello there!"
We can add numbers or variables to strings like so: "x is " + 5 = "x is 5". If we instead add the variable x, "x is " + x, then we'll get a string that says "x is " and then the value of x. For example if we previously assigned x a value of 3, then we'd get "x is 3".
How does this relate to our previous examples? Well, what if instead of just telling the user the size of x compared to y, we could tell them which was bigger too? It's a relatively small change for us, but this flexibility can open a lot of doors when you're coding something more complicated. We'll use assert commands for our error checking since that's their purpose, and if-statements for our comparison of x and y.
def x = args.x
def y = args.y
assert x > 0."m" : "x should be greater than 0 meters" /* x isn't allowed to be 0."m" anymore since we might divide by it */
assert y > 0."m" : "y should be greater than 0 meters"
if (x == y) { //checks if x and y are equal lengths
return "They're equal lengths"
} else if (x > y) { //checks if x is longer than y
return "Length x is " + x/y + " times longer than length y"
} else { /* the only option left is that y ix longer than x. If we've made it this far, we know that must be the case */
return "Length y is " + y/x + "times longer than length x"
}
Here are some examples of vCalc code. Simply click the link and navigate to "Show Algorithm".
meanDensity Lookup - this is a good example of an equation that references a dataset. It may help if you see this Finding Dataset IDs page. Note: in Groovy, and just about every other programming language, you can substitute 1 is treated like TRUE and 0 is treated like FALSE if you use them in a logical statement.
Magic the Gathering - Opening Hand Mana Curve - even if you aren't familiar with the card game Magic the Gathering, this equation still provides a good example of if-statements and assertions.
To create any kind of vCalc content, you must first be logged into vCalc. This section is meant as an introductory summary of the types of content available and how to use them. If you don't find what you're looking for here, then you might have more luck with either the examples or the vCalc Knowledge Base.
To create a vCalc equation, click create (in the upper right hand corner), then select equation. This will bring you to the Equation Editor page. This page as multiple section:
Those are the different pages and tabs you'll see when when you create an equation. Let's revisit the Algorithm tab. The details of coding are in the Coding in Groovy section, but we can talk here about the general format of an equation algorithm. There are many ways to code your equation, but a good place to start is:
For more complex equations, you may need to repeat steps 2 and 3, re-checking and re-processing data that has already been checked and processed.
Here some examples of equations that follow the above 3-step formula. The easiest way to check an equation's code is to hit the "Show Algorithm" button near the bottom of the page. For whatever reason, the code showed by "Show Algorithm" sometimes gets cut off. If you need a closer look at the code, just duplicate the page for a private copy.
The Floor - Area equation's algorithm is fairly straightforward. Takes in values, checks values, returns answer.
Critical Angle - this equation's algorithm follows the 3-step formula and uses both asserts and if-statements to check the values.
Currently, constants are a separate content type in vCalc, but they're very similar to equations. To create a constant, click the "Create" button in the upper right-hand corner of the vCalc page and then click "Constant" in the list that appears. This will bring to the Constant Editor page with Info, Markup, Algorithm, Test, and Permissions tabs. These tabs work just the same as the Equation tabs described in the previous section.
Any code entered in the constant's Algorithm tab will function just as it would if it were in an equation's Algorithm tab, with one notable exception: constant can't take in information from the user. # or arg commands will not work in a constant's Algorithm tab.
Gold SPOT - here's an example of an equation that doesn't simply return a set value. It doesn't take in values from the user. Instead, it references a dataset that contains the recent prices of precious metals.
c (speed of light) with units m/s - this is a more standard example of a constant, returning a set value with set units.
To create a vCalc Calculator, click "Create" in the upper right corner, and then select "Calculator" from the list that appears. This will take you to the Calculator Editor page with Info, Design, and Permissions tabs. The Info and Permissions tabs are the same as the Equation Editor's Info and Permissions tabs.
Titration of weak acid with a strong base - an example of how button can be color coded to make finding the appropriate equation easier.
Statistical Decision Tree - a good use of multiple tabs to separate many equations into smaller groups.
Collections are very similar to Calculators, minus the buttons. There's more than one way create a collection. The first way:
The second way to create a collection is relate to how you add an equation to the collection, so let's cover them both here:
To edit a collection, navigate to your collections. For each of your collections, you should have the option to either "Edit" or "Delete". The edit button will bring up a list of "Edit Collection", "Wiki", and "WYSIWYG". The "Edit Collection" option brings you to a page that allows you to:
Corn Grain Yield Estimation - this collection demonstrates how the creative use of a table allows a collection to be just as user-friendly as a calculator, if not more so.
To create a dataset, click "Create" in the upper right-hand corner of the screen and selecting "Dataset". This will bring you to the Dataset Editor with Info, Design, and Permissions tabs. The Info and Permissions tabs work like they do for an equation.
Once you save the dataset, you should be brought to its wiki page. There will be an edit button up and to the right of the wiki. If you click the arrow next to "Edit", you should see "Use this Dataset" and "Dataset Definition" among the options provided. "Dataset Definition" will bring you back to the Dataset Editor. "Use this Dataset" is how you enter data into the dataset. Clicking "Use this Dataset" will bring you a page with "Grid" and "Form" tabs. The "Form" tab allows you to fill out new entries, while the "Grid" tab will let you both add entries and view pre-existing entries.
To get back to your dataset's wiki page, the best bet is to just hit the back button.
meanDensity - this dataset has three columns: a "Substance" column that stores the material's name, a "meanDensity" column that stores the material's average density, and a "nominalState" column that stores the state of matter you're most likely to encounter this material in (solid, liquid, or gas).
Two-way Atmospheric Loss Rate (Radar) - here's an example of a dataset with four columns: "weather" describing the amount of rain, "altitude (kft)" describing the altitude of the radar, "band" describing the frequency of the radar waves, and "rate" describing how quickly the wave dies away.