kOS Autopilot

[Dunbaratu]

In general, a reference manual and a tutorial are two utterly different types of documentation. They should not be done using the same document. A reference manual gives a complete list of everything thats true about thing A then a complete list of everything thats true about thing B and so on. It finishes telling you everything about one thing before telling you anything about tenet thing. This is so you can look stuff up.

A tutorial on the other hand explains things the other way around... you get a little about thing A then a little about thing B and after getting a little about each you go back and get a little more about A and a little more about B. .

They are opposed approaches because one is a depth first walk while the other is a breadth first walk.

If the only documentation was a tutorial then it would be even worse. Thats what we had before when only the trivial stuff was documented in 0.9.

There should be a tutorial. It should not be the only form of documentation. And if there can only be one so far because its still being written it's better to have it be the reference docs. it is possible to derive information that would be in the tutorial from the reference documentation. it is generally not possible to go the other way around because tutorials typically do not have complete information.

[Camacha]

In general, a reference manual and a tutorial are two utterly different types of documentation. They should not be done using the same document. A reference manual gives a complete list of everything thats true about thing A then a complete list of everything thats true about thing B and so on. It finishes telling you everything about one thing before telling you anything about tenet thing. This is so you can look stuff up.

Mind you, I am not asking for tutorial documentation. I am just saying that the current reference manual is way too sparse to make sense without prior knowledge or experience. Sometimes things are listed in similar ways, while actually doing quite different things. Only by looking in other places can be figured out what is intended and I feel that documentation is not doing its job when that is the case.

Of course, a more comprehensive description of how to use and apply the syntax helps too when people are just getting started, but you should be able to get the information from the documentation. In quite a few places you can, but in some you can not.

Edited June 25, 2014 by Camacha

[Dunbaratu]

Sometimes things are listed in similar ways, while actually doing quite different things.

If you'd like to see the situation rectified you need to be more precise and show where you see this happening.

[Camacha]

If you'd like to see the situation rectified you need to be more precise and show where you see this happening.

In entries like Atmosphere and Engines the actual way to use them is rather unclear. They certainly do not seem to work in the same way as Body entry, while the method of describing things is pretty much the same. The difference is to be guessed by the user, as well as how to actually employ the terms.

In contrast, Lists and Terminal are rather well described in a concise manner, although I would argue that for instance the iterator and Resources return list type are unclear too. There are other examples to be found, but I think the problem is clear.

Edited June 25, 2014 by Camacha

[MrOnak]

On the discussion of where kOS is or should be heading:

As it is there are a lot of low level features missing in kOS (see my github feature requests for what I mean). Simple tools to get stuff done. Before that area hasn't been tidied up (and I applaud the progress the team is making) I think the discussion whether or not high level functionality or info x, y or z should be provided is premature. I'm not saying it shouldn't be done, I'm saying for me personally its not as important as getting the low level issues ironed out.

That said, I love the way that kOS enables (or forces) me to actually understand the math behind orbital mechanics and solving the engineering problems with automatic ascend, descend, executing Hohmann transfers precisely etc. For me personally, that joy I'm having with kOS would probably be a lot diminished if I could write a two-liner to execute a maneuver node perfectly (just an example).

Writing scripts for maneuver node execution, Hohmann transfers etc is relatively trivial once I figured out the math required to do so. kOS isn't lacking much in that regard for me. But that's me. I'm missing a way for other mods to hook into kOS, information where the ascending-/descending nodes of an orbit are, parameter passing between scripts and cores and stuff like that much more, and bugs with vectors and directions hurt me much more than high-ish level functions.

Once those things are rectified, yeah! Why not, add high level stuff to make things easier for people who want it. Nothing wrong with that. But I don't think the time has come yet.

A quick example why I think solving engineering problems are fun here, a script that executes a maneuver node that's given thru parameters:

// calculates the burn time for a given maneuver node
// save as executenode.txt
//
// call as run executenode(ETA, m/s prograde, m/s radial out, m/s normal).
// i.e. run executenode(30, 200, 0, 0).

declare parameter Neta, Nprograde, Nradialout, Nnormal.

sas off. rcs off.

// calibrate throttle
lock throttle to 1. wait 0.1. lock throttle to 0.

// calculate TWR
lock F to (body:mu*(ship:mass*1000)) / (body:radius+body:distance)^2.
lock grav to F / (ship:mass * 1000).
lock TWRmax to ship:maxthrust / (ship:mass * grav).

// calculate maximum acceleration of the craft in m/s
lock maxAcc to ship:maxthrust/ship:mass.
set burnAcc to maxAcc. // save this, since maxAcc will increase as TWR gets better during the burn

// set up the maneuver
set N to node(time:seconds+Neta, Nprograde, Nradialout, Nnormal).
add N.

// calculate burn start and end
set burnTime to N:deltav:mag / burnAcc. // this assumes a constant acceleration as in burnAcc
lock burnStart to time:seconds+(N:eta-(burnTime/2)).
lock burnEnd to burnStart+burnTime.

lock steering to N:burnvector.

wait until time:seconds > burnStart.

until time:seconds > burnend {
	// manipulate the throttle to maintain constant acceleration
	lock throttle to burnAcc/maxAcc.
}

lock throttle to 0.
unlock throttle.
unlock steering.
remove N.

While the script really isn't rocket science I'm very happy how it turned out, I learned quite a bit while writing it and it is really quite precise. That's the joy of kOS for me.

Edited June 25, 2014 by MrOnak

[Dunbaratu]

In entries like Atmosphere and Engines the actual way to use them is rather unclear. They certainly do not seem to work in the same way as Body entry, while the method of describing things is pretty much the same. The difference is to be guessed by the user, as well as how to actually employ the terms.

They work the same once you have such an object. The difference is whether or not there's a way to get the object directly. With Body, you get the Body object directly, so it makes sense to document how under the page for body. With Atmosphere and Engines, there's no way to just get an Engine or an Atmosphere as a first-tier object - they are types that "hang" off of other types, which is why their pages don't describe how you get one. (i.e. You get an atmosphere by getting a body, and then getting the body's :ATM suffix. You get an engine by getting a LIST ENGINES IN FOO and then looking at FOO[0] and FOO[1] and so on for each engine.) The problem is that if I describe how you get one, then I'm not describing that object. I'm describing a different object. "how do you get an Atmosphere" is a property of Body, not a property of Atmosphere. The atmosphere page feels like the wrong place to document it. Similarly "how do you get an Engine" is really a property of the LIST command.

It may feel weird and pedantic but the reason it's like that is because there could be other multiple ways to get to objects later on that I can't predict for. There is *currently* one answer to the question "how do I get to an engine" and that's "you call LIST ENGINES", but if there then were other ways invented later should I keep adding them to the Engine page? It's not *technically* where they belong. There's a programming principle that one should never try to do the same exact thing in two different places if at all possible because it opens up the chance for later edits of the code to cause inconsistency if they only edit one of those places. That same principle applies to making reference documentation. If, say, BODY describes how to get to an ATMOSPHERE, and ATMOSPHERE also describes how you get to itself from a BODY, then the same thing is described in two places.

Perhaps the thing to do is to REMOVE Atmosphere from the flat list on the first index page, so you can't even look at the Atmosphere page unless you got there by first clicking on the Body page and then clicking on the ATM suffix term on that page. Then people wouldn't even see it at all unless they've walked the path that shows them how they get to it.

In contrast, Lists and Terminal are rather well described in a concise manner, although I would argue that for instance the iterator and Resources return list type are unclear too. There are other examples to be found, but I think the problem is clear.

That's because those are inherently top-level topics being described. The question "what object do I use to get to the print command?" isn't even a thing because print is global.

As for Resources.. the page was missing. I discovered this when I was trying to publish out the changes for 0.12.2 and added it.

As for iterator.. I have no clue. It doesn't seem to actually work like a real iterator so I have no clue why the decision was made to expose it to the kOS user. The user can't call "next" or "atEnd" on the iterator, so it's useless in kosscript as an iterator.

[erendrake]

As for iterator.. I have no clue. It doesn't seem to actually work like a real iterator so I have no clue why the decision was made to expose it to the kOS user. The user can't call "next" or "atEnd" on the iterator, so it's useless in kosscript as an iterator.

The reason iterator is exposed is there was no FOR command when i added lists, it only came later in development. As for it being useful as an iterator you use it like so.

LIST ENGINES IN FOO.
SET BAR TO FOO:ITERATOR.
UNTIL(BAR:END) {
    PRINT BAR:VALUE:NAME + " " + BAR:VALUE:MAXTHRUST + " " + BAR:INDEX.
}

This was a little clunky so i added the FOR loop, the iterator does let you access the index however so i left it in and neglected to document it fully.

Edited June 25, 2014 by erendrake

[MrOnak]

Wait what? There is a for loop in kOS?

[erendrake]

Wait what? There is a for loop in kOS?

We do, its an iterator based loop that lets you traverse the LIST structure. I just looked at the user docs and i am shocked (not really) to see that I forgot to add it or it has been removed?

ill just show the example above using FOR

LIST ENGINES IN FOO.
FOR engine in FOO {
    PRINT engine:NAME + " " + engine:MAXTHRUST.
}

the engine variable will only be in scope while you are in the FOR block, then it will be unset.

Edited June 25, 2014 by erendrake

[MrOnak]

ah that one... damnit

I knew about that for-in. I was thinking more in terms of for i=0. i < ....... i++ {...}

oh well

[Dunbaratu]

We do, its an iterator based loop that lets you traverse the LIST structure. I just looked at the user docs and i am shocked (not really) to see that I forgot to add it or it has been removed?

Neither. It's documented but not under "flow control" because of the fact that it's not implemented like a real FOR loop in a generic way. It's not a generic flow control operartor and only works on LIST, so it's documented under LIST. There'd be no point in knowing it exists if you didn't know about LISTs, given its current limited implementation.

[Dunbaratu]

LIST ENGINES IN FOO.
SET BAR TO FOO:ITERATOR.
UNTIL(BAR:END) {
    PRINT BAR:VALUE:NAME + " " + BAR:VALUE:MAXTHRUST + " " + BAR:INDEX.
}

Wait, so where's the increment in that example? You check for if it's at the end, and you obtain the value and the current index, but where does it increment to the next element? That's why I didn't document it - because I don't get how it works without a 'next' operator.

[erendrake]

Neither. It's documented but not under "flow control" because of the fact that it's not implemented like a real FOR loop in a generic way. It's not a generic flow control operartor and only works on LIST, so it's documented under LIST. There'd be no point in knowing it exists if you didn't know about LISTs, given its current limited implementation.

I disagree, it operates on all of the collections that the language has and it does affect the script control flow. just because it is a collection controlled loop doesnt make it not a loop.

Edited June 25, 2014 by erendrake

[erendrake]

Wait, so where's the increment in that example? You check for if it's at the end, and you obtain the value and the current index, but where does it increment to the next element? That's why I didn't document it - because I don't get how it works without a 'next' operator.

end is the next. i was going to make it 'next' and have it return true at the end but i didnt like the way it worked with our UNTIL statement.

Collections were the very first thing change I made after kevin left so I was trying to work within his system as closely as possible.

Edited June 25, 2014 by erendrake

[Dunbaratu]

all of the collections that the language has.

All one of them.

When there's only one example to go from, and you didn't document your intent, then I can't assume it was your intent to make it work with all collections or work with ONE collection. Given that there only is one collection the two look identical in intent at the moment.

[IronGremlin]

They work the same once you have such an object. The difference is whether or not there's a way to get the object directly. With Body, you get the Body object directly, so it makes sense to document how under the page for body. With Atmosphere and Engines, there's no way to just get an Engine or an Atmosphere as a first-tier object - they are types that "hang" off of other types, which is why their pages don't describe how you get one. (i.e. You get an atmosphere by getting a body, and then getting the body's :ATM suffix. You get an engine by getting a LIST ENGINES IN FOO and then looking at FOO[0] and FOO[1] and so on for each engine.) The problem is that if I describe how you get one, then I'm not describing that object. I'm describing a different object. "how do you get an Atmosphere" is a property of Body, not a property of Atmosphere. The atmosphere page feels like the wrong place to document it. Similarly "how do you get an Engine" is really a property of the LIST command.

It may feel weird and pedantic but the reason it's like that is because there could be other multiple ways to get to objects later on that I can't predict for. There is *currently* one answer to the question "how do I get to an engine" and that's "you call LIST ENGINES", but if there then were other ways invented later should I keep adding them to the Engine page? It's not *technically* where they belong. There's a programming principle that one should never try to do the same exact thing in two different places if at all possible because it opens up the chance for later edits of the code to cause inconsistency if they only edit one of those places. That same principle applies to making reference documentation. If, say, BODY describes how to get to an ATMOSPHERE, and ATMOSPHERE also describes how you get to itself from a BODY, then the same thing is described in two places.

Perhaps the thing to do is to REMOVE Atmosphere from the flat list on the first index page, so you can't even look at the Atmosphere page unless you got there by first clicking on the Body page and then clicking on the ATM suffix term on that page. Then people wouldn't even see it at all unless they've walked the path that shows them how they get to it.

That's because those are inherently top-level topics being described. The question "what object do I use to get to the print command?" isn't even a thing because print is global.

As for Resources.. the page was missing. I discovered this when I was trying to publish out the changes for 0.12.2 and added it.

As for iterator.. I have no clue. It doesn't seem to actually work like a real iterator so I have no clue why the decision was made to expose it to the kOS user. The user can't call "next" or "atEnd" on the iterator, so it's useless in kosscript as an iterator.

If your dead set on not including any executable code for reference, maybe you could at least link to a description of what "objects" are, and the syntax surrounding them? Calling out the syntax examples as syntax examples may also help people who are new to programming - it's easy to forget once you've spent enough time learning different languages, but typical code documentation practices are super unintuitive.

[erendrake]

If your dead set on not including any executable code for reference, maybe you could at least link to a description of what "objects" are, and the syntax surrounding them? Calling out the syntax examples as syntax examples may also help people who are new to programming - it's easy to forget once you've spent enough time learning different languages, but typical code documentation practices are super unintuitive.

I am not deadset on this, I would love to have tutorials on how to use each structure and function. Right now we just dont have the bandwidth, Steven made a great video about the new VecDraw features and i hope in the future we have more of these.

I think that Steven is right that if you are only going to have one kind of documentation, the reference doc would be it. That being said we should soon have a much more complete reference doc and might be able to branch out, esp if more people get involved

[Dunbaratu]

end is the next. i was going to make it 'next' and have it return true at the end but i didnt like the way it worked with our UNTIL statement.

Collections were the very first thing change I made after kevin left so I was trying to work within his system as closely as possible.

That is extremely counter-intuitive. Having an operator called "end" that actually does "next" with the side effect of also checking for "end" seems backward. What would make more sense and be less confusing for people would be to have the operator called "next", since that's what it actually *does* and have the fact that it can check for end be the side effect. (Rather than have the check be the 'named' effect and the increment be the unnamed side effect).

Although I don't see why we can't have both. Most iterators do have both. You can perform 'next' and check its return code to see if it worked, or you can check for 'end' and see if it's at end without actually incrementing it if all you wanted to do was perform the check.

It also seems backward to have the incrementing operator return false when it WORKS and true when it doesn't, although I can see why you did that given that kOS has UNTIL loops instead of WHILE loops.

For iterators to actually be good to use, I think they'd need separate next and end operators. The side effect that Next also returns a boolean for whether it worked or not *could* be used as the check for at-end, or you could call END explicitly to check. I think that would have a lot less hidden behaviors that way.

Edited June 25, 2014 by Steven Mading
prev post didn't look like it worked so I repeated it here. After looking I saw that it did so I cut the repeated content.

[erendrake]

All one of them.

When there's only one example to go from, and you didn't document your intent, then I can't assume it was your intent to make it work with all collections or work with ONE collection. Given that there only is one collection the two look identical in intent at the moment.

thats fair, and to be honest i dont know if we will have another collection type anytime soon? I also wouldnt mind a python like range loop

FOR foo IN RANGE(0,100) {
    print foo.
}

[Dunbaratu]

I think that Steven is right that if you are only going to have one kind of documentation, the reference doc would be it. That being said we should soon have a much more complete reference doc and might be able to branch out, esp if more people get involved

One thing I *am* dead set against is writing the same information in more than one place. The proper state of mind to have if you catch yourself doing that is not "the information in these two places *might* become contradictory some day if I'm not careful." The proper state of mind to have is "the information in these two places *will* become contradictory some day. It's just a matter of time." It's the sort of defensive pessimism that keeps you from shooting yourself in the foot.

If it makes sense that someone in another location in the docs might want the same information, then it should be linked to from there, not cut-n-pasted to there.

[erendrake]

That is extremely counter-intuitive.

Nothing is set in stone, and we can surely add to the iterator type, and i was at the time very closely coupling it to the UNTIL statement to have the line read

    UNTIL (var:END) {

so "until the end of the list run this block" made sense to me. It also had the side affect of getting me a list to play with while i worked on FOR

[erendrake]

One thing I *am* dead set against is writing the same information in more than one place.

I agree, I would say that a nice video on how to loop over the engine list is different "information" or at least different context than a ref doc of the engine structure. I abhor duplication of effort and data

[Dunbaratu]

I would like there to exist some sort of "lesson plan" set of documents to get people started on kOS. The hard part is deciding how far into it to go before it becomes just handing people the answer on a platter, which is not what kOS is supposed to be. If you wanted an autopilot that does everything for you without much player agency you'd probably be using Mechjeb. kOS is for the purpose of writing YOUR autopilot YOUR way, which makes the question of what do you put in tutorial examples a bit of a fine line to walk. There should be SOME helpful examples, but none of them that work so well that you can just cut and paste them and have them work perfectly.

I was contemplating what would go into a set of quick example scripts and where that fine line should actually be. There's also the issue of public image and advertising. Tutorial examples would be the very first thing a person new to kOS will see. Therefore the examples need to be sufficiently nifty that a person looking at them will go "wow that's cool" rather than "what a useless piece of junk this is", and yet at the same time they shouldn't be doing things like just handing the answer working out of the box for complex operations like "this is how you dock", or "this script will land an airplane on the KSC runway".

There is a place for more complex examples like that, but I think it's not in the documentation but rather in repository projects like SolarLiner's kOS repository.

For one thing, a really good piece of kOS code that actually works universally and does the job smartly is a thing to brag about and show off. The documentation shouldn't be doing that sort of bragging and showing off. The examples will need to be crude and simplistic and full of caveats.

[Dunbaratu]

I agree, I would say that a nice video on how to loop over the engine list is different "information" or at least different context than a ref doc of the engine structure. I abhor duplication of effort and data

That's not the sort of duplication I meant. I was referring to things like having the fact that BODY:ATM is how you obtain an Atmosphere object being described both in the reference documentation for Body and the reference documentation for Atmosphere.

[MrOnak]

@devs I'll be more than happy to contribute to kOS by providing documentation. If you're interested we should probably set up some sort of more direct communication over the weekend.